![]() |
Leptonica
1.82.0
Image processing and image analysis suite
|
#include <string.h>
#include "allheaders.h"
Go to the source code of this file.
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 |
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:
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.byte 0 byte (nalloc - 1)| |--------------------------------------------------H T[ aw ][ bytes currently on queue ][ anr ]---: all allocated data in bbufferH: 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 queueanr: allocated but not yet read to
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.
L_BBUFFER* bbufferCreate | ( | const l_uint8 * | indata, |
l_int32 | nalloc | ||
) |
[in] | indata | address in memory [optional] |
[in] | nalloc | size of byte array to be alloc'd 0 for default |
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().
void bbufferDestroy | ( | L_BBUFFER ** | pbb | ) |
[in,out] | pbb | will be set to null before returning |
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().
l_uint8* bbufferDestroyAndSaveData | ( | L_BBUFFER ** | pbb, |
size_t * | pnbytes | ||
) |
[in,out] | pbb | input data buffer; will be nulled |
[out] | pnbytes | number of bytes saved in array |
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().
l_ok bbufferExtendArray | ( | L_BBUFFER * | bb, |
l_int32 | nbytes | ||
) |
[in] | bb | bbuffer |
[in] | nbytes | number of bytes to extend array size |
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().
l_ok bbufferRead | ( | L_BBUFFER * | bb, |
l_uint8 * | src, | ||
l_int32 | nbytes | ||
) |
[in] | bb | bbuffer |
[in] | src | source memory buffer from which bytes are read |
[in] | nbytes | bytes to be read |
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().
l_ok bbufferReadStream | ( | L_BBUFFER * | bb, |
FILE * | fp, | ||
l_int32 | nbytes | ||
) |
[in] | bb | bbuffer |
[in] | fp | source stream from which bytes are read |
[in] | nbytes | bytes to be read |
Definition at line 311 of file bbuffer.c.
References L_ByteBuffer::array, bbufferExtendArray(), L_ByteBuffer::n, L_ByteBuffer::nalloc, and L_ByteBuffer::nwritten.
l_ok bbufferWrite | ( | L_BBUFFER * | bb, |
l_uint8 * | dest, | ||
size_t | nbytes, | ||
size_t * | pnout | ||
) |
[in] | bb | bbuffer |
[in] | dest | dest memory buffer to which bytes are written |
[in] | nbytes | bytes requested to be written |
[out] | pnout | bytes actually written |
Definition at line 394 of file bbuffer.c.
References L_ByteBuffer::array, L_ByteBuffer::n, and L_ByteBuffer::nwritten.
Referenced by zlibUncompress().
l_ok bbufferWriteStream | ( | L_BBUFFER * | bb, |
FILE * | fp, | ||
size_t | nbytes, | ||
size_t * | pnout | ||
) |
[in] | bb | bbuffer |
[in] | fp | dest stream to which bytes are written |
[in] | nbytes | bytes requested to be written |
[out] | pnout | bytes actually written |
Definition at line 446 of file bbuffer.c.
References L_ByteBuffer::array, L_ByteBuffer::n, and L_ByteBuffer::nwritten.