#include "vl_numtypes.h"
#include "vl_memory.h"

Include dependency graph for vl_buffer.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	vl_buffer
	A multi-purpose byte buffer. More...

Macros
#define	vlBufferInit(bufferPtr) vlBufferInitSz(bufferPtr, VL_DEFAULT_MEMORY_SIZE)
	Initializes a buffer instance for the first time. This will create the initial allocation for the default capacity.

Functions
vl_buffer *	vlBufferNew (void)
	Allocates a new buffer, and initializes it with the default capacity. The buffer must be deleted with vlBufferDelete(...) when it is no longer being used to avoid leaking memory.

vl_buffer *	vlBufferNewSz (vl_memsize_t initialCapacity)
	Allocates a new buffer, and initializes it with a capacity of N bytes. The buffer must be deleted with vlBufferDelete(...) when it is no longer being used to avoid leaking memory.

void	vlBufferInitSz (vl_buffer *buffer, vl_memsize_t initialCapacity)
	Initializes a buffer instance for the first time. This will create the initial allocation for the specified capacity.

void	vlBufferReset (vl_buffer *buffer)
	Resets the state of the specified buffer, setting the offset integer to zero. This will re-allocate the buffer to hold the default capacity.

void	vlBufferResetSz (vl_buffer *buffer, vl_memsize_t newCapacity)
	Resets the state of the specified buffer, setting the offset integer to zero. This will re-allocate the buffer to hold the specified capacity.

void	vlBufferClear (vl_buffer *buffer)
	Sets the entirety of the buffer to zero. Also resets offset and computed size.

void	vlBufferShrinkToFit (vl_buffer *buffer)
	Resizes the specified buffer to hold a capacity equal to the current size.

vl_buffer *	vlBufferClone (const vl_buffer src, vl_buffer dest)
	Clones the source buffer to the destination buffer.

vl_memsize_t	vlBufferCopy (vl_buffer src, vl_buffer dest, vl_memsize_t len)
	Copies a series of bytes from one buffer to another.

vl_memsize_t	vlBufferWrite (vl_buffer buffer, vl_memsize_t size, const void src)
	Performs a copy from the specified source pointer into the buffer. The bytes are written at the current offset integer belonging to the buffer state. This function will resize the buffer when necessary. The buffer offset will be incremented by the total number of bytes written.

vl_memsize_t	vlBufferRead (vl_buffer buffer, vl_memsize_t size, void dest)
	Copies bytes from the buffer to the specified destination. Performs a copy from the buffer to the specified destination pointer. This will increment the buffer offset.

void	vlBufferSeek (vl_buffer *buffer, vl_uintptr_t offset)
	Sets the buffer offset relative to the beginning of the allocation.

void	vlBufferSeekRelative (vl_buffer *buffer, vl_intptr_t offset)
	Seeks the internal offset relative to the current offset. Adds the specified offset to the offset integer belonging to the buffer state.

void	vlBufferSeekBegin (vl_buffer *buffer)
	Seeks the internal offset to the beginning of the buffer. Moves the offset integer belonging to the buffer state to the beginning of the allocation (e.g, zero)

void	vlBufferSeekEnd (vl_buffer *buffer)
	Seeks the internal offset to the end of the buffer. Moves the offset integer belonging to the buffer state to the end of the allocation (e.g, the buffer size)

vl_transient *	vlBufferBegin (vl_buffer *buffer)
	Returns a pointer to the beginning of the buffer allocation.

vl_transient *	vlBufferEnd (vl_buffer *buffer)
	Returns a pointer to the end of the buffer allocation.

void	vlBufferFree (vl_buffer *buffer)
	Frees the specified buffer.

void	vlBufferDelete (vl_buffer *buffer)
	Deletes the specified buffer.

Data Structure Documentation

◆ vl_buffer

struct vl_buffer

A multi-purpose byte buffer.

Buffers are the most basic data structure used by the VL library (aside from simple blocks of memory) Every other data structure uses a vl_buffer somewhere in their implementation. Most comparable to a standard Vector or ArrayList, the buffer is capable of resizing itself according to write operations by doubling its size for new elements.

Buffers do offer stateful functionality used to treat them as streams (e.g, seeking). Unless otherwise specified, the default initial capacity is equal to VL_DEFAULT_MEMORY_SIZE.

Collaboration diagram for vl_buffer:

Data Fields
vl_memory *	data	Actual allocation managed by the buffer.
vl_dsoffs_t	offset	Read-write offset of the buffer.
vl_memsize_t	size	Virtual size of the buffer. Actual capacity of the allocation is always equal to or larger.

Macro Definition Documentation

◆ vlBufferInit

#define vlBufferInit ( bufferPtr ) vlBufferInitSz(bufferPtr, VL_DEFAULT_MEMORY_SIZE)

Initializes a buffer instance for the first time. This will create the initial allocation for the default capacity.

This buffer should be deleted via vlBufferFree.

See also: vlBufferFree

Parameters

buffer struct pointer

Complexity O(1) constant

Function Documentation

◆ vlBufferBegin()

vl_transient * vlBufferBegin ( vl_buffer * buffer )

Returns a pointer to the beginning of the buffer allocation.

Complexity O(1) constant

Parameters

buffer struct pointer

Returns: pointer to the first byte of the allocation

◆ vlBufferClear()

void vlBufferClear ( vl_buffer * buffer )

Sets the entirety of the buffer to zero. Also resets offset and computed size.

Complexity O(n) where n = buffer capacity

Parameters

buffer struct pointer

Here is the call graph for this function:

◆ vlBufferClone()

vl_buffer * vlBufferClone	(	const vl_buffer *	src,
		vl_buffer *	dest )

Clones the source buffer to the destination buffer.

This is a 'complete' clone of the entirety of the buffer, and thus includes all related state alongside a copy of the underlying block of memory.

When simply copying data from one buffer to another, consider the more stateful vlBufferCopy.

The 'src' buffer must be non-null and point to an initialized buffer. The 'dest' buffer must be either null, or a pointer to an initialized buffer.

If the 'dest' buffer is null, a new instance is created via vlBufferNew. It must later be disposed using vlBufferDelete if this is the case.

See also: vlBufferNew; vlBufferCopy

Parameters

src	source buffer pointer
dest	destination buffer pointer, or NULL.

Complexity O(n) where n = buffer capacity.

Returns: 'dest' buffer, or buffer created via vlBufferNew.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlBufferCopy()

vl_memsize_t vlBufferCopy	(	vl_buffer *	src,
		vl_buffer *	dest,
		vl_memsize_t	len )

Copies a series of bytes from one buffer to another.

The read from the src buffer and the write to the dest buffer are relative to their current respective offsets.

If there are less bytes available in the source buffer than those specified by len, the copy is performed up to the end of the source.

Parameters

src	source buffer pointer
dest	destination buffer pointer
len	total number of bytes to attempt to copy.

Complexity O(n) where n = len

Returns: total number of bytes copied from src to dest.

Here is the call graph for this function:

◆ vlBufferDelete()

void vlBufferDelete ( vl_buffer * buffer )

Deletes the specified buffer.

The buffer should have been initialized via vlBufferNew(Sz) or vlBufferClone.

See also: vlBufferNew; vlBufferClone

Parameters

buffer struct pointer

Complexity O(1) constant.

Here is the call graph for this function:

◆ vlBufferEnd()

vl_transient * vlBufferEnd ( vl_buffer * buffer )

Returns a pointer to the end of the buffer allocation.

Complexity O(1) constant

Parameters

buffer struct pointer

Returns: pointer to one past the last byte of the allocation

◆ vlBufferFree()

void vlBufferFree ( vl_buffer * buffer )

Frees the specified buffer.

The buffer should have been initialized via vlBufferInit(Sz).

See also: vlBufferInit; vlBufferInitSz

Parameters

buffer struct pointer

Complexity O(1) constant.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlBufferInitSz()

void vlBufferInitSz	(	vl_buffer *	buffer,
		vl_memsize_t	initialCapacity )

Initializes a buffer instance for the first time. This will create the initial allocation for the specified capacity.

This buffer should be deleted via vlBufferFree.

See also: vlBufferFree

Parameters

buffer	struct pointer
initialCapacity	total number of initial bytes the buffer will have the capacity to hold.

Complexity O(1) constant

Here is the call graph for this function:

◆ vlBufferNew()

vl_buffer * vlBufferNew ( void )

Allocates a new buffer, and initializes it with the default capacity. The buffer must be deleted with vlBufferDelete(...) when it is no longer being used to avoid leaking memory.

Complexity O(1) constant

Returns: pointer to buffer.

Here is the call graph for this function:

◆ vlBufferNewSz()

vl_buffer * vlBufferNewSz ( vl_memsize_t initialCapacity )

Allocates a new buffer, and initializes it with a capacity of N bytes. The buffer must be deleted with vlBufferDelete(...) when it is no longer being used to avoid leaking memory.

Complexity O(1) constant

Parameters

initialCapacity initial capacity N

Returns: pointer to buffer.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlBufferRead()

vl_memsize_t vlBufferRead	(	vl_buffer *	buffer,
		vl_memsize_t	size,
		void *	dest )

Copies bytes from the buffer to the specified destination. Performs a copy from the buffer to the specified destination pointer. This will increment the buffer offset.

Complexity O(n) where n = param size

Parameters

buffer	struct pointer
size	total number of bytes to attempt to copy
dest	pointer to the memory that will be copied to

Returns: actual number of bytes copied

◆ vlBufferReset()

void vlBufferReset ( vl_buffer * buffer )

Resets the state of the specified buffer, setting the offset integer to zero. This will re-allocate the buffer to hold the default capacity.

Complexity O(1) constant

Parameters

buffer struct pointer

Here is the caller graph for this function:

◆ vlBufferResetSz()

void vlBufferResetSz	(	vl_buffer *	buffer,
		vl_memsize_t	newCapacity )

Resets the state of the specified buffer, setting the offset integer to zero. This will re-allocate the buffer to hold the specified capacity.

Complexity O(1) constant

Parameters

buffer	struct pointer
newCapacity	new capacity, in bytes

Here is the call graph for this function:

◆ vlBufferSeek()

void vlBufferSeek	(	vl_buffer *	buffer,
		vl_uintptr_t	offset )

Sets the buffer offset relative to the beginning of the allocation.

Complexity O(1) constant

Parameters

buffer	struct pointer
offset	total number of bytes, positive, to seek forward.

◆ vlBufferSeekBegin()

void vlBufferSeekBegin ( vl_buffer * buffer )

Seeks the internal offset to the beginning of the buffer. Moves the offset integer belonging to the buffer state to the beginning of the allocation (e.g, zero)

Complexity O(1) constant

Parameters

buffer struct pointer

◆ vlBufferSeekEnd()

void vlBufferSeekEnd ( vl_buffer * buffer )

Seeks the internal offset to the end of the buffer. Moves the offset integer belonging to the buffer state to the end of the allocation (e.g, the buffer size)

Complexity O(1) constant

See also: vlBufferEnd

Parameters

buffer struct pointer

◆ vlBufferSeekRelative()

void vlBufferSeekRelative	(	vl_buffer *	buffer,
		vl_intptr_t	offset )

Seeks the internal offset relative to the current offset. Adds the specified offset to the offset integer belonging to the buffer state.

Complexity O(1) constant

Parameters

buffer	struct pointer
offset	total number of bytes, positive or negative, to seek.

◆ vlBufferShrinkToFit()

void vlBufferShrinkToFit ( vl_buffer * buffer )

Resizes the specified buffer to hold a capacity equal to the current size.

Complexity O(n) where n = new buffer capacity

Parameters

buffer struct pointer

Here is the call graph for this function:

◆ vlBufferWrite()

vl_memsize_t vlBufferWrite	(	vl_buffer *	buffer,
		vl_memsize_t	size,
		const void *	src )

Performs a copy from the specified source pointer into the buffer. The bytes are written at the current offset integer belonging to the buffer state. This function will resize the buffer when necessary. The buffer offset will be incremented by the total number of bytes written.

Complexity O(n) where n = param size

Parameters

buffer	struct pointer
size	total number of bytes to write
src	pointer to the memory that will be copied from

Returns: the offset at which the bytes were written into the buffer.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Functions

Data Structure Documentation

◆ vl_buffer

Macro Definition Documentation

◆ vlBufferInit

Function Documentation

◆ vlBufferBegin()

◆ vlBufferClear()

◆ vlBufferClone()

◆ vlBufferCopy()

◆ vlBufferDelete()

◆ vlBufferEnd()

◆ vlBufferFree()

◆ vlBufferInitSz()

◆ vlBufferNew()

◆ vlBufferNewSz()

◆ vlBufferRead()

◆ vlBufferReset()

◆ vlBufferResetSz()

◆ vlBufferSeek()

◆ vlBufferSeekBegin()

◆ vlBufferSeekEnd()

◆ vlBufferSeekRelative()

◆ vlBufferShrinkToFit()

◆ vlBufferWrite()