Leptonica  1.82.0
Image processing and image analysis suite
bbuffer.c File Reference
#include <string.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

L_BBUFFERbbufferCreate (const l_uint8 *indata, l_int32 nalloc)
 
void bbufferDestroy (L_BBUFFER **pbb)
 
l_uint8 * bbufferDestroyAndSaveData (L_BBUFFER **pbb, size_t *pnbytes)
 
l_ok bbufferRead (L_BBUFFER *bb, l_uint8 *src, l_int32 nbytes)
 
l_ok bbufferReadStream (L_BBUFFER *bb, FILE *fp, l_int32 nbytes)
 
l_ok bbufferExtendArray (L_BBUFFER *bb, l_int32 nbytes)
 
l_ok bbufferWrite (L_BBUFFER *bb, l_uint8 *dest, size_t nbytes, size_t *pnout)
 
l_ok bbufferWriteStream (L_BBUFFER *bb, FILE *fp, size_t nbytes, size_t *pnout)
 

Variables

static const l_uint32 MaxArraySize = 1000000000
 
static const l_int32 InitialArraySize = 1024
 

Detailed Description

     Create/Destroy BBuffer
         L_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()
   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.
   We can also use the bbuffer trivially to read from stdin
   into memory; e.g., to capture bytes piped from the stdout
   of another program.  This is equivalent to repeatedly
   calling bbufferReadStream() until the input queue is empty.
   This is implemented in l_binaryReadStream().

Definition in file bbuffer.c.

Function Documentation

◆ bbufferCreate()

L_BBUFFER* bbufferCreate ( const l_uint8 *  indata,
l_int32  nalloc 
)

bbufferCreate()

Parameters
[in]indataaddress in memory [optional]
[in]nallocsize of byte array to be alloc'd 0 for default
Returns
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 130 of file bbuffer.c.

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

◆ bbufferDestroy()

void bbufferDestroy ( L_BBUFFER **  pbb)

bbufferDestroy()

Parameters
[in,out]pbbwill be set to null before returning
Returns
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 172 of file bbuffer.c.

References L_ByteBuffer::array.

Referenced by bbufferDestroyAndSaveData(), l_binaryReadStream(), and zlibUncompress().

◆ bbufferDestroyAndSaveData()

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

bbufferDestroyAndSaveData()

Parameters
[in,out]pbbinput data buffer; will be nulled
[out]pnbytesnumber of bytes saved in array
Returns
barray newly allocated array of data
Notes:
     (1) Copies data to newly allocated array; then destroys the bbuffer.

Definition at line 206 of file bbuffer.c.

References L_ByteBuffer::array, bbufferDestroy(), L_ByteBuffer::n, and L_ByteBuffer::nwritten.

Referenced by zlibUncompress().

◆ bbufferExtendArray()

l_ok bbufferExtendArray ( L_BBUFFER bb,
l_int32  nbytes 
)

bbufferExtendArray()

Parameters
[in]bbbbuffer
[in]nbytesnumber of bytes to extend array size
Returns
0 if OK, 1 on error
Notes:
     (1) reallocNew() copies all bb->nalloc bytes, even though
         only bb->n are data.

Definition at line 363 of file bbuffer.c.

References L_ByteBuffer::array, L_ByteBuffer::nalloc, and reallocNew().

Referenced by bbufferRead(), bbufferReadStream(), and l_binaryReadStream().

◆ bbufferRead()

l_ok bbufferRead ( L_BBUFFER bb,
l_uint8 *  src,
l_int32  nbytes 
)

bbufferRead()

Parameters
[in]bbbbuffer
[in]srcsource memory buffer from which bytes are read
[in]nbytesbytes to be read
Returns
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 265 of file bbuffer.c.

References L_ByteBuffer::array, bbufferExtendArray(), L_ByteBuffer::n, L_ByteBuffer::nalloc, and L_ByteBuffer::nwritten.

Referenced by ccbaWriteStream(), and zlibUncompress().

◆ bbufferReadStream()

l_ok bbufferReadStream ( L_BBUFFER bb,
FILE *  fp,
l_int32  nbytes 
)

bbufferReadStream()

Parameters
[in]bbbbuffer
[in]fpsource stream from which bytes are read
[in]nbytesbytes to be read
Returns
0 if OK, 1 on error

Definition at line 311 of file bbuffer.c.

References L_ByteBuffer::array, bbufferExtendArray(), L_ByteBuffer::n, L_ByteBuffer::nalloc, and L_ByteBuffer::nwritten.

◆ bbufferWrite()

l_ok bbufferWrite ( L_BBUFFER bb,
l_uint8 *  dest,
size_t  nbytes,
size_t *  pnout 
)

bbufferWrite()

Parameters
[in]bbbbuffer
[in]destdest memory buffer to which bytes are written
[in]nbytesbytes requested to be written
[out]pnoutbytes actually written
Returns
0 if OK, 1 on error

Definition at line 394 of file bbuffer.c.

References L_ByteBuffer::array, L_ByteBuffer::n, and L_ByteBuffer::nwritten.

Referenced by zlibUncompress().

◆ bbufferWriteStream()

l_ok bbufferWriteStream ( L_BBUFFER bb,
FILE *  fp,
size_t  nbytes,
size_t *  pnout 
)

bbufferWriteStream()

Parameters
[in]bbbbuffer
[in]fpdest stream to which bytes are written
[in]nbytesbytes requested to be written
[out]pnoutbytes actually written
Returns
0 if OK, 1 on error

Definition at line 446 of file bbuffer.c.

References L_ByteBuffer::array, L_ByteBuffer::n, and L_ByteBuffer::nwritten.

Variable Documentation

◆ InitialArraySize

const l_int32 InitialArraySize = 1024
static

n'importe quoi

Definition at line 109 of file bbuffer.c.