Leptonica 1.68
C Image Processing Library

bbuffer.c File Reference

Implements ByteBuffer, a byte queue; used for zlib comp/decomp in memory. More...

#include <string.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

BBUFFERbbufferCreate (l_uint8 *indata, l_int32 nalloc)
void bbufferDestroy (BBUFFER **pbb)
l_uint8bbufferDestroyAndSaveData (BBUFFER **pbb, size_t *pnbytes)
l_int32 bbufferRead (BBUFFER *bb, l_uint8 *src, l_int32 nbytes)
l_int32 bbufferReadStream (BBUFFER *bb, FILE *fp, l_int32 nbytes)
l_int32 bbufferExtendArray (BBUFFER *bb, l_int32 nbytes)
l_int32 bbufferWrite (BBUFFER *bb, l_uint8 *dest, size_t nbytes, size_t *pnout)
l_int32 bbufferWriteStream (BBUFFER *bb, FILE *fp, size_t nbytes, size_t *pnout)
l_int32 bbufferBytesToWrite (BBUFFER *bb, size_t *pnbytes)

Variables

static const l_int32 INITIAL_BUFFER_ARRAYSIZE = 1024

Detailed Description

Implements ByteBuffer, a byte queue; used for zlib comp/decomp in memory.

    Create/Destroy BBuffer
        BBUFFER   *bbufferCreate()
        void      *bbufferDestroy()
        l_uint8   *bbufferDestroyAndSaveData()

    Operations to read data TO a BBuffer
        l_int32    bbufferRead()
        l_int32    bbufferReadStream()
        l_int32    bbufferExtendArray()

    Operations to write data FROM a BBuffer
        l_int32    bbufferWrite()
        l_int32    bbufferWriteStream()

    Accessors
        l_int32    bbufferBytesToWrite()


  The bbuffer is an implementation of a byte queue.
  The bbuffer holds a byte array from which bytes are
  processed in a first-in/first-out fashion.  As with
  any queue, bbuffer maintains two "pointers," one to the
  tail of the queue (where you read new bytes onto it)
  and one to the head of the queue (where you start from
  when writing bytes out of it. 

  The queue can be visualized:

    
byte 0                                           byte (nalloc - 1)
     |                                                |
     --------------------------------------------------
               H                             T
     [   aw   ][  bytes currently on queue  ][  anr   ] 
  
     ---:  all allocated data in bbuffer
     H:    queue head (ptr to next byte to be written out)
     T:    queue tail (ptr to first byte to be written to) 
     aw:   already written from queue
     anr:  allocated but not yet read to

  The purpose of bbuffer is to allow you to safely read
  bytes in, and to sequentially write them out as well.
  In the process of writing bytes out, you don't actually
  remove the bytes in the array; you just move the pointer
  (nwritten) which points to the head of the queue.  In
  the process of reading bytes in, you sometimes need to
  expand the array size.  If a read is performed after a
  write, so that the head of the queue is not at the
  beginning of the array, the bytes already written are
  first removed by copying the others over them; then the
  new bytes are read onto the tail of the queue.

  Note that the meaning of "read into" and "write from"
  the bbuffer is OPPOSITE to that for a stream, where
  you read "from" a stream and write "into" a stream.
  As a mnemonic for remembering the direction:
      - to read bytes from a stream into the bbuffer,
        you call fread on the stream
      - to write bytes from the bbuffer into a stream,
        you call fwrite on the stream

  See zlibmem.c for an example use of bbuffer, where we
  compress and decompress an array of bytes in memory.

Definition in file bbuffer.c.


Function Documentation

BBUFFER* bbufferCreate ( l_uint8 indata,
l_int32  nalloc 
)

bbufferCreate()

Input: buffer address in memory (<optional>) size of byte array to be alloc'd (0 for default) Return: bbuffer, or null on error

Notes: (1) If a buffer address is given, you should read all the data in. (2) Allocates a bbuffer with associated byte array of the given size. If a buffer address is given, it then reads the number of bytes into the byte array.

Definition at line 108 of file bbuffer.c.

References ByteBuffer::array, CALLOC, ERROR_PTR, INITIAL_BUFFER_ARRAYSIZE, ByteBuffer::n, L_Bytea::nalloc, ByteBuffer::nalloc, NULL, ByteBuffer::nwritten, and PROCNAME.

Referenced by ccbaWriteStream(), main(), zlibCompress(), and zlibUncompress().

void bbufferDestroy ( BBUFFER **  pbb)

bbufferDestroy()

Input: &bbuffer (<to be="" nulled>="">) Return: void

Notes: (1) Destroys the byte array in the bbuffer and then the bbuffer; then nulls the contents of the input ptr.

Definition at line 147 of file bbuffer.c.

References ByteBuffer::array, FREE, L_WARNING, NULL, and PROCNAME.

Referenced by bbufferDestroyAndSaveData(), main(), zlibCompress(), and zlibUncompress().

l_uint8* bbufferDestroyAndSaveData ( BBUFFER **  pbb,
size_t *  pnbytes 
)

bbufferDestroyAndSaveData()

Input: &bbuffer (<to be="" nulled>="">) &nbytes (<return> number of bytes saved in array) Return: barray (newly allocated array of data)

Notes: (1) Copies data to newly allocated array; then destroys the bbuffer.

Definition at line 181 of file bbuffer.c.

References ByteBuffer::array, bbufferDestroy(), CALLOC, L_WARNING, ByteBuffer::n, NULL, ByteBuffer::nwritten, and PROCNAME.

Referenced by ccbaWriteStream(), zlibCompress(), and zlibUncompress().

l_int32 bbufferRead ( BBUFFER bb,
l_uint8 src,
l_int32  nbytes 
)

bbufferRead()

Input: bbuffer src (source memory buffer from which bytes are read) nbytes (bytes to be read) Return: 0 if OK, 1 on error

Notes: (1) For a read after write, first remove the written bytes by shifting the unwritten bytes in the array, then check if there is enough room to add the new bytes. If not, realloc with bbufferExpandArray(), resulting in a second writing of the unwritten bytes. While less efficient, this is simpler than making a special case of reallocNew().

Definition at line 239 of file bbuffer.c.

References ByteBuffer::array, bbufferExtendArray(), ERROR_INT, L_MAX, ByteBuffer::n, ByteBuffer::nalloc, ByteBuffer::nwritten, and PROCNAME.

Referenced by ccbaWriteStream(), main(), zlibCompress(), and zlibUncompress().

l_int32 bbufferReadStream ( BBUFFER bb,
FILE *  fp,
l_int32  nbytes 
)

bbufferReadStream()

Input: bbuffer fp (source stream from which bytes are read) nbytes (bytes to be read) Return: 0 if OK, 1 on error

Definition at line 286 of file bbuffer.c.

References ByteBuffer::array, bbufferExtendArray(), ERROR_INT, L_MAX, ByteBuffer::n, ByteBuffer::nalloc, ByteBuffer::nwritten, and PROCNAME.

l_int32 bbufferExtendArray ( BBUFFER bb,
l_int32  nbytes 
)

bbufferExtendArray()

Input: bbuffer nbytes (number of bytes to extend array size) Return: 0 if OK, 1 on error

Notes: (1) reallocNew() copies all bb->nalloc bytes, even though only bb->n are data.

Definition at line 336 of file bbuffer.c.

References ByteBuffer::array, ERROR_INT, ByteBuffer::nalloc, NULL, PROCNAME, and reallocNew().

Referenced by bbufferRead(), and bbufferReadStream().

l_int32 bbufferWrite ( BBUFFER bb,
l_uint8 dest,
size_t  nbytes,
size_t *  pnout 
)

bbufferWrite()

Input: bbuffer dest (dest memory buffer to which bytes are written) nbytes (bytes requested to be written) &nout (<return> bytes actually written) Return: 0 if OK, 1 on error

Definition at line 368 of file bbuffer.c.

References ByteBuffer::array, ERROR_INT, L_MIN, ByteBuffer::n, ByteBuffer::nwritten, and PROCNAME.

Referenced by main(), zlibCompress(), and zlibUncompress().

l_int32 bbufferWriteStream ( BBUFFER bb,
FILE *  fp,
size_t  nbytes,
size_t *  pnout 
)

bbufferWriteStream()

Input: bbuffer fp (dest stream to which bytes are written) nbytes (bytes requested to be written) &nout (<return> bytes actually written) Return: 0 if OK, 1 on error

Definition at line 420 of file bbuffer.c.

References ByteBuffer::array, ERROR_INT, L_MIN, ByteBuffer::n, ByteBuffer::nwritten, and PROCNAME.

Referenced by main().

l_int32 bbufferBytesToWrite ( BBUFFER bb,
size_t *  pnbytes 
)

bbufferBytesToWrite()

Input: bbuffer &nbytes (<return>) Return: 0 if OK; 1 on error

Definition at line 474 of file bbuffer.c.

References ERROR_INT, ByteBuffer::n, ByteBuffer::nwritten, and PROCNAME.


Variable Documentation

const l_int32 INITIAL_BUFFER_ARRAYSIZE = 1024 [static]

Definition at line 88 of file bbuffer.c.

Referenced by bbufferCreate().

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines