Advanced buffer implementation. More...

#include "common.h"
#include "allocator.h"

Data Structures
struct	cx_buffer_s
	Structure for the UCX buffer data. More...

Macros
#define	CX_BUFFER_DEFAULT 0x00
	No buffer features enabled (all flags cleared).

#define	CX_BUFFER_FREE_CONTENTS 0x01
	If this flag is enabled, the buffer will automatically free its contents when destroyed.

#define	CX_BUFFER_AUTO_EXTEND 0x02
	If this flag is enabled, the buffer will automatically extends its capacity.

Typedefs
typedef cx_buffer_s	CxBuffer
	UCX buffer.

Functions
int	cxBufferInit (CxBuffer buffer, void space, size_t capacity, CxAllocator const *allocator, int flags)
	Initializes a fresh buffer.

CxBuffer *	cxBufferCreate (void space, size_t capacity, CxAllocator const allocator, int flags)
	Allocates and initializes a fresh buffer.

void	cxBufferDestroy (CxBuffer *buffer)
	Destroys the buffer contents.

void	cxBufferFree (CxBuffer *buffer)
	Deallocates the buffer.

int	cxBufferShift (CxBuffer *buffer, off_t shift)
	Shifts the contents of the buffer by the given offset.

int	cxBufferShiftRight (CxBuffer *buffer, size_t shift)
	Shifts the buffer to the right.

int	cxBufferShiftLeft (CxBuffer *buffer, size_t shift)
	Shifts the buffer to the left.

int	cxBufferSeek (CxBuffer *buffer, off_t offset, int whence)
	Moves the position of the buffer.

void	cxBufferClear (CxBuffer *buffer)
	Clears the buffer by resetting the position and deleting the data.

int	cxBufferEof (CxBuffer const *buffer)
	Tests, if the buffer position has exceeded the buffer capacity.

int	cxBufferMinimumCapacity (CxBuffer *buffer, size_t capacity)
	Ensures that the buffer has a minimum capacity.

size_t	cxBufferWrite (void const ptr, size_t size, size_t nitems, CxBuffer buffer)
	Writes data to a CxBuffer.

size_t	cxBufferRead (void ptr, size_t size, size_t nitems, CxBuffer buffer)
	Reads data from a CxBuffer.

int	cxBufferPut (CxBuffer *buffer, int c)
	Writes a character to a buffer.

size_t	cxBufferPutString (CxBuffer buffer, const char str)
	Writes a string to a buffer.

int	cxBufferGet (CxBuffer *buffer)
	Gets a character from a buffer.

Detailed Description

Advanced buffer implementation.

Instances of CxBuffer can be used to read from or to write to like one would do with a stream.

Some features for convenient use of the buffer can be enabled. See the documentation of the macro constants for more information.

Author: Mike Becker; Olaf Wintermann

Version: 3.0

Copyright: 2-Clause BSD License

Function Documentation

◆ cxBufferClear()

void cxBufferClear ( CxBuffer * buffer )

Clears the buffer by resetting the position and deleting the data.

The data is deleted by zeroing it with a call to memset().

Parameters

buffer the buffer to be cleared

◆ cxBufferCreate()

CxBuffer * cxBufferCreate	(	void *	space,
		size_t	capacity,
		CxAllocator const *	allocator,
		int	flags
	)

Allocates and initializes a fresh buffer.

Note: You may provide NULL as argument for space. Then this function will allocate the space and enforce the CX_BUFFER_FREE_CONTENTS flag.

Parameters

space	pointer to the memory area, or `NULL` to allocate new memory
capacity	the capacity of the buffer
allocator	the allocator to use for allocating the structure and the automatic memory management within the buffer. If `NULL`, the default heap allocator will be used.
flags	buffer features (see cx_buffer_s.flags)

Returns: a pointer to the buffer on success, NULL if a required allocation failed

◆ cxBufferDestroy()

void cxBufferDestroy ( CxBuffer * buffer )

Destroys the buffer contents.

Has no effect if the CX_BUFFER_FREE_CONTENTS feature is not enabled. If you want to free the memory of the entire buffer, use cxBufferFree().

Parameters

buffer the buffer which contents shall be destroyed

See also: cxBufferInit()

◆ cxBufferEof()

int cxBufferEof ( CxBuffer const * buffer )

Tests, if the buffer position has exceeded the buffer capacity.

Parameters

buffer the buffer to test

Returns: non-zero, if the current buffer position has exceeded the last available byte of the buffer.

◆ cxBufferFree()

void cxBufferFree ( CxBuffer * buffer )

Deallocates the buffer.

If the CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys the contents. If you only want to destroy the contents, use cxBufferDestroy().

Parameters

buffer the buffer to deallocate

See also: cxBufferCreate()

◆ cxBufferGet()

int cxBufferGet ( CxBuffer * buffer )

Gets a character from a buffer.

The current position of the buffer is increased after a successful read.

Parameters

buffer the buffer to read from

Returns: the character or EOF, if the end of the buffer is reached

◆ cxBufferInit()

int cxBufferInit	(	CxBuffer *	buffer,
		void *	space,
		size_t	capacity,
		CxAllocator const *	allocator,
		int	flags
	)

Initializes a fresh buffer.

Note: You may provide NULL as argument for space. Then this function will allocate the space and enforce the CX_BUFFER_FREE_CONTENTS flag.

Parameters

buffer	the buffer to initialize
space	pointer to the memory area, or `NULL` to allocate new memory
capacity	the capacity of the buffer
allocator	the allocator this buffer shall use for automatic memory management. If `NULL`, the default heap allocator will be used.
flags	buffer features (see cx_buffer_s.flags)

Returns: zero on success, non-zero if a required allocation failed

◆ cxBufferMinimumCapacity()

int cxBufferMinimumCapacity	(	CxBuffer *	buffer,
		size_t	capacity
	)

Ensures that the buffer has a minimum capacity.

If the current capacity is not sufficient, the buffer will be extended.

Parameters

buffer	the buffer
capacity	the minimum required capacity for this buffer

Returns: 0 on success or a non-zero value on failure

◆ cxBufferPut()

int cxBufferPut	(	CxBuffer *	buffer,
		int	c
	)

Writes a character to a buffer.

The least significant byte of the argument is written to the buffer. If the end of the buffer is reached and CX_BUFFER_AUTO_EXTEND feature is enabled, the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature is disabled or buffer extension fails, EOF is returned.

On successful write, the position of the buffer is increased.

Parameters

buffer	the buffer to write to
c	the character to write

Returns: the byte that has bean written or EOF when the end of the stream is reached and automatic extension is not enabled or not possible

◆ cxBufferPutString()

size_t cxBufferPutString	(	CxBuffer *	buffer,
		const char *	str
	)

Writes a string to a buffer.

Parameters

buffer	the buffer
str	the zero-terminated string

Returns: the number of bytes written

◆ cxBufferRead()

size_t cxBufferRead	(	void *	ptr,
		size_t	size,
		size_t	nitems,
		CxBuffer *	buffer
	)

Reads data from a CxBuffer.

The position of the buffer is increased by the number of bytes read.

Note: The signature is compatible with the fread() family of functions.

Parameters

ptr	a pointer to the memory area where to store the read data
size	the length of one element
nitems	the element count
buffer	the CxBuffer to read from

Returns: the total number of elements read

◆ cxBufferSeek()

int cxBufferSeek	(	CxBuffer *	buffer,
		off_t	offset,
		int	whence
	)

Moves the position of the buffer.

The new position is relative to the whence argument.

SEEK_SET marks the start of the buffer.
SEEK_CUR marks the current position.
SEEK_END marks the end of the buffer.

With an offset of zero, this function sets the buffer position to zero (SEEK_SET), the buffer size (SEEK_END) or leaves the buffer position unchanged (SEEK_CUR).

Parameters

buffer	the buffer
offset	position offset relative to `whence`
whence	one of `SEEK_SET`, `SEEK_CUR` or `SEEK_END`

Returns: 0 on success, non-zero if the position is invalid

◆ cxBufferShift()

int cxBufferShift	(	CxBuffer *	buffer,
		off_t	shift
	)

Shifts the contents of the buffer by the given offset.

If the offset is positive, the contents are shifted to the right. If auto extension is enabled, the buffer grows, if necessary. In case the auto extension fails, this function returns a non-zero value and no contents are changed. If auto extension is disabled, the contents that do not fit into the buffer are discarded.

If the offset is negative, the contents are shifted to the left where the first shift bytes are discarded. The new size of the buffer is the old size minus the absolute shift value. If this value is larger than the buffer size, the buffer is emptied (but not cleared, see the security note below).

The buffer position gets shifted alongside with the content but is kept within the boundaries of the buffer.

Note: For situations where off_t is not large enough, there are specialized cxBufferShiftLeft() and cxBufferShiftRight() functions using a size_t as parameter type.

Attention: Security Note: The shifting operation does not erase the previously occupied memory cells. But you can easily do that manually, e.g. by calling memset(buffer->bytes, 0, shift) for a right shift or memset(buffer->bytes + buffer->size, 0, buffer->capacity - buffer->size) for a left shift.

Parameters

buffer	the buffer
shift	the shift offset (negative means left shift)

Returns: 0 on success, non-zero if a required auto-extension fails

◆ cxBufferShiftLeft()

int cxBufferShiftLeft	(	CxBuffer *	buffer,
		size_t	shift
	)

Shifts the buffer to the left.

See cxBufferShift() for details.

Note: Since a left shift cannot fail due to memory allocation problems, this function always returns zero.

Parameters

buffer	the buffer
shift	the positive shift offset

Returns: always zero

See also: cxBufferShift()

◆ cxBufferShiftRight()

int cxBufferShiftRight	(	CxBuffer *	buffer,
		size_t	shift
	)

Shifts the buffer to the right.

See cxBufferShift() for details.

Parameters

buffer	the buffer
shift	the shift offset

Returns: 0 on success, non-zero if a required auto-extension fails

See also: cxBufferShift()

◆ cxBufferWrite()

size_t cxBufferWrite	(	void const *	ptr,
		size_t	size,
		size_t	nitems,
		CxBuffer *	buffer
	)

Writes data to a CxBuffer.

If flushing is enabled and the buffer needs to flush, the data is flushed to the target until the target signals that it cannot take more data by returning zero via the respective write function. In that case, the remaining data in this buffer is shifted to the beginning of this buffer so that the newly available space can be used to append as much data as possible. This function only stops writing more elements, when the flush target and this buffer are both incapable of taking more data or all data has been written. The number returned by this function is the total number of elements that could be written during the process. It does not necessarily mean that those elements are still in this buffer, because some of them could have also be flushed already.

If automatic flushing is not enabled, the position of the buffer is increased by the number of bytes written.

Note: The signature is compatible with the fwrite() family of functions.

Parameters

ptr	a pointer to the memory area containing the bytes to be written
size	the length of one element
nitems	the element count
buffer	the CxBuffer to write to

Returns: the total count of elements written

Data Structures

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ cxBufferClear()

◆ cxBufferCreate()

◆ cxBufferDestroy()

◆ cxBufferEof()

◆ cxBufferFree()

◆ cxBufferGet()

◆ cxBufferInit()

◆ cxBufferMinimumCapacity()

◆ cxBufferPut()

◆ cxBufferPutString()

◆ cxBufferRead()

◆ cxBufferSeek()

◆ cxBufferShift()

◆ cxBufferShiftLeft()

◆ cxBufferShiftRight()

◆ cxBufferWrite()