Dynamic buffers

Overview

Definition of functions to work with dynamic buffers. More…

// typedefs

typedef struct te_dbuf te_dbuf;

// structs

struct te_dbuf;

// global functions

static void te_dbuf_reset(te_dbuf* dbuf);
te_errno te_dbuf_append(te_dbuf* dbuf, const void* data, size_t data_len);
te_errno te_dbuf_expand(te_dbuf* dbuf, size_t n);
void te_dbuf_cut(te_dbuf* dbuf, size_t start_index, size_t count);
void te_dbuf_free(te_dbuf* dbuf);
void te_dbuf_print(const te_dbuf* dbuf);

// macros

#define TE_DBUF_DEFAULT_GROW_FACTOR
#define TE_DBUF_INIT(grow_factor_)

Detailed Documentation

Definition of functions to work with dynamic buffers.

Example of using:

// Init the dynamic buffer with the default growth parameters.
te_dbuf dbuf = TE_DBUF_INIT(TE_DBUF_DEFAULT_GROW_FACTOR);
...
// Put the "foo\0" into the dbuf
te_dbuf_append(&dbuf, "foo", 4);
...
// Reserve 4 bytes into the dbuf
size_t pos = dbuf.len;   // Save current position in the buffer.
te_dbuf_append(&dbuf, NULL, 4);

(uint32_t *)&dbuf.ptr[pos] = 5;  // Put the number to reserved place.
...
// Reset the buffer to start filling it from the beginning again.
te_dbuf_reset(&dbuf);
...
// Finish work with dynamic buffer, free the memory.
te_dbuf_free(&dbuf);

Typedefs

typedef struct te_dbuf te_dbuf

Dynamically allocated buffer.

Global Functions

static void te_dbuf_reset(te_dbuf* dbuf)

Reset dynamic buffer (makes its empty).

Parameters:

dbuf	Dynamic buffer.

te_errno te_dbuf_append(te_dbuf* dbuf, const void* data, size_t data_len)

Append additional data to the dynamic buffer. Allocate/reallocate the memory for the buffer if needed. dbuf should be released with te_dbuf_free when it is no longer needed.

Parameters:

dbuf	Dynamic buffer.
data	Data to append to the buffer pointed by `dbuf`. If `NULL`, then a block of `data_len` zeroes is appended.
data_len	Length of the data.

Returns:

Status code (always 0).

See also:

te_dbuf_free

te_errno te_dbuf_expand(te_dbuf* dbuf, size_t n)

Increase the size of dynamic buffer on n bytes. It reallocates the te_dbuf container with new size. dbuf should be released with te_dbuf_free when it is no longer needed.

Parameters:

dbuf	Dynamic buffer.
n	Number of bytes to add to the buffer size to expand it.

Returns:

Status code (always 0).

void te_dbuf_cut(te_dbuf* dbuf, size_t start_index, size_t count)

Cut a region of a dynamic buffer starting from start_index of length count

Function does not reallocate memory

Parameters:

dbuf	Dynamic buffer
start_index	Starting index of a region
count	Length of a region

void te_dbuf_free(te_dbuf* dbuf)

Free dynamic buffer that was allocated with te_dbuf_append or te_dbuf_expand.

Parameters:

dbuf	Dynamic buffer.

Macros

#define TE_DBUF_DEFAULT_GROW_FACTOR

A grow factor is a percentage of extra memory to reserve for a dbuf when new data are appended to it.

For example, with a grow factor of 100, the amount of reserved memory is doubled every time the buffer is reallocated.

The purpose of grow factos is to optimize memory usage for different buffer grow scenario, however, most users should not bother with it and use the default factor.

#define TE_DBUF_INIT(grow_factor_)

On-stack te_dbuf initializer.

Parameters:

grow_factor_

see TE_DBUF_DEFAULT_GROW_FACTOR