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

Functions
L_BBUFFER *	bbufferCreate (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]	indata	address in memory [optional]
[in]	nalloc	size 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.

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

◆ bbufferDestroy()

void bbufferDestroy ( L_BBUFFER ** pbb )

bbufferDestroy()

Parameters

[in,out] pbb will 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 170 of file bbuffer.c.

References L_ByteBuffer::array.

Referenced by bbufferDestroyAndSaveData().

◆ bbufferDestroyAndSaveData()

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

bbufferDestroyAndSaveData()

Parameters

[in,out]	pbb	input data buffer; will be nulled
[out]	pnbytes	number 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 202 of file bbuffer.c.

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

◆ bbufferExtendArray()

l_ok bbufferExtendArray	(	L_BBUFFER *	bb,
		l_int32	nbytes )

bbufferExtendArray()

Parameters

[in]	bb	bbuffer
[in]	nbytes	number 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 353 of file bbuffer.c.

References L_ByteBuffer::array, and L_ByteBuffer::nalloc.

Referenced by bbufferRead(), and bbufferReadStream().

◆ bbufferRead()

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

bbufferRead()

Parameters

[in]	bb	bbuffer
[in]	src	source memory buffer from which bytes are read
[in]	nbytes	bytes 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 259 of file bbuffer.c.

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