ucx
UAP Common Extensions
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
buffer.h File Reference

Advanced buffer implementation. More...

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

Go to the source code of this file.

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.
 
CxBuffercxBufferCreate (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

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
bufferthe 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
spacepointer to the memory area, or NULL to allocate new memory
capacitythe capacity of the buffer
allocatorthe allocator to use for allocating the structure and the automatic memory management within the buffer. If NULL, the default heap allocator will be used.
flagsbuffer 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
bufferthe 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
bufferthe 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
bufferthe 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
bufferthe 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
bufferthe buffer to initialize
spacepointer to the memory area, or NULL to allocate new memory
capacitythe capacity of the buffer
allocatorthe allocator this buffer shall use for automatic memory management. If NULL, the default heap allocator will be used.
flagsbuffer 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
bufferthe buffer
capacitythe 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
bufferthe buffer to write to
cthe 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
bufferthe buffer
strthe 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
ptra pointer to the memory area where to store the read data
sizethe length of one element
nitemsthe element count
bufferthe 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
bufferthe 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

◆ 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
bufferthe buffer
shiftthe 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
bufferthe buffer
shiftthe 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
bufferthe buffer
shiftthe 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
ptra pointer to the memory area containing the bytes to be written
sizethe length of one element
nitemsthe element count
bufferthe CxBuffer to write to
Returns
the total count of elements written