The Flat_buffer Interface. More...

#include "private/private_flat_buffer.h"
#include "types.h"

Include dependency graph for flat_buffer.h:

This graph shows which files directly or indirectly include this file:

Detailed Description

The Flat_buffer Interface.

Flat_buffer usage is similar to a C++ vector, with more flexible functions provided to support higher level containers and abstractions. While useful on its own–a stack could be implemented with the provided functions–a buffer is often used as the lower level abstraction for the flat data structures in this library that provide more specialized operations. A Flat_buffer does not require the user accommodate any intrusive elements.

A Flat_buffer offers a more flexible interface than a standard C++ vector. There are functions that assume elements are stored contiguously from [0, N) where N is the count of elements. However, there are also functions that let the user access any Flat_buffer slot that is within the bounds of Flat_buffer capacity. This requires the user pay closer attention to Flat_buffer usage but ultimately allows a wider variety of abstractions on top of the buffer.

Interface functions in the slot management section offer data movement and writing operations that do not affect the size of the container. If writing a more complex higher level container that does not need size management these functions offer more custom control over the buffer.

A Flat_buffer function that accepts an allocator will re-size as required when a new element is inserted in a contiguous fashion if an allocator is provided. Interface functions in the allocation management section assume elements are stored contiguously and adjust size accordingly.

If an allocator is not provided, resizing will not occur and the insertion function will fail when capacity is reached, returning some value to indicate failure.

If shorter names are desired, define the following preprocessor directive.

#define FLAT_BUFFER_USING_NAMESPACE_CCC

Then, the CCC_ prefix can be dropped from all types and functions.

Initialization Interface
Initialize the container with memory, callbacks, and permissions.
#define	CCC_flat_buffer_default(type_name) CCC_private_flat_buffer_default(type_name)
	Initialize a contiguous empty buffer of a type.

#define	CCC_flat_buffer_for(type_name, capacity, count, data_pointer...) CCC_private_flat_buffer_for(type_name, capacity, count, data_pointer)
	Initialize a contiguous Flat_buffer of user a specified type, capacity, and optional starting size.

#define	CCC_flat_buffer_from( allocator, optional_capacity, compound_literal_array...)
	Initialize a Flat_buffer from a compound literal array initializer.

#define	CCC_flat_buffer_with_capacity(type_name, allocator, capacity) CCC_private_flat_buffer_with_capacity(type_name, allocator, capacity)
	Initialize a Flat_buffer with a capacity.

#define	CCC_flat_buffer_with_storage(count, compound_literal_array...) CCC_private_flat_buffer_with_storage(count, compound_literal_array)
	Initialize a contiguous Flat_buffer of user a specified type of fixed capacity with no allocation permission or context.

CCC_Result	CCC_flat_buffer_reserve (CCC_Flat_buffer buffer, size_t to_add, CCC_Allocator const allocator)
	Reserves space for at least to_add more elements.

CCC_Result	CCC_flat_buffer_copy (CCC_Flat_buffer destination, CCC_Flat_buffer const source, CCC_Allocator const *allocator)
	Copy the buffer from source to newly initialized destination.

Insert and Remove Interface
These functions assume contiguity of elements in the Flat_buffer and increase or decrease size accordingly.
#define	CCC_flat_buffer_emplace_back( flat_buffer_pointer, allocator_pointer, type_compound_literal...)
	Pushes the user provided compound literal directly to back of buffer and increments the size to reflect the newly added element.

CCC_Result	CCC_flat_buffer_allocate (CCC_Flat_buffer buffer, size_t capacity, CCC_Allocator const allocator)
	allocates the Flat_buffer to the specified size according to the user defined allocation function.

void *	CCC_flat_buffer_allocate_back (CCC_Flat_buffer buffer, CCC_Allocator const allocator)
	allocates a new slot from the Flat_buffer at the end of the contiguous array. A slot is equivalent to one of the element type specified when the Flat_buffer is initialized.

void *	CCC_flat_buffer_push_back (CCC_Flat_buffer buffer, void const data, CCC_Allocator const *allocator)
	return the newly pushed data into the last slot of the buffer according to size.

void *	CCC_flat_buffer_insert (CCC_Flat_buffer buffer, size_t index, void const data, CCC_Allocator const *allocator)
	insert data at slot index according to size of the Flat_buffer maintaining contiguous storage of elements between 0 and size.

CCC_Result	CCC_flat_buffer_pop_back (CCC_Flat_buffer *buffer)
	pop the back element from the Flat_buffer according to size.

CCC_Result	CCC_flat_buffer_pop_back_n (CCC_Flat_buffer *buffer, size_t count)
	pop count elements from the back of the Flat_buffer according to size.

CCC_Result	CCC_flat_buffer_erase (CCC_Flat_buffer *buffer, size_t index)
	erase element at slot index according to size of the Flat_buffer maintaining contiguous storage of elements between 0 and size.

Slot Management Interface
These functions interact with slots in the Flat_buffer directly and do not modify the size of the buffer. These are best used for custom container types operating at a higher level of abstraction.
#define	CCC_flat_buffer_as(flat_buffer_pointer, type_name, index) ((type_name *)CCC_flat_buffer_at(flat_buffer_pointer, index))
	Access en element at the specified index as the stored type.

#define	CCC_flat_buffer_back_as(flat_buffer_pointer, type_name) ((type_name *)CCC_flat_buffer_back(flat_buffer_pointer))
	return the final element in the Flat_buffer according the current size.

#define	CCC_flat_buffer_front_as(flat_buffer_pointer, type_name) ((type_name *)CCC_flat_buffer_front(flat_buffer_pointer))
	return the first element in the Flat_buffer at index 0.

#define	CCC_flat_buffer_emplace( flat_buffer_pointer, index, type_compound_literal...)
	Writes a user provided compound literal directly to a Flat_buffer slot.

void *	CCC_flat_buffer_at (CCC_Flat_buffer const *buffer, size_t index)
	return the element at slot index in buf.

CCC_Count	CCC_flat_buffer_index (CCC_Flat_buffer const buffer, void const slot)
	return the index of an element known to be in the buffer.

void *	CCC_flat_buffer_back (CCC_Flat_buffer const *buffer)
	return the final element in the Flat_buffer according the current size.

void *	CCC_flat_buffer_front (CCC_Flat_buffer const *buffer)
	return the first element in the Flat_buffer at index 0.

void *	CCC_flat_buffer_move (CCC_Flat_buffer const *buffer, size_t destination, size_t source)
	Move data at index source to destination according to capacity.

CCC_Result	CCC_flat_buffer_write (CCC_Flat_buffer const buffer, size_t index, void const data)
	write data to Flat_buffer at slot at index index according to capacity.

CCC_Result	CCC_flat_buffer_swap (CCC_Flat_buffer const buffer, void temp, size_t index, size_t swap_index)
	swap elements at index and swap_index according to capacity of the bufer.

Container Types
Types available in the container interface.
typedef struct CCC_Flat_buffer	CCC_Flat_buffer
	A contiguous block of storage for elements of the same type.

Iteration Interface
The following functions implement iterators over the buffer.
void *	CCC_flat_buffer_begin (CCC_Flat_buffer const *buffer)
	obtain the base address of the Flat_buffer in preparation for iteration.

void *	CCC_flat_buffer_next (CCC_Flat_buffer const buffer, void const iterator)
	advance the iterator to the next slot in the Flat_buffer according to size.

void *	CCC_flat_buffer_end (CCC_Flat_buffer const *buffer)
	return the end position of the Flat_buffer according to size.

void *	CCC_flat_buffer_reverse_begin (CCC_Flat_buffer const *buffer)
	obtain the address of the last element in the Flat_buffer in preparation for iteration according to size.

void *	CCC_flat_buffer_reverse_next (CCC_Flat_buffer const buffer, void const iterator)
	advance the iterator to the next slot in the Flat_buffer according to size and in reverse order.

void *	CCC_flat_buffer_reverse_end (CCC_Flat_buffer const *buffer)
	return the reverse_end position of the buffer.

State Interface
These functions help manage or obtain state of the buffer.
CCC_Result	CCC_flat_buffer_count_plus (CCC_Flat_buffer *buffer, size_t count)
	add count to the size of the buffer.

CCC_Result	CCC_flat_buffer_count_minus (CCC_Flat_buffer *buffer, size_t count)
	Subtract count from the size of the buffer.

CCC_Result	CCC_flat_buffer_count_set (CCC_Flat_buffer *buffer, size_t count)
	Set the Flat_buffer size to n.

CCC_Count	CCC_flat_buffer_count (CCC_Flat_buffer const *buffer)
	obtain the count of Flat_buffer active slots.

CCC_Count	CCC_flat_buffer_capacity (CCC_Flat_buffer const *buffer)
	Return the current capacity of total possible slots.

CCC_Count	CCC_flat_buffer_sizeof_type (CCC_Flat_buffer const *buffer)
	The size of the type being stored contiguously in the buffer.

CCC_Count	CCC_flat_buffer_count_bytes (CCC_Flat_buffer const *buffer)
	Return the bytes in the Flat_buffer given the current count of active elements.

CCC_Count	CCC_flat_buffer_capacity_bytes (CCC_Flat_buffer const *buffer)
	Return the bytes in the Flat_buffer given the current capacity elements.

CCC_Tribool	CCC_flat_buffer_is_empty (CCC_Flat_buffer const *buffer)
	return true if the size of the Flat_buffer is 0.

CCC_Tribool	CCC_flat_buffer_is_full (CCC_Flat_buffer const *buffer)
	return true if the size of the Flat_buffer equals capacity.

void *	CCC_flat_buffer_data (CCC_Flat_buffer const *buffer)
	return a reference to the underlying data of the buffer.

Deallocation Interface
Free the elements of the container and the underlying buffer.
CCC_Result	CCC_flat_buffer_clear_and_free (CCC_Flat_buffer buffer, CCC_Destructor const destructor, CCC_Allocator const *allocator)
	Set size of buffer to 0 and call destroy on each element if needed. Free the underlying Flat_buffer setting the capacity to 0. O(1) if no destructor is provided, else O(N).

CCC_Result	CCC_flat_buffer_clear (CCC_Flat_buffer buffer, CCC_Destructor const destructor)
	Set size of buffer to 0 and call destroy on each element if needed. O(1) if no destroy is provided, else O(N).

Macro Definition Documentation

◆ CCC_flat_buffer_as

#define CCC_flat_buffer_as	(	flat_buffer_pointer,
		type_name,
		index
	)	((type_name *)CCC_flat_buffer_at(flat_buffer_pointer, index))

Access en element at the specified index as the stored type.

Parameters

[in]	flat_buffer_pointer	the pointer to the buffer.
[in]	type_name	the name of the stored type.
[in]	index	the index within capacity range of the buffer.

Returns: a pointer to the element in the slot at position index or NULL if index is out of capacity range.

Note that as long as the index is valid within the capacity of the Flat_buffer a valid pointer is returned, which may result in a slot of old or uninitialized data. It is up to the user to ensure the index provided is within the current size of the buffer.

◆ CCC_flat_buffer_back_as

#define CCC_flat_buffer_back_as	(	flat_buffer_pointer,
		type_name
	)	((type_name *)CCC_flat_buffer_back(flat_buffer_pointer))

return the final element in the Flat_buffer according the current size.

Parameters

[in]	flat_buffer_pointer	the pointer to the buffer.
[in]	type_name	the name of the stored type.

Returns: the pointer the final element in the Flat_buffer according to the current size or NULL if the Flat_buffer does not exist or is empty.

◆ CCC_flat_buffer_default

#define CCC_flat_buffer_default ( type_name ) CCC_private_flat_buffer_default(type_name)

Initialize a contiguous empty buffer of a type.

Parameters

[in] type_name the name of the user type in the buffer.

Returns: the initialized buffer. Directly assign to Flat_buffer on the right hand side of the equality operator.

Initialization of a Flat_buffer can occur at compile time or run time.

static CCC_Flat_buffer stack = CCC_flat_buffer_default(int);

CCC_flat_buffer_default

#define CCC_flat_buffer_default(type_name)

Initialize a contiguous empty buffer of a type.

Definition: flat_buffer.h:93

CCC_Flat_buffer

Definition: private_flat_buffer.h:32

The buffer will be empty with a count and capacity of 0.

◆ CCC_flat_buffer_emplace

#define CCC_flat_buffer_emplace	(	flat_buffer_pointer,
		index,
		type_compound_literal...
	)

Value:

    CCC_private_flat_buffer_emplace(                                           \
        flat_buffer_pointer, index, type_compound_literal                      \
    )

Writes a user provided compound literal directly to a Flat_buffer slot.

Parameters

[in]	flat_buffer_pointer	a pointer to the buffer.
[in]	index	the desired index at which to insert an element.
[in]	type_compound_literal	the direct compound literal as provided.

Returns: a pointer to the inserted element or NULL if insertion failed.

Warning: The index provided is only checked to be within capacity bounds so it is the user's responsibility to ensure the index is within the contiguous range of [0, size). This insert method does not increment the size of the buffer.

Any function calls that set fields of the compound literal will not be evaluated if the provided index is out of range of the Flat_buffer capacity.

◆ CCC_flat_buffer_emplace_back

#define CCC_flat_buffer_emplace_back	(	flat_buffer_pointer,
		allocator_pointer,
		type_compound_literal...
	)

Value:

    CCC_private_flat_buffer_emplace_back(                                      \
        flat_buffer_pointer, allocator_pointer, type_compound_literal          \
    )

Pushes the user provided compound literal directly to back of buffer and increments the size to reflect the newly added element.

Parameters

[in]	flat_buffer_pointer	a pointer to the buffer.
[in]	allocator_pointer	a pointer to the CCC_Allocator
[in]	type_compound_literal	the direct compound literal as provided.

Returns: a pointer to the inserted element or NULL if insertion failed.

Any function calls that set fields of the compound literal will not be evaluated if the Flat_buffer fails to allocate a slot at the back of the buffer. This may occur if resizing fails or is prohibited.

◆ CCC_flat_buffer_for

#define CCC_flat_buffer_for	(	type_name,
		capacity,
		count,
		data_pointer...
	)	CCC_private_flat_buffer_for(type_name, capacity, count, data_pointer)

Initialize a contiguous Flat_buffer of user a specified type, capacity, and optional starting size.

Parameters

[in]	type_name	the name of the user type in the buffer.
[in]	capacity	the capacity of memory at data_pointer.
[in]	count	optional starting size of the Flat_buffer <= capacity.
[in]	data_pointer	the pointer to existing memory or NULL.

Returns: the initialized buffer. Directly assign to Flat_buffer on the right hand side of the equality operator.

Initialization of a Flat_buffer can occur at compile time or run time depending on the arguments. The memory pointer should be of the same type one intends to store in the buffer.

#define FLAT_BUFFER_USING_NAMESPACE_CCC
static Flat_buffer stack = flat_buffer_for(
    int, 4096, 0, &(static int[4096]){}
);

Initialize a fixed Flat_buffer with some elements occupied.

#define FLAT_BUFFER_USING_NAMESPACE_CCC
static Flat_buffer stack = flat_buffer_for(
    int, 4096, 4, &(static int[4096]){0, 1, 2, 3}
);

Ensure the count is less than equal to capacity.

◆ CCC_flat_buffer_from

#define CCC_flat_buffer_from	(	allocator,
		optional_capacity,
		compound_literal_array...
	)

Value:

    CCC_private_flat_buffer_from(                                              \
        allocator, optional_capacity, compound_literal_array                   \
    )

Initialize a Flat_buffer from a compound literal array initializer.

Parameters

[in]	allocator	a pointer to CCC_Allocator.
[in]	optional_capacity	optionally specify the capacity of the Flat_buffer if different from the size of the compound literal array initializer. If the capacity is greater than the size of the compound literal array initializer, it is respected and the capacity is reserved. If the capacity is less than the size of the compound array initializer, the compound literal array initializer size is set as the capacity. Therefore, 0 is valid if one is not concerned with the underlying reservation.
[in]	compound_literal_array	the initializer of the type stored in buffer.

Returns: the initialized buffer. Directly assign to Flat_buffer on the right hand side of the equality operator (e.g. CCC_Flat_buffer b = CCC_flat_buffer_from(...);).

Initialize a dynamic Flat_buffer with a compound literal array.

#define FLAT_BUFFER_USING_NAMESPACE_CCC
int
main(void)
{
    Flat_buffer b = flat_buffer_from(
        (CCC_Allocator){.allocator = std_allocate},
        0,
        (int[]){ 0, 1, 2, 3 }
    );
    return 0;
}

Initialize a dynamic Flat_buffer with a compound literal array with capacity and context

#define FLAT_BUFFER_USING_NAMESPACE_CCC
int
main(void)
{
    Flat_buffer b = flat_buffer_from(
        ((CCC_Allocator){
            .allocator = arena_allocate,
            .context = &arena,
        }),
        4096,
        (int[]){ 0, 1, 2, 3 }
    );
    return 0;
}

Only dynamic buffers may be initialized this way. For static or stack based initialization of fixed buffers with contents known at compile time, see the CCC_flat_buffer_for() macro.

◆ CCC_flat_buffer_front_as

#define CCC_flat_buffer_front_as	(	flat_buffer_pointer,
		type_name
	)	((type_name *)CCC_flat_buffer_front(flat_buffer_pointer))

return the first element in the Flat_buffer at index 0.

Parameters

[in]	flat_buffer_pointer	the pointer to the buffer.
[in]	type_name	the name of the stored type.

Returns: the pointer to the front element or NULL if the Flat_buffer does not exist or is empty.

◆ CCC_flat_buffer_with_capacity

#define CCC_flat_buffer_with_capacity	(	type_name,
		allocator,
		capacity
	)	CCC_private_flat_buffer_with_capacity(type_name, allocator, capacity)

Initialize a Flat_buffer with a capacity.

Parameters

[in]	type_name	any user or language standard type name.
[in]	allocator	a pointer to CCC_Allocator.
[in]	capacity	the capacity of the Flat_buffer to reserve.

Returns: the initialized buffer. Directly assign to Flat_buffer on the right hand side of the equality operator (e.g. CCC_Flat_buffer b = CCC_flat_buffer_with_capacity(...);).

Initialize a dynamic buffer.

#define FLAT_BUFFER_USING_NAMESPACE_CCC
int
main(void)
{
    Flat_buffer b = flat_buffer_with_capacity(
        int,
        (CCC_Allocator){.allocator = std_allocate},
        4096
    );
    return 0;
}

Only dynamic buffers may be initialized this way. For static or stack based initialization of fixed buffers with contents known at compile time, see the CCC_flat_buffer_for() macro.

◆ CCC_flat_buffer_with_storage

#define CCC_flat_buffer_with_storage	(	count,
		compound_literal_array...
	)	CCC_private_flat_buffer_with_storage(count, compound_literal_array)

Initialize a contiguous Flat_buffer of user a specified type of fixed capacity with no allocation permission or context.

Parameters

[in]	count	starting count of the Flat_buffer <= capacity of input literal.
[in]	compound_literal_array	the compound literal array of types.

Returns: the initialized buffer. Directly assign to Flat_buffer on the right hand side of the equality operator (e.g. CCC_Flat_buffer b = CCC_flat_buffer_with_storage(...);).

Initialization of a Flat_buffer can occur at compile time or run time but always lacks any allocation permissions. The memory pointer should be of the same type one intends to store in the buffer.

#define FLAT_BUFFER_USING_NAMESPACE_CCC

static Flat_buffer stack = flat_buffer_with_storage(0, (static int[4096]){});

Compile time creation of fixed capacity buffers can be a helpful use case when wrapping static or stack based arrays.

Typedef Documentation

◆ CCC_Flat_buffer

typedef struct CCC_Flat_buffer CCC_Flat_buffer

A contiguous block of storage for elements of the same type.

Warning: it is undefined behavior to use an uninitialized buffer.

A Flat_buffer may be initialized on the stack, heap, or data segment at compile time or runtime.

Function Documentation

◆ CCC_flat_buffer_allocate()

CCC_Result CCC_flat_buffer_allocate	(	CCC_Flat_buffer *	buffer,
		size_t	capacity,
		CCC_Allocator const *	allocator
	)

allocates the Flat_buffer to the specified size according to the user defined allocation function.

Parameters

[in]	buffer	a pointer to the buffer.
[in]	capacity	the newly desired capacity.
[in]	allocator	the allocation context defined by the user.

Returns: the result of reallocation.

◆ CCC_flat_buffer_allocate_back()

void * CCC_flat_buffer_allocate_back	(	CCC_Flat_buffer *	buffer,
		CCC_Allocator const *	allocator
	)

allocates a new slot from the Flat_buffer at the end of the contiguous array. A slot is equivalent to one of the element type specified when the Flat_buffer is initialized.

Parameters

[in]	buffer	a pointer to the buffer.
[in]	allocator	the allocation context defined by the user.

Returns: a pointer to the newly allocated memory or NULL if no Flat_buffer is provided or the Flat_buffer is unable to allocate more memory.

Note: this function modifies the size of the container.

A Flat_buffer can be used as the backing for more complex data structures. Requesting new space from a Flat_buffer as an allocator can be helpful for these higher level organizations.

◆ CCC_flat_buffer_at()

void * CCC_flat_buffer_at	(	CCC_Flat_buffer const *	buffer,
		size_t	index
	)

return the element at slot index in buf.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	index	the index within capacity range of the buffer.

Returns: a pointer to the element in the slot at position index or NULL if index is out of capacity range.

Note that as long as the index is valid within the capacity of the Flat_buffer a valid pointer is returned, which may result in a slot of old or uninitialized data. It is up to the user to ensure the index provided is within the current size of the buffer.

◆ CCC_flat_buffer_back()

void * CCC_flat_buffer_back ( CCC_Flat_buffer const * buffer )

return the final element in the Flat_buffer according the current size.

Parameters

[in] buffer the pointer to the buffer.

Returns: the pointer the final element in the Flat_buffer according to the current size or NULL if the Flat_buffer does not exist or is empty.

◆ CCC_flat_buffer_begin()

void * CCC_flat_buffer_begin ( CCC_Flat_buffer const * buffer )

obtain the base address of the Flat_buffer in preparation for iteration.

Parameters

[in] buffer the pointer to the buffer.

Returns: the base address of the buffer. This will be equivalent to the buffer end iterator if the Flat_buffer size is 0. NULL is returned if a NULL argument is provided or the Flat_buffer has not yet been allocated.

◆ CCC_flat_buffer_capacity()

CCC_Count CCC_flat_buffer_capacity ( CCC_Flat_buffer const * buffer )

Return the current capacity of total possible slots.

Parameters

[in] buffer the pointer to the buffer.

Returns: the total number of elements the can be stored in the buffer. This value remains the same until a resize occurs. An argument error is set if buffer is NULL.

◆ CCC_flat_buffer_capacity_bytes()

CCC_Count CCC_flat_buffer_capacity_bytes ( CCC_Flat_buffer const * buffer )

Return the bytes in the Flat_buffer given the current capacity elements.

Parameters

[in] buffer the pointer to the buffer.

Returns: the number of bytes occupied by the current capacity elements.

For total possible bytes that can be stored in the Flat_buffer given the current element count see CCC_flat_buffer_count_bytes.

◆ CCC_flat_buffer_clear()

CCC_Result CCC_flat_buffer_clear	(	CCC_Flat_buffer *	buffer,
		CCC_Destructor const *	destructor
	)

Set size of buffer to 0 and call destroy on each element if needed. O(1) if no destroy is provided, else O(N).

Parameters

[in]	buffer	a pointer to the buf.
[in]	destructor	the destroy function and context if needed, or the empty `&(CCC_Destructor){}` anonymous compound literal if not..

Note that if destroy is non-NULL it will be called on each element in the buf. However, the underlying Flat_buffer for the buffer is not freed. If the destructor is NULL, setting the size to 0 is O(1). Elements are assumed to be contiguous from the 0th index to index at size - 1.

◆ CCC_flat_buffer_clear_and_free()

CCC_Result CCC_flat_buffer_clear_and_free	(	CCC_Flat_buffer *	buffer,
		CCC_Destructor const *	destructor,
		CCC_Allocator const *	allocator
	)

Set size of buffer to 0 and call destroy on each element if needed. Free the underlying Flat_buffer setting the capacity to 0. O(1) if no destructor is provided, else O(N).

Parameters

[in]	buffer	a pointer to the buf.
[in]	destructor	the destroy function and context if needed, or the empty `&(CCC_Destructor){}` anonymous compound literal if not..
[in]	allocator	the allocator context needed to free memory.

Note that if destroy is non-NULL it will be called on each element in the buf. After all elements are processed the Flat_buffer is freed and capacity is 0. If destroy is NULL the Flat_buffer is freed directly and capacity is 0. Elements are assumed to be contiguous from the 0th index to index at size - 1.

◆ CCC_flat_buffer_copy()

CCC_Result CCC_flat_buffer_copy	(	CCC_Flat_buffer *	destination,
		CCC_Flat_buffer const *	source,
		CCC_Allocator const *	allocator
	)

Copy the buffer from source to newly initialized destination.

Parameters

[in]	destination	the destination that will copy the source buf.
[in]	source	the source of the buf.
[in]	allocator	the allocation function in case resizing of destination is needed.

Returns: the result of the copy operation. If the destination capacity is less than the source capacity and no allocation function is provided an input error is returned. If resizing is required and resizing of destination fails a memory error is returned.

Note: destination must have capacity greater than or equal to source. If destination capacity is less than source, an allocation function must be provided with the allocate argument.

Note that there are two ways to copy data from source to destination: provide sufficient memory and pass NULL as allocate, or allow the copy function to take care of allocation for the copy.

Manual memory management with no allocation function provided.

#define FLAT_BUFFER_USING_NAMESPACE_CCC
Flat_buffer source = flat_buffer_with_storage(0, (int[10]){});
int *new_data = malloc(sizeof(int) * flat_buffer_capacity(&source).count);
Flat_buffer destination
    = flat_buffer_for(int, flat_buffer_capacity(&source).count, 0, new_data);
CCC_Result res = flat_buffer_copy(&destination, &source, &(CCC_Allocator){});

The above requires destination capacity be greater than or equal to source capacity. Here is memory management handed over to the copy function.

#define FLAT_BUFFER_USING_NAMESPACE_CCC
Flat_buffer source = flat_buffer_default(int);
(void)push_back_range(&source, 5, (int[5]){0,1,2,3,4}, &std_allocator);
Flat_buffer destination = flat_buffer_default(int);
CCC_Result res = flat_buffer_copy(&destination, &source, &std_allocator);

These options allow users to stay consistent across containers with their memory management strategies.

◆ CCC_flat_buffer_count()

CCC_Count CCC_flat_buffer_count ( CCC_Flat_buffer const * buffer )

obtain the count of Flat_buffer active slots.

Parameters

[in] buffer the pointer to the buffer.

Returns: the quantity of elements stored in the buffer. An argument error is set if buffer is NULL.

Note that size must be less than or equal to capacity.

◆ CCC_flat_buffer_count_bytes()

CCC_Count CCC_flat_buffer_count_bytes ( CCC_Flat_buffer const * buffer )

Return the bytes in the Flat_buffer given the current count of active elements.

Parameters

[in] buffer the pointer to the buffer.

Returns: the number of bytes occupied by the current count of elements.

For total possible bytes that can be stored in the Flat_buffer see CCC_flat_buffer_capacity_bytes.

◆ CCC_flat_buffer_count_minus()

CCC_Result CCC_flat_buffer_count_minus	(	CCC_Flat_buffer *	buffer,
		size_t	count
	)

Subtract count from the size of the buffer.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	count	the quantity to subtract from the current Flat_buffer size.

Returns: the result of resizing. CCC_RESULT_OK if no errors occur or an error indicating bad input has been provided.

If count would reduce the size to less than 0, the Flat_buffer size is set to 0 and the input error status is returned.

◆ CCC_flat_buffer_count_plus()

CCC_Result CCC_flat_buffer_count_plus	(	CCC_Flat_buffer *	buffer,
		size_t	count
	)

add count to the size of the buffer.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	count	the quantity to add to the current Flat_buffer size.

Returns: the result of resizing. CCC_RESULT_OK if no errors occur or an error indicating bad input has been provided.

If count would exceed the current capacity of the Flat_buffer the size is set to capacity and the input error status is returned.

◆ CCC_flat_buffer_count_set()

CCC_Result CCC_flat_buffer_count_set	(	CCC_Flat_buffer *	buffer,
		size_t	count
	)

Set the Flat_buffer size to n.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	count	the new size of the buffer.

Returns: the result of setting the size. CCC_RESULT_OK if no errors occur or an error indicating bad input has been provided.

If count is larger than the capacity of the Flat_buffer the size is set equal to the capacity and an error is returned.

◆ CCC_flat_buffer_data()

void * CCC_flat_buffer_data ( CCC_Flat_buffer const * buffer )

return a reference to the underlying data of the buffer.

Parameters

[in] buffer the pointer to the buffer.

Returns: NULL if empty or buffer pointer is NULL, otherwise the base of the underlying buffer.

Warning: It is the user's responsibility to remain within bounds of this reference according to the capacity provided to the buffer.

◆ CCC_flat_buffer_end()

void * CCC_flat_buffer_end ( CCC_Flat_buffer const * buffer )

return the end position of the Flat_buffer according to size.

Parameters

[in] buffer the pointer to the buffer.

Returns: the address of the end position. It is undefined to access this position for any reason. NULL is returned if NULL is provided or Flat_buffer has not yet been allocated.

Note that end is determined by the size of the Flat_buffer dynamically.

◆ CCC_flat_buffer_erase()

CCC_Result CCC_flat_buffer_erase	(	CCC_Flat_buffer *	buffer,
		size_t	index
	)

erase element at slot index according to size of the Flat_buffer maintaining contiguous storage of elements between 0 and size.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	index	the index of the element to be erased.

Returns: the result, CCC_RESULT_OK if the input is valid. If no Flat_buffer exists or i is out of range of size then an input error is returned.

Note: this function modifies the size of the container.

Note that this function assumes elements must be maintained contiguously according to size meaning a bulk copy of elements sliding down to fill the space left by index will occur.

◆ CCC_flat_buffer_front()

void * CCC_flat_buffer_front ( CCC_Flat_buffer const * buffer )

return the first element in the Flat_buffer at index 0.

Parameters

[in] buffer the pointer to the buffer.

Returns: the pointer to the front element or NULL if the Flat_buffer does not exist or is empty.

◆ CCC_flat_buffer_index()

CCC_Count CCC_flat_buffer_index	(	CCC_Flat_buffer const *	buffer,
		void const *	slot
	)

return the index of an element known to be in the buffer.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	slot	the pointer to the element stored in the buffer.

Returns: the index if the slot provided is within the capacity range of the buffer, otherwise an argument error is set.

◆ CCC_flat_buffer_insert()

void * CCC_flat_buffer_insert	(	CCC_Flat_buffer *	buffer,
		size_t	index,
		void const *	data,
		CCC_Allocator const *	allocator
	)

insert data at slot index according to size of the Flat_buffer maintaining contiguous storage of elements between 0 and size.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	index	the index at which to insert data.
[in]	data	the data copied into the Flat_buffer at index index of the same size
[in]	allocator	the allocation context defined by the user. as elements stored in the buffer.

Returns: the pointer to the inserted element or NULL if bad input is provided, the Flat_buffer is full and no resizing is allowed, or resizing fails when resizing is allowed.

Note: this function modifies the size of the container.

Note that this function assumes elements must be maintained contiguously according to size of the Flat_buffer meaning a bulk move of elements sliding down to accommodate index will occur.

◆ CCC_flat_buffer_is_empty()

CCC_Tribool CCC_flat_buffer_is_empty ( CCC_Flat_buffer const * buffer )

return true if the size of the Flat_buffer is 0.

Parameters

[in] buffer the pointer to the buffer.

Returns: true if the size is 0 false if not. Error if buffer is NULL.

◆ CCC_flat_buffer_is_full()

CCC_Tribool CCC_flat_buffer_is_full ( CCC_Flat_buffer const * buffer )

return true if the size of the Flat_buffer equals capacity.

Parameters

[in] buffer the pointer to the buffer.

Returns: true if the size equals the capacity. Error if buffer is NULL.

◆ CCC_flat_buffer_move()

void * CCC_flat_buffer_move	(	CCC_Flat_buffer const *	buffer,
		size_t	destination,
		size_t	source
	)

Move data at index source to destination according to capacity.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	destination	the index of destination within bounds of capacity.
[in]	source	the index of source within bounds of capacity.

Returns: a pointer to the slot at destination or NULL if bad input is provided.

Note: this function does NOT modify the size of the container.

Note that destination and source are only required to be valid within bounds of capacity of the buffer. It is up to the user to ensure destination and source are within the size bounds of the buffer, if required.

◆ CCC_flat_buffer_next()

void * CCC_flat_buffer_next	(	CCC_Flat_buffer const *	buffer,
		void const *	iterator
	)

advance the iterator to the next slot in the Flat_buffer according to size.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	iterator	the pointer to the current slot of the buffer.

Returns: the next iterator position according to size.

◆ CCC_flat_buffer_pop_back()

CCC_Result CCC_flat_buffer_pop_back ( CCC_Flat_buffer * buffer )

pop the back element from the Flat_buffer according to size.

Parameters

[in] buffer the pointer to the buffer.

Returns: the result of the attempted pop. CCC_RESULT_OK upon success or an input error if bad input is provided.

Note: this function modifies the size of the container.

◆ CCC_flat_buffer_pop_back_n()

CCC_Result CCC_flat_buffer_pop_back_n	(	CCC_Flat_buffer *	buffer,
		size_t	count
	)

pop count elements from the back of the Flat_buffer according to size.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	count	the number of elements to pop.

Returns: the result of the attempted pop. CCC_RESULT_OK if the Flat_buffer exists and n is within the bounds of size. If the Flat_buffer does not exist an input error is returned. If count is greater than the size of the Flat_buffer size is set to zero and input error is returned.

Note: this function modifies the size of the container.

◆ CCC_flat_buffer_push_back()

void * CCC_flat_buffer_push_back	(	CCC_Flat_buffer *	buffer,
		void const *	data,
		CCC_Allocator const *	allocator
	)

return the newly pushed data into the last slot of the buffer according to size.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	data	the pointer to the data of element size.
[in]	allocator	the allocation context defined by the user.

Returns: the pointer to the newly pushed element or NULL if no Flat_buffer exists or resizing has failed due to memory exhuastion or no allocation allowed.

Note: this function modifies the size of the container.

The data is copied into the Flat_buffer at the final slot if there is remaining capacity. If size is equal to capacity resizing will be attempted but may fail if no allocation function is provided or the allocator provided is exhausted.

◆ CCC_flat_buffer_reserve()

CCC_Result CCC_flat_buffer_reserve	(	CCC_Flat_buffer *	buffer,
		size_t	to_add,
		CCC_Allocator const *	allocator
	)

Reserves space for at least to_add more elements.

Parameters

[in]	buffer	a pointer to the buffer.
[in]	to_add	the number of elements to add to the current size.
[in]	allocator	the allocation function to use to reserve memory.

Returns: the result of the reservation. OK if successful, otherwise an error status is returned.

◆ CCC_flat_buffer_reverse_begin()

void * CCC_flat_buffer_reverse_begin ( CCC_Flat_buffer const * buffer )

obtain the address of the last element in the Flat_buffer in preparation for iteration according to size.

Parameters

[in] buffer the pointer to the buffer.

Returns: the address of the last element buffer. This will be equivalent to the Flat_buffer reverse_end iterator if the Flat_buffer size is 0. NULL is returned if a NULL argument is provided or the Flat_buffer has not yet been allocated.

◆ CCC_flat_buffer_reverse_end()

void * CCC_flat_buffer_reverse_end ( CCC_Flat_buffer const * buffer )

return the reverse_end position of the buffer.

Parameters

[in] buffer the pointer to the buffer.

Returns: the address of the reverse_end position. It is undefined to access this position for any reason. NULL is returned if NULL is provided or Flat_buffer has not yet been allocated.

◆ CCC_flat_buffer_reverse_next()

void * CCC_flat_buffer_reverse_next	(	CCC_Flat_buffer const *	buffer,
		void const *	iterator
	)

advance the iterator to the next slot in the Flat_buffer according to size and in reverse order.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	iterator	the pointer to the current slot of the buffer.

Returns: the next iterator position according to size and in reverse order. NULL is returned if bad input is provided or the Flat_buffer has not been allocated.

◆ CCC_flat_buffer_sizeof_type()

CCC_Count CCC_flat_buffer_sizeof_type ( CCC_Flat_buffer const * buffer )

The size of the type being stored contiguously in the buffer.

Parameters

[in] buffer the pointer to the buffer.

Returns: the size of the type being stored in the buffer. 0 if buffer is NULL because a zero sized object is not possible for a buffer.

◆ CCC_flat_buffer_swap()

CCC_Result CCC_flat_buffer_swap	(	CCC_Flat_buffer const *	buffer,
		void *	temp,
		size_t	index,
		size_t	swap_index
	)

swap elements at index and swap_index according to capacity of the bufer.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	temp	the pointer to the temporary Flat_buffer of the same size as an element stored in the buffer.
[in]	index	the index of an element in the buffer.
[in]	swap_index	the index of an element in the buffer.

Returns: the result of the swap, CCC_RESULT_OK if no error occurs. If no buffer exists, no temp exists, index is out of capacity range, or swap_index is out of capacity range, an input error is returned.

Note: this function does NOT modify the size of the container.

Note that index and swap_index are only checked to be within capacity range of the buffer. It is the user's responsibility to check for index and swap_index within bounds of size if such behavior is needed.

◆ CCC_flat_buffer_write()

CCC_Result CCC_flat_buffer_write	(	CCC_Flat_buffer const *	buffer,
		size_t	index,
		void const *	data
	)

write data to Flat_buffer at slot at index index according to capacity.

Parameters

[in]	buffer	the pointer to the buffer.
[in]	index	the index within bounds of capacity of the buffer.
[in]	data	the data that will be written to slot at i.

Returns: the result of the write, CCC_RESULT_OK if success. If no Flat_buffer or data exists input error is returned. If index is outside of the range of capacity input error is returned.

Note: this function does NOT modify the size of the container.

Note that data will be written to the slot at index i, according to the capacity of the buffer. It is up to the user to ensure index is within size of the Flat_buffer if such behavior is desired. No elements are moved to be preserved meaning any data at index is overwritten.

Detailed Description

Initialization Interface

Insert and Remove Interface

Slot Management Interface

Container Types

Iteration Interface

State Interface

Deallocation Interface

Macro Definition Documentation

◆ CCC_flat_buffer_as

◆ CCC_flat_buffer_back_as

◆ CCC_flat_buffer_default

◆ CCC_flat_buffer_emplace

◆ CCC_flat_buffer_emplace_back

◆ CCC_flat_buffer_for

◆ CCC_flat_buffer_from

◆ CCC_flat_buffer_front_as

◆ CCC_flat_buffer_with_capacity

◆ CCC_flat_buffer_with_storage

Typedef Documentation

◆ CCC_Flat_buffer

Function Documentation

◆ CCC_flat_buffer_allocate()

◆ CCC_flat_buffer_allocate_back()

◆ CCC_flat_buffer_at()

◆ CCC_flat_buffer_back()

◆ CCC_flat_buffer_begin()

◆ CCC_flat_buffer_capacity()

◆ CCC_flat_buffer_capacity_bytes()

◆ CCC_flat_buffer_clear()

◆ CCC_flat_buffer_clear_and_free()

◆ CCC_flat_buffer_copy()

◆ CCC_flat_buffer_count()

◆ CCC_flat_buffer_count_bytes()

◆ CCC_flat_buffer_count_minus()

◆ CCC_flat_buffer_count_plus()

◆ CCC_flat_buffer_count_set()

◆ CCC_flat_buffer_data()

◆ CCC_flat_buffer_end()

◆ CCC_flat_buffer_erase()

◆ CCC_flat_buffer_front()

◆ CCC_flat_buffer_index()

◆ CCC_flat_buffer_insert()

◆ CCC_flat_buffer_is_empty()

◆ CCC_flat_buffer_is_full()

◆ CCC_flat_buffer_move()

◆ CCC_flat_buffer_next()

◆ CCC_flat_buffer_pop_back()

◆ CCC_flat_buffer_pop_back_n()

◆ CCC_flat_buffer_push_back()

◆ CCC_flat_buffer_reserve()

◆ CCC_flat_buffer_reverse_begin()

◆ CCC_flat_buffer_reverse_end()

◆ CCC_flat_buffer_reverse_next()

◆ CCC_flat_buffer_sizeof_type()

◆ CCC_flat_buffer_swap()

◆ CCC_flat_buffer_write()