Simple Buffers

Data Structures
struct	BufferHeader
struct	BufIov

Typedefs
typedef struct BufIov	BufIov

Functions
Buffer	bufCreate (size_t size)
Buffer	bufTryCreate (size_t size)
void	bufResize (Buffer *buf, size_t newsize)
bool	bufTryResize (Buffer *buf, size_t newsize)
size_t	bufLen (Buffer buf)
void	bufClear (Buffer buf)
uint8 *	bufReserve (Buffer *buf, size_t len)
void	bufAppendBytes (Buffer *buf, _In_reads_bytes_opt_(len) const void *data, size_t len)
void	bufAppend (Buffer *buf, Buffer src)
void	bufAppendC (Buffer *buf, Buffer *src)
void	bufDestroy (Buffer *buf)

Detailed Description

Simple dynamically-sized buffers with header metadata.

Buffers are heap-allocated structures that store arbitrary binary data along with size and length tracking. They support resizing and optional allocation.

Example:

Buffer buf = bufCreate(1024);
memcpy(buf->data, mydata, datalen);
buf->len = datalen;
bufResize(&buf, 2048);
bufDestroy(&buf);

Typedef Documentation

BufIov

typedef struct BufIov BufIov

Platform-neutral scatter/gather vector.

Describes a single contiguous region of memory as part of a vectored I/O operation. This is not the same layout as the OS's own type (struct iovec on Unix, WSABUF on Windows) – translate into the platform's array immediately before the syscall that needs it.

See also

bufchainGatherIov

Function Documentation

bufAppend()

void bufAppend	(	Buffer *	buf,
		Buffer	src
	)

void bufAppend(Buffer* buf, Buffer src)

Appends the contents of one buffer to another.

Parameters

buf	Pointer to buffer pointer to append to (may be NULL)
src	Buffer to copy the bytes from; NULL or empty appends nothing

Example:

bufAppend(&dest, src);
bufDestroy(&src);

bufAppendBytes()

void bufAppendBytes	(	Buffer *	buf,
		_In_reads_bytes_opt_(len) const void *	data,
		size_t	len
	)

void bufAppendBytes(Buffer* buf, const void* data, size_t len)

Appends raw bytes to the end of a buffer.

The buffer grows if it has to, and creates one if the pointer is NULL.

Parameters

buf	Pointer to buffer pointer to append to (may be NULL)
data	Bytes to append
len	Number of bytes

Example:

Buffer buf = 0;
bufAppendBytes(&buf, "hello", 5);

bufAppendC()

void bufAppendC	(	Buffer *	buf,
		Buffer *	src
	)

void bufAppendC(Buffer* buf, Buffer* src)

Appends one buffer to another and destroys the source.

The source is destroyed and its pointer set to NULL, so it must not be used again. When the destination is empty this hands its memory over instead of copying the bytes, which is what makes chaining these cheap.

Parameters

buf	Pointer to buffer pointer to append to (may be NULL)
src	Pointer to the buffer to append and destroy

Example:

Buffer part = bufCreate(64);
...fill part...
bufAppendC(&whole, &part);   // part is now NULL

bufClear()

void bufClear ( Buffer  buf )

inline

void bufClear(Buffer buf)

Discards a buffer's contents without freeing its memory.

The allocation is kept, so a buffer used over and over as scratch space stops reallocating once it has grown to the size it needs.

Parameters

buf	Buffer to empty; NULL is ignored

Definition at line 110 of file buffer.h.

bufCreate()

Buffer bufCreate

(

size_t

size

)

Buffer bufCreate(size_t size)

Create a new buffer with the specified size.

Parameters

size	The size in bytes to allocate for the buffer

Returns

A newly allocated buffer (never NULL)

bufDestroy()

void bufDestroy

(

Buffer *

buf

)

void bufDestroy(Buffer* buf)

Destroy a buffer and free its memory.

Sets the buffer pointer to NULL after freeing.

Parameters

buf	Pointer to buffer pointer to destroy

bufLen()

size_t bufLen ( Buffer  buf )

inline

size_t bufLen(Buffer buf)

Number of valid bytes in a buffer.

Parameters

buf	Buffer to measure; NULL counts as empty

Returns

Length of the valid data

Definition at line 97 of file buffer.h.

bufReserve()

uint8 * bufReserve	(	Buffer *	buf,
		size_t	len
	)

uint8* bufReserve(Buffer* buf, size_t len)

Makes room for len more bytes and returns where to write them.

The buffer grows if it has to, and creates one if the pointer is NULL. The length is left alone, so add to it yourself once the bytes are written.

Parameters

buf	Pointer to buffer pointer to reserve space in (may be NULL)
len	Number of bytes to make room for

Returns

Pointer to the first reserved byte

Example:

uint8 *p = bufReserve(&buf, 4);
memcpy(p, "abcd", 4);
buf->len += 4;

bufResize()

void bufResize	(	Buffer *	buf,
		size_t	newsize
	)

void bufResize(Buffer* buf, size_t newsize)

Resize an existing buffer to a new size.

If the buffer pointer is NULL, creates a new buffer with the specified size. If resizing smaller than current length, the length is truncated.

Parameters

buf	Pointer to buffer pointer to resize (may be NULL)
newsize	New size in bytes for the buffer

bufTryCreate()

Buffer bufTryCreate

(

size_t

size

)

Buffer bufTryCreate(size_t size)

Create a new buffer with optional allocation (may fail).

Uses optional allocation which will return NULL on out-of-memory instead of terminating the program. Useful for large allocations that may fail.

Parameters

size	The size in bytes to allocate for the buffer

Returns

A newly allocated buffer, or NULL if allocation failed

bufTryResize()

bool bufTryResize	(	Buffer *	buf,
		size_t	newsize
	)

bool bufTryResize(Buffer* buf, size_t newsize)

Resize an existing buffer with optional allocation (may fail).

Like bufResize() but uses optional allocation and returns false on failure instead of terminating the program.

Parameters

buf	Pointer to buffer pointer to resize (may be NULL)
newsize	New size in bytes for the buffer

Returns

true if resize succeeded, false if allocation failed