ucx
UAP Common Extensions
Data Structures | Macros | Functions
buffer.h File Reference

Advanced buffer implementation. More...

#include "ucx.h"
#include <sys/types.h>
#include <stdio.h>

Go to the source code of this file.

Data Structures

struct  UcxBuffer
 UCX Buffer. More...
 

Macros

#define UCX_BUFFER_DEFAULT   0x00
 No buffer features enabled (all flags cleared).
 
#define UCX_BUFFER_AUTOFREE   0x01
 If this flag is enabled, the buffer will automatically free its contents.
 
#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...
 

Functions

UcxBufferucx_buffer_new (void *space, size_t capacity, int flags)
 Creates a new buffer. More...
 
void ucx_buffer_free (UcxBuffer *buffer)
 Destroys a buffer. More...
 
UcxBufferucx_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_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, char *str)
 Writes a string to a buffer. More...
 

Detailed Description

Advanced buffer implementation.

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.

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

Macro Definition Documentation

#define ucx_buffer_clear (   buffer)
Value:
memset(buffer->space, 0, buffer->size); \
buffer->size = 0; buffer->pos = 0;

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

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

Parameters
bufferthe buffer to be cleared
#define ucx_buffer_clone (   src,
  flags 
)    ucx_buffer_extract(src, 0, (src)->capacity, flags)

A shorthand macro for the full extraction of the buffer.

Parameters
srcthe source buffer
flagsfeature mask for the new buffer
Returns
a new buffer with the extracted content

Function Documentation

int ucx_buffer_eof ( UcxBuffer buffer)

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

Parameters
bufferthe buffer to test
Returns
non-zero, if the current buffer position has exceeded the last available byte of the buffer.
int ucx_buffer_extend ( UcxBuffer buffer,
size_t  additional_bytes 
)

Extends the capacity of the buffer.

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.

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.

Parameters
bufferthe buffer to extend
additional_bytesthe number of additional bytes the buffer shall at least hold
Returns
0 on success or a non-zero value on failure
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.

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

Parameters
srcthe source buffer
startthe start position of extraction
lengththe count of bytes to extract (must not be zero)
flagsfeature mask for the new buffer
Returns
a new buffer containing the extraction
void ucx_buffer_free ( UcxBuffer buffer)

Destroys a buffer.

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

Parameters
bufferthe buffer to destroy
int ucx_buffer_getc ( UcxBuffer buffer)

Gets a character from a buffer.

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

Parameters
bufferthe buffer to read from
Returns
the character as int value or EOF, if the end of the buffer is reached
UcxBuffer* ucx_buffer_new ( void *  space,
size_t  capacity,
int  flags 
)

Creates a new buffer.

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

Parameters
spacepointer to the memory area, or NULL to allocate new memory
capacitythe capacity of the buffer
flagsbuffer features (see UcxBuffer.flags)
Returns
the new buffer
int ucx_buffer_putc ( UcxBuffer 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 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.

On successful write the position of the buffer is increased.

Parameters
bufferthe buffer to write to
cthe character to write as int value
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
size_t ucx_buffer_puts ( UcxBuffer buffer,
char *  str 
)

Writes a string to a buffer.

Parameters
bufferthe buffer
strthe string
Returns
the number of bytes written
size_t ucx_buffer_read ( void *  ptr,
size_t  size,
size_t  nitems,
UcxBuffer buffer 
)

Reads data from a UcxBuffer.

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

Parameters
ptra pointer to the memory area where to store the read data
sizethe length of one element
nitemsthe element count
bufferthe UcxBuffer to read from
Returns
the total number of elements read
int ucx_buffer_seek ( UcxBuffer 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
offsetposition offset relative to whence
whenceone of SEEK_SET, SEEK_CUR or SEEK_END
Returns
0 on success, non-zero if the position is invalid
size_t ucx_buffer_write ( const void *  ptr,
size_t  size,
size_t  nitems,
UcxBuffer buffer 
)

Writes data to a UcxBuffer.

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

Parameters
ptra pointer to the memory area containing the bytes to be written
sizethe length of one element
nitemsthe element count
bufferthe UcxBuffer to write to
Returns
the total count of bytes written