universe@390: universe@390:

Advanced buffer implementation. universe@390: More...

universe@390:

#include "ucx.h"
universe@390: #include <sys/types.h>
universe@390: #include <stdio.h>
universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Data Structures
struct	UcxBuffer
	UCX Buffer. More...

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Macros
universe@390: #define	UCX_BUFFER_DEFAULT 0x00
	No buffer features enabled (all flags cleared).

universe@390: #define	UCX_BUFFER_AUTOFREE 0x01
	If this flag is enabled, the buffer will automatically free its contents.

universe@390: #define	UCX_BUFFER_AUTOEXTEND 0x02
	If this flag is enabled, the buffer will automatically extends its capacity.

#define	ucx_buffer_clone(src, flags) ucx_buffer_extract(src, 0, (src)->capacity, flags)
	A shorthand macro for the full extraction of the buffer. More...

#define	ucx_buffer_clear(buffer)
	Clears the buffer by resetting the position and deleting the data. More...

#define	ucx_buffer_to_sstr(buffer) sstrn((buffer)->space, (buffer)->size)
	Returns the complete buffer content as sstr_t. More...

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Functions
UcxBuffer *	ucx_buffer_new (void *space, size_t capacity, int flags)
	Creates a new buffer. More...

void	ucx_buffer_free (UcxBuffer *buffer)
	Destroys a buffer. More...

UcxBuffer *	ucx_buffer_extract (UcxBuffer *src, size_t start, size_t length, int flags)
	Creates a new buffer and fills it with extracted content from another buffer. More...

int	ucx_buffer_shift (UcxBuffer *buffer, off_t shift)
	Shifts the contents of the buffer by the given offset. More...

int	ucx_buffer_shift_right (UcxBuffer *buffer, size_t shift)
	Shifts the buffer to the right. More...

int	ucx_buffer_shift_left (UcxBuffer *buffer, size_t shift)
	Shifts the buffer to the left. More...

int	ucx_buffer_seek (UcxBuffer *buffer, off_t offset, int whence)
	Moves the position of the buffer. More...

int	ucx_buffer_eof (UcxBuffer *buffer)
	Tests, if the buffer position has exceeded the buffer capacity. More...

int	ucx_buffer_extend (UcxBuffer *buffer, size_t additional_bytes)
	Extends the capacity of the buffer. More...

size_t	ucx_buffer_write (const void ptr, size_t size, size_t nitems, UcxBuffer buffer)
	Writes data to a UcxBuffer. More...

size_t	ucx_buffer_read (void ptr, size_t size, size_t nitems, UcxBuffer buffer)
	Reads data from a UcxBuffer. More...

int	ucx_buffer_putc (UcxBuffer *buffer, int c)
	Writes a character to a buffer. More...

int	ucx_buffer_getc (UcxBuffer *buffer)
	Gets a character from a buffer. More...

size_t	ucx_buffer_puts (UcxBuffer buffer, const char str)
	Writes a string to a buffer. More...

universe@390:

Detailed Description

universe@390:

Advanced buffer implementation.

universe@390:

Instances of UcxBuffer can be used to read from or to write to like one would do with a stream. This allows the use of ucx_stream_copy() to copy contents from one buffer to another.

universe@390:

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

universe@390:

Author: Mike Becker; universe@390: Olaf Wintermann

universe@390:

Macro Definition Documentation

universe@390: universe@390:

◆ ucx_buffer_clear

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_buffer_clear ( buffer )

universe@390:

universe@390: Value:

memset((buffer)->space, 0, (buffer)->size); \

(buffer)->size = 0; (buffer)->pos = 0;

universe@390:

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

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390:

buffer the buffer to be cleared

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_clone

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_buffer_clone	(	src,
		flags
	)	ucx_buffer_extract(src, 0, (src)->capacity, flags)

universe@390:

universe@390: universe@390:

A shorthand macro for the full extraction of the buffer.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

src	the source buffer
flags	feature mask for the new buffer

universe@390:

Returns: a new buffer with the extracted content

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_to_sstr

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_buffer_to_sstr ( buffer ) sstrn((buffer)->space, (buffer)->size)

universe@390:

universe@390: universe@390:

Returns the complete buffer content as sstr_t.

universe@390:

Parameters

universe@390: universe@390: universe@390:

buffer the buffer

universe@390:

Returns: the result of sstrn() with the buffer space and size as arguments

universe@390: universe@390:

universe@390:

Function Documentation

universe@390: universe@390:

◆ ucx_buffer_eof()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_eof ( UcxBuffer * buffer )

universe@390:

universe@390: universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390:

buffer the buffer to test

universe@390:

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

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_extend()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_extend	(	UcxBuffer *	buffer,
		size_t	additional_bytes
	)

universe@390:

universe@390: universe@390:

Extends the capacity of the buffer.

universe@390:

Note: The buffer capacity increased by a power of two. I.e. the buffer capacity is doubled, as long as it would not hold the current content plus the additional required bytes.

universe@390:

Attention: the argument provided is the number of additional bytes the buffer shall hold. It is NOT the total number of bytes the buffer shall hold.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

buffer	the buffer to extend
additional_bytes	the number of additional bytes the buffer shall at least hold

universe@390:

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

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_extract()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

UcxBuffer* ucx_buffer_extract	(	UcxBuffer *	src,
		size_t	start,
		size_t	length,
		int	flags
	)

universe@390:

universe@390: universe@390:

Creates a new buffer and fills it with extracted content from another buffer.

universe@390:

Note: the UCX_BUFFER_AUTOFREE feature is enforced for the new buffer.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

src	the source buffer
start	the start position of extraction
length	the count of bytes to extract (must not be zero)
flags	feature mask for the new buffer

universe@390:

Returns: a new buffer containing the extraction

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_free()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_buffer_free ( UcxBuffer * buffer )

universe@390:

universe@390: universe@390:

Destroys a buffer.

universe@390:

If the UCX_BUFFER_AUTOFREE feature is enabled, the contents of the buffer are also freed.

universe@390:

Parameters

universe@390: universe@390: universe@390:

buffer the buffer to destroy

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_getc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_getc ( UcxBuffer * buffer )

universe@390:

universe@390: universe@390:

Gets a character from a buffer.

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390:

buffer the buffer to read from

universe@390:

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

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_new()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

UcxBuffer* ucx_buffer_new	(	void *	space,
		size_t	capacity,
		int	flags
	)

universe@390:

universe@390: universe@390:

Creates a new buffer.

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

space	pointer to the memory area, or `NULL` to allocate new memory
capacity	the capacity of the buffer
flags	buffer features (see UcxBuffer.flags)

universe@390:

Returns: the new buffer

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_putc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_putc	(	UcxBuffer *	buffer,
		int	c
	)

universe@390:

universe@390: universe@390:

Writes a character to a buffer.

universe@390:

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

universe@390:

On successful write the position of the buffer is increased.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

buffer	the buffer to write to
c	the character to write as `int` value

universe@390:

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

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_puts()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

size_t ucx_buffer_puts	(	UcxBuffer *	buffer,
		const char *	str
	)

universe@390:

universe@390: universe@390:

Writes a string to a buffer.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

buffer	the buffer
str	the string

universe@390:

Returns: the number of bytes written

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_read()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

size_t ucx_buffer_read	(	void *	ptr,
		size_t	size,
		size_t	nitems,
		UcxBuffer *	buffer
	)

universe@390:

universe@390: universe@390:

Reads data from a UcxBuffer.

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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 UcxBuffer to read from

universe@390:

Returns: the total number of elements read

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_seek()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_seek	(	UcxBuffer *	buffer,
		off_t	offset,
		int	whence
	)

universe@390:

universe@390: universe@390:

Moves the position of the buffer.

universe@390:

The new position is relative to the whence argument.

universe@390:

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

universe@390:

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).

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

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

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_shift()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_shift	(	UcxBuffer *	buffer,
		off_t	shift
	)

universe@390:

universe@390: universe@390:

Shifts the contents of the buffer by the given offset.

universe@390:

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.

universe@390:

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).

universe@390:

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

universe@390:

Security note: the shifting operation does not erase the previously occupied memory cells. You can easily do that manually, e.g. by calling memset(buffer->space, 0, shift) for a right shift or memset(buffer->size, 0, buffer->capacity-buffer->size) for a left shift.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

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

universe@390:

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

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_shift_left()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_shift_left	(	UcxBuffer *	buffer,
		size_t	shift
	)

universe@390:

universe@390: universe@390:

Shifts the buffer to the left.

universe@390:

See ucx_buffer_shift() for details. Note, however, that this method expects a positive shift offset.

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

buffer	the buffer
shift	the shift offset

universe@390:

Returns: always zero

universe@390:

See also: ucx_buffer_shift()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_shift_right()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_buffer_shift_right	(	UcxBuffer *	buffer,
		size_t	shift
	)

universe@390:

universe@390: universe@390:

Shifts the buffer to the right.

universe@390:

See ucx_buffer_shift() for details.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

buffer	the buffer
shift	the shift offset

universe@390:

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

universe@390:

See also: ucx_buffer_shift()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_buffer_write()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

size_t ucx_buffer_write	(	const void *	ptr,
		size_t	size,
		size_t	nitems,
		UcxBuffer *	buffer
	)

universe@390:

universe@390: universe@390:

Writes data to a UcxBuffer.

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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 UcxBuffer to write to

universe@390:

Returns: the total count of bytes written

universe@390: universe@390:

universe@390:

universe@390: Data Structures

universe@390: Macros

universe@390: Functions

Detailed Description

Macro Definition Documentation

◆ ucx_buffer_clear

◆ ucx_buffer_clone

◆ ucx_buffer_to_sstr

Function Documentation

◆ ucx_buffer_eof()

◆ ucx_buffer_extend()

◆ ucx_buffer_extract()

◆ ucx_buffer_free()

◆ ucx_buffer_getc()

◆ ucx_buffer_new()

◆ ucx_buffer_putc()

◆ ucx_buffer_puts()

◆ ucx_buffer_read()

◆ ucx_buffer_seek()

◆ ucx_buffer_shift()

◆ ucx_buffer_shift_left()

◆ ucx_buffer_shift_right()

◆ ucx_buffer_write()