|
C Container Collection (CCC)
|
The C Container Collection Fundamental Types. More...

Go to the source code of this file.
The C Container Collection Fundamental Types.
All containers make use of the fundamental types defined here. The purpose of these types is to aid the user in writing correct callback functions, allow clear error handling, and present a consistent interface to users across containers. If an allocator is passed to container functions be sure to review the allocator function interface.
Data Structures | |
| struct | CCC_Range |
| The result of a range query on iterable containers. More... | |
| struct | CCC_Range_reverse |
| The result of a range_reverse query on iterable containers. More... | |
| struct | CCC_Handle_range |
| The result of a range query on iterable containers. Handles are stable indices into an array until removed, regardless of other insertions, removals, or array resizing. More... | |
| struct | CCC_Handle_range_reverse |
| The result of a range_reverse query on iterable containers. Handles are stable indices into an array until removed, regardless of other insertions, removals, or array resizing. More... | |
| struct | CCC_Entry |
| An Occupied or Vacant position in a searchable container. More... | |
| struct | CCC_Handle |
| An Occupied or Vacant handle to a flat searchable container entry. More... | |
| struct | CCC_Count |
| A type for returning an unsigned integer from a container for counting. Intended to count sizes, capacities, and 0-based indices. More... | |
| struct | CCC_Arguments |
| A reference to a user type within the container. More... | |
| struct | CCC_Allocator_arguments |
| A bundle of arguments to pass to the user-implemented Allocator_interface function interface. This ensures clarity in inputs and expected outputs to an allocator function the user wishes to use for managing containers. Additional context can be provided for more complex allocation schemes. More... | |
| struct | CCC_Allocator |
The type passed by reference to any container function that may need to allocate memory. The allocation function controls allocation, resizing, and freeing of memory. The context pointer references any auxiliary information needed to support the allocation function. The context pointer is passed as the context argument of the CCC_Allocator_arguments type, when provided. More... | |
| struct | CCC_Comparator_arguments |
| An element comparison helper. More... | |
| struct | CCC_Comparator |
The type passed by reference to any container function that may need to compare elements. The context pointer is passed as the context argument of the CCC_Comparator_arguments type, when provided. More... | |
| struct | CCC_Modifier |
The type passed by reference to any container function that may need to modify elements. The context pointer is passed as the context argument of the CCC_Arguments type, when provided. More... | |
| struct | CCC_Destructor |
The type passed by reference to any container function that may need to destroy elements. The context pointer is passed as the context argument of the CCC_Arguments type, when provided. More... | |
| struct | CCC_Key_comparator_arguments |
| A key comparison helper to avoid argument swapping. More... | |
| struct | CCC_Key_comparator |
The type passed by reference to any container function that may need to compare keys. The context pointer is passed as the context argument of the CCC_Key_comparator_arguments type, when provided. More... | |
| struct | CCC_Key_arguments |
| A read only reference to a key type matching the key field type used for hash containers. More... | |
| struct | CCC_Hasher |
The type passed by reference to a hash map that needs a hash function and key comparison function. These fields are owned and stored within the hash map metadata struct because they provide the invariants of the container hashing and comparison algorithm. The fields are provided as arguments to the CCC_Key_arguments type for hashing and the CCC_Key_comparator_arguments type for key comparison when needed for the user defined functions that accept those types. More... | |
Container Types | |
Types used across many containers. | |
| enum | CCC_Entry_status : uint8_t { CCC_ENTRY_VACANT = 0 , CCC_ENTRY_OCCUPIED = 0x1 , CCC_ENTRY_INSERT_ERROR = 0x2 , CCC_ENTRY_ARGUMENT_ERROR = 0x4 , CCC_ENTRY_NO_UNWRAP = 0x8 } |
| The status monitoring and entry state once it is obtained. More... | |
| enum | CCC_Tribool : int8_t { CCC_TRIBOOL_ERROR = -1 , CCC_FALSE , CCC_TRUE } |
| A three state boolean to allow for an error state. Error is -1, False is 0, and True is 1. More... | |
| enum | CCC_Result : uint8_t { CCC_RESULT_OK = 0 , CCC_RESULT_FAIL , CCC_RESULT_NO_ALLOCATION_FUNCTION , CCC_RESULT_ALLOCATOR_ERROR , CCC_RESULT_ARGUMENT_ERROR , CCC_PRIVATE_RESULT_COUNT } |
| A result of actions on containers. More... | |
| enum | CCC_Order : int8_t { CCC_ORDER_LESSER = -1 , CCC_ORDER_EQUAL , CCC_ORDER_GREATER , CCC_ORDER_ERROR } |
| A three-way comparison for comparison functions. More... | |
| typedef size_t | CCC_Handle_index |
| A stable index to user data in a container that uses a flat array as the underlying storage method. | |
| typedef CCC_Entry_status | CCC_Handle_status |
| The status monitoring and handle state once it is obtained. | |
| typedef void * | CCC_Allocator_interface(CCC_Allocator_arguments) |
| An allocation function at the core of all containers. | |
| typedef CCC_Order | CCC_Comparator_interface(CCC_Comparator_arguments) |
| A callback function for comparing two elements in a container. | |
| typedef void | CCC_Modifier_interface(CCC_Arguments) |
| A callback function for modifying an element in the container. | |
| typedef void | CCC_Destructor_interface(CCC_Arguments) |
| A callback function for destroying an element in the container. | |
| typedef CCC_Order | CCC_Key_comparator_interface(CCC_Key_comparator_arguments) |
| A callback function for three-way comparing two stored keys. | |
| typedef uint64_t | CCC_Key_hasher_interface(CCC_Key_arguments) |
| A callback function to hash the key type used in a container. | |
Entry Interface | |
The generic interface for associative container entries. | |
| CCC_Tribool | CCC_entry_occupied (CCC_Entry const *entry) |
| Determine if an entry is Occupied in the container. | |
| CCC_Tribool | CCC_entry_insert_error (CCC_Entry const *entry) |
| Determine if an insertion error has occurred when a function that attempts to insert a value in a container is used. | |
| CCC_Tribool | CCC_entry_argument_error (CCC_Entry const *entry) |
| Determine if an input error has occurred for a function that generates an entry. | |
| void * | CCC_entry_unwrap (CCC_Entry const *entry) |
| Unwraps the provided entry providing a reference to the user type obtained from the operation that provides the entry. | |
| CCC_Tribool | CCC_handle_occupied (CCC_Handle const *handle) |
| Determine if an handle is Occupied in the container. | |
| CCC_Tribool | CCC_handle_insert_error (CCC_Handle const *handle) |
| Determine if an insertion error has occurred when a function that attempts to insert a value in a container is used. | |
| CCC_Tribool | CCC_handle_argument_error (CCC_Handle const *handle) |
| Determine if an input error has occurred for a function that generates an handle. | |
| CCC_Handle_index | CCC_handle_unwrap (CCC_Handle const *handle) |
| Unwraps the provided handle providing a reference to the user type obtained from the operation that provides the handle. | |
Range Interface | |
The generic range interface for associative containers. | |
| void * | CCC_range_begin (CCC_Range const *range) |
| Obtain a reference to the beginning user element stored in a container in the provided range. | |
| void * | CCC_range_end (CCC_Range const *range) |
| Obtain a reference to the end user element stored in a container in the provided range. | |
| void * | CCC_range_reverse_begin (CCC_Range_reverse const *range) |
| Obtain a reference to the reverse beginning user element stored in a container in the provided range. | |
| void * | CCC_range_reverse_end (CCC_Range_reverse const *range) |
| Obtain a reference to the reverse end user element stored in a container in the provided range. | |
| CCC_Handle_index | CCC_handle_range_begin (CCC_Handle_range const *range) |
| Obtain a handle to the beginning user element stored in a container in the provided range. | |
| CCC_Handle_index | CCC_handle_range_end (CCC_Handle_range const *range) |
| Obtain a handle to the end user element stored in a container in the provided range. | |
| CCC_Handle_index | CCC_handle_range_reverse_begin (CCC_Handle_range_reverse const *range) |
| Obtain a handle to the reverse beginning user element stored in a container in the provided range. | |
| CCC_Handle_index | CCC_handle_range_reverse_end (CCC_Handle_range_reverse const *range) |
| Obtain a handle to the reverse end user element stored in a container in the provided range. | |
Status Interface | |
Functions for obtaining more descriptive status information. | |
| char const * | CCC_result_message (CCC_Result result) |
| Obtain a string message with a description of the error returned from a container operation, possible causes, and possible fixes to such error. | |
| CCC_Entry_status | CCC_entry_status (CCC_Entry const *entry) |
| Obtain the entry status from a generic entry. | |
| CCC_Handle_status | CCC_handle_status (CCC_Handle const *handle) |
| Obtain the handle status from a generic handle. | |
| char const * | CCC_entry_status_message (CCC_Entry_status status) |
| Obtain a string message with a description of the entry status. | |
| char const * | CCC_handle_status_message (CCC_Handle_status status) |
| Obtain a string message with a description of the handle status. | |
| typedef void * CCC_Allocator_interface(CCC_Allocator_arguments) |
An allocation function at the core of all containers.
An allocation function implements the following behavior, when it has been passed an allocator context. Context is passed to a container upon its initialization and the programmer may choose how to best utilize this reference (more on context later).
For example, one solution using the standard library allocator might be implemented as follows (context is not needed):
However, the above example is only useful if the standard library allocator is used. Any allocator that implements the required behavior is sufficient. For example programs that utilize the context parameter, see the sample programs. Using custom arena allocators or container compositions are cases when context is needed.
| typedef CCC_Order CCC_Comparator_interface(CCC_Comparator_arguments) |
A callback function for comparing two elements in a container.
A three-way comparison return value is expected and the two containers being compared are guaranteed to be non-NULL and pointing to the base of the user type stored in the container. Context may be NULL if no context is provided on initialization.
| typedef void CCC_Destructor_interface(CCC_Arguments) |
A callback function for destroying an element in the container.
A reference to the container type and any context data provided on initialization is available. The container pointer points to the base of the user type and is not NULL. Context may be NULL if no context is provided on initialization. A destructor function is used to act on each element of the container when it is being emptied and destroyed. The function will be called on each type after it removed from the container and before it is freed by the container, if allocation permission is provided to the container. Therefore, if the user has given permission to the container to allocate memory they can assume the container will free each element with the provided allocation function; this function can be used for any other program state to be maintained before the container frees. If the user has not given permission to the container to allocate memory, this a good function in which to free each element, if desired; any program state can be maintained then the element can be freed by the user in this function as the final step.
| typedef size_t CCC_Handle_index |
A stable index to user data in a container that uses a flat array as the underlying storage method.
User data at a handle position in an array remains valid until that element is removed from the container. This means that resizing of the underlying array may occur, but the handle index remains valid regardless.
This is similar to pointer stability except that pointers would not remain valid when the underlying array is resized; a handle remains valid because it is an index not a pointer.
| typedef CCC_Entry_status CCC_Handle_status |
The status monitoring and handle state once it is obtained.
To manage safe and efficient views into associative containers entries use status flags internally. The provided functions in the Handle Interface for each container are sufficient to obtain the needed status. However if more information is needed, the status can be passed to the CCC_entry_status_message() function for detailed string messages regarding the handle status. This may be helpful for debugging or logging.
| typedef CCC_Order CCC_Key_comparator_interface(CCC_Key_comparator_arguments) |
A callback function for three-way comparing two stored keys.
The key is considered the left hand side of the comparison. The function should return CCC_ORDER_LESSER if the key is less than the key in key field of user type, CCC_ORDER_EQUAL if equal, and CCC_ORDER_GREATER if greater.
| typedef uint64_t CCC_Key_hasher_interface(CCC_Key_arguments) |
A callback function to hash the key type used in a container.
A reference to any context data provided on initialization is also available. Return the complete hash value as determined by the user hashing algorithm.
| typedef void CCC_Modifier_interface(CCC_Arguments) |
A callback function for modifying an element in the container.
A reference to the container type and any context data provided on initialization is available. The container pointer points to the base of the user type and is not NULL. Context may be NULL if no context is provided on initialization. An update function is used when a container Interface exposes functions to modify the key or value used to determine sorted order of elements in the container.
| enum CCC_Entry_status : uint8_t |
The status monitoring and entry state once it is obtained.
To manage safe and efficient views into associative containers entries use status flags internally. The provided functions in the Entry Interface for each container are sufficient to obtain the needed status. However if more information is needed, the status can be passed to the CCC_entry_status_message() function for detailed string messages regarding the entry status. This may be helpful for debugging or logging.
| enum CCC_Order : int8_t |
A three-way comparison for comparison functions.
A C style three way comparison value (e.g. ((a > b) - (a < b))). CCC_ORDER_LESSER if left hand side is less than right hand side, CCC_ORDER_EQUAL if they are equal, and CCC_ORDER_GREATER if left hand side is greater than right hand side.
| enum CCC_Result : uint8_t |
A result of actions on containers.
A result indicates the status of the requested operation. Each container provides status messages according to the result type returned from a operation that uses this type.
| enum CCC_Tribool : int8_t |
A three state boolean to allow for an error state. Error is -1, False is 0, and True is 1.
Some containers conceptually take or return a boolean value as part of their operations. However, booleans cannot indicate errors and this library offers no errno or C++ throw-like behavior. Therefore, a three state value can offer additional information while still maintaining the truthy and falsey bool behavior one would normally expect.
A third branch can be added while otherwise using simple true(1) and false(0). if (result == CCC_TRIBOOL_ERROR) {} else if (result) {} else {}.
| CCC_Tribool CCC_entry_argument_error | ( | CCC_Entry const * | entry | ) |
Determine if an input error has occurred for a function that generates an entry.
| [in] | entry | the pointer to the entry obtained from a container function. |
| CCC_Tribool CCC_entry_insert_error | ( | CCC_Entry const * | entry | ) |
Determine if an insertion error has occurred when a function that attempts to insert a value in a container is used.
| [in] | entry | the pointer to the entry obtained from a container insert. |
| CCC_Tribool CCC_entry_occupied | ( | CCC_Entry const * | entry | ) |
Determine if an entry is Occupied in the container.
| [in] | entry | the pointer to the entry obtained from a container. |
| CCC_Entry_status CCC_entry_status | ( | CCC_Entry const * | entry | ) |
Obtain the entry status from a generic entry.
| [in] | entry | a pointer to the entry. |
| char const * CCC_entry_status_message | ( | CCC_Entry_status | status | ) |
Obtain a string message with a description of the entry status.
| [in] | status | the status obtained from an entry. |
Note that status for an entry is relevant when it is first obtained and when an action completes. Obtaining an entry can provide information on whether the search yielded an Occupied or Vacant Entry or any errors that may have occurred. If a function tries to complete an action like insertion or removal the status can reflect if any errors occurred in this process as well. Usually, the provided interface gives all the functions needed to check status but these strings can be used when more details are required.
| void * CCC_entry_unwrap | ( | CCC_Entry const * | entry | ) |
Unwraps the provided entry providing a reference to the user type obtained from the operation that provides the entry.
| [in] | entry | the pointer to the entry obtained from an operation. |
The expected return value from unwrapping a value will change depending on the container from which the entry is obtained. Read the documentation for the container being used to understand what to expect from this function once an entry is obtained.
| CCC_Tribool CCC_handle_argument_error | ( | CCC_Handle const * | handle | ) |
Determine if an input error has occurred for a function that generates an handle.
| [in] | handle | the pointer to the handle obtained from a container function. |
| CCC_Tribool CCC_handle_insert_error | ( | CCC_Handle const * | handle | ) |
Determine if an insertion error has occurred when a function that attempts to insert a value in a container is used.
| [in] | handle | the pointer to the handle obtained from a container insert. |
| CCC_Tribool CCC_handle_occupied | ( | CCC_Handle const * | handle | ) |
Determine if an handle is Occupied in the container.
| [in] | handle | the pointer to the handle obtained from a container. |
| CCC_Handle_index CCC_handle_range_begin | ( | CCC_Handle_range const * | range | ) |
Obtain a handle to the beginning user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the beginning of a range may be equivalent to the end or NULL.
| CCC_Handle_index CCC_handle_range_end | ( | CCC_Handle_range const * | range | ) |
Obtain a handle to the end user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the end of a range may be equivalent to the beginning or 0. Functions that obtain ranges treat the end as an exclusive bound and therefore it is undefined to access this element.
| CCC_Handle_index CCC_handle_range_reverse_begin | ( | CCC_Handle_range_reverse const * | range | ) |
Obtain a handle to the reverse beginning user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the reverse beginning of a range may be equivalent to the reverse end or 0.
| CCC_Handle_index CCC_handle_range_reverse_end | ( | CCC_Handle_range_reverse const * | range | ) |
Obtain a handle to the reverse end user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the reverse end of a range may be equivalent to the reverse beginning or 0. Functions that obtain ranges treat the reverse end as an exclusive bound and therefore it is undefined to access this element.
| CCC_Handle_status CCC_handle_status | ( | CCC_Handle const * | handle | ) |
Obtain the handle status from a generic handle.
| [in] | handle | a pointer to the handle. |
| char const * CCC_handle_status_message | ( | CCC_Handle_status | status | ) |
Obtain a string message with a description of the handle status.
| [in] | status | the status obtained from an handle. |
Note that status for an handle is relevant when it is first obtained and when an action completes. Obtaining a handle can provide information on whether the search yielded an Occupied or Vacant handle or any errors that may have occurred. If a function tries to complete an action like insertion or removal the status can reflect if any errors occurred in this process as well. Usually, the provided interface gives all the functions needed to check status but these strings can be used when more details are required.
| CCC_Handle_index CCC_handle_unwrap | ( | CCC_Handle const * | handle | ) |
Unwraps the provided handle providing a reference to the user type obtained from the operation that provides the handle.
| [in] | handle | the pointer to the handle obtained from an operation. |
The expected return value from unwrapping a value will change depending on the container from which the handle is obtained. Read the documentation for the container being used to understand what to expect from this function once an handle is obtained.
| void * CCC_range_begin | ( | CCC_Range const * | range | ) |
Obtain a reference to the beginning user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the beginning of a range may be equivalent to the end or NULL.
| void * CCC_range_end | ( | CCC_Range const * | range | ) |
Obtain a reference to the end user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the end of a range may be equivalent to the beginning or NULL. Functions that obtain ranges treat the end as an exclusive bound and therefore it is undefined to access this element.
| void * CCC_range_reverse_begin | ( | CCC_Range_reverse const * | range | ) |
Obtain a reference to the reverse beginning user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the reverse beginning of a range may be equivalent to the reverse end or NULL.
| void * CCC_range_reverse_end | ( | CCC_Range_reverse const * | range | ) |
Obtain a reference to the reverse end user element stored in a container in the provided range.
| [in] | range | a pointer to the range. |
Note the reverse end of a range may be equivalent to the reverse beginning or NULL. Functions that obtain ranges treat the reverse end as an exclusive bound and therefore it is undefined to access this element.
| char const * CCC_result_message | ( | CCC_Result | result | ) |
Obtain a string message with a description of the error returned from a container operation, possible causes, and possible fixes to such error.
| [in] | result | the result obtained from a container operation. |
These messages can be used for logging or to help with debugging by providing more information for why such a result might be obtained from a container.