C Container Collection (CCC)
Loading...
Searching...
No Matches
types.h File Reference

The C Container Collection Fundamental Types. More...

#include "private/private_types.h"
Include dependency graph for types.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Detailed Description

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 allocation permission is given to containers be sure to review the allocator function interface.

Data Structures

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_Type_comparator_context
 An element comparison helper. More...
 
struct  CCC_Key_comparator_context
 A key comparison helper to avoid argument swapping. More...
 
struct  CCC_Type_context
 A reference to a user type within the container. More...
 
struct  CCC_Key_context
 A read only reference to a key type matching the key field type used for hash containers. More...
 
struct  CCC_Allocator_context
 A bundle of arguments to pass to the user-implemented Allocator 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...
 

Container Types

Types used across many containers.

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 union CCC_Range_wrap CCC_Range
 The result of a range query on iterable containers.
 
typedef union CCC_Range_reverse_wrap CCC_Range_reverse
 The result of a range_reverse query on iterable containers.
 
typedef union CCC_Handle_range_wrap CCC_Handle_range
 The result of a range query on iterable containers.
 
typedef union CCC_Handle_range_reverse_wrap CCC_Handle_range_reverse
 The result of a range_reverse query on iterable containers.
 
typedef union CCC_Entry_wrap CCC_Entry
 An Occupied or Vacant position in a searchable container.
 
typedef enum CCC_Entry_status CCC_Entry_status
 The status monitoring and entry state once it is obtained.
 
typedef union CCC_Handle_wrap CCC_Handle
 An Occupied or Vacant handle to a flat searchable container entry.
 
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 enum CCC_Entry_status CCC_Handle_status
 The status monitoring and handle state once it is obtained.
 
typedef void * CCC_Allocator(CCC_Allocator_context)
 An allocation function at the core of all containers.
 
typedef CCC_Order CCC_Type_comparator(CCC_Type_comparator_context)
 A callback function for comparing two elements in a container.
 
typedef void CCC_Type_modifier(CCC_Type_context)
 A callback function for modifying an element in the container.
 
typedef void CCC_Type_destructor(CCC_Type_context)
 A callback function for destroying an element in the container.
 
typedef CCC_Order CCC_Key_comparator(CCC_Key_comparator_context)
 A callback function for three-way comparing two stored keys.
 
typedef uint64_t CCC_Key_hasher(CCC_Key_context)
 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_input_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_input_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_array_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_array_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_array_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_array_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_get_entry_status (CCC_Entry const *entry)
 Obtain the entry status from a generic entry.
 
CCC_Handle_status CCC_get_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 Documentation

◆ CCC_Allocator

typedef void * CCC_Allocator(CCC_Allocator_context)

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).

  • If input is NULL and bytes 0, NULL is returned.
  • If input is NULL with non-zero bytes, new memory is allocated/returned.
  • If input is non-NULL it has been previously allocated by the Allocator.
  • If input is non-NULL with non-zero size, input is resized to at least bytes size. The pointer returned is NULL if resizing fails. Upon success, the pointer returned might not be equal to the pointer provided.
  • If input is non-NULL and size is 0, input is freed and NULL is returned.

One may be tempted to use realloc to check all of these boxes but realloc is implementation defined on some of these points. So, the context parameter also discourages users from providing realloc. For example, one solution using the standard library allocator might be implemented as follows (context is not needed):

void *
std_allocate(CCC_Allocator_context const context)
{
if (!context.input && !context.bytes)
{
return NULL;
}
if (!context.input)
{
return malloc(context.bytes);
}
if (!context.bytes)
{
free(context.input);
return NULL;
}
return realloc(context.input, context.bytes);
}
A bundle of arguments to pass to the user-implemented Allocator function interface....
Definition: types.h:284
void * input
Definition: types.h:286
size_t bytes
Definition: types.h:288

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.

◆ CCC_Entry

typedef union CCC_Entry_wrap CCC_Entry

An Occupied or Vacant position in a searchable container.

A entry is the basis for more complex container specific Entry Interface for all search-by-key containers. An entry is returned from various operations to provide both a reference to data and any context status that is important for the user. An entry can be Occupied or Vacant. See individual headers for containers that return this type for its meaning in context.

◆ CCC_Entry_status

typedef enum CCC_Entry_status CCC_Entry_status

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.

◆ CCC_Handle

typedef union CCC_Handle_wrap CCC_Handle

An Occupied or Vacant handle to a flat searchable container entry.

A handle uses the same semantics as an entry. However, the wrapped value is a CCC_Handle_index index. When this type is returned the container interface is promising that this element will remain at the returned handle index until the element is removed by the user. This is similar to pointer stability but offers a stronger guarantee that will hold even if the underlying container is resized.

◆ CCC_Handle_index

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.

◆ CCC_Handle_range

The result of a range query on iterable containers.

A range provides a view all elements that fit the equals range criteria of search-by-key containers. Use the provided range iteration functions in this header to iterate from beginning to end in forward order relative to the containers default ordering.

◆ CCC_Handle_range_reverse

The result of a range_reverse query on iterable containers.

A range_reverse provides a view all elements that fit the equals range_reverse criteria of search-by-key containers. Use the provided range iteration functions in this header to iterate from beginning to end in reverse order relative to the containers default ordering.

◆ CCC_Handle_status

typedef enum 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.

◆ CCC_Key_comparator

typedef CCC_Order CCC_Key_comparator(CCC_Key_comparator_context)

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.

◆ CCC_Key_hasher

typedef uint64_t CCC_Key_hasher(CCC_Key_context)

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.

◆ CCC_Range

typedef union CCC_Range_wrap CCC_Range

The result of a range query on iterable containers.

A range provides a view all elements that fit the equals range criteria of search-by-key containers. Use the provided range iteration functions in this header to iterate from beginning to end in forward order relative to the containers default ordering.

◆ CCC_Range_reverse

The result of a range_reverse query on iterable containers.

A range_reverse provides a view all elements that fit the equals range_reverse criteria of search-by-key containers. Use the provided range iteration functions in this header to iterate from beginning to end in reverse order relative to the containers default ordering.

◆ CCC_Type_comparator

typedef CCC_Order CCC_Type_comparator(CCC_Type_comparator_context)

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.

◆ CCC_Type_destructor

typedef void CCC_Type_destructor(CCC_Type_context)

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.

◆ CCC_Type_modifier

typedef void CCC_Type_modifier(CCC_Type_context)

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.

Enumeration Type Documentation

◆ CCC_Order

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.

Enumerator
CCC_ORDER_LESSER 

The left hand side is less than the right hand side.

CCC_ORDER_EQUAL 

The left hand side and right hand side are equal.

CCC_ORDER_GREATER 

The left hand side is greater than the right hand side.

CCC_ORDER_ERROR 

Comparison is not possible or other error has occurred.

◆ CCC_Result

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.

Enumerator
CCC_RESULT_OK 

The operation has occurred successfully.

CCC_RESULT_FAIL 

An operation ran but could not return the intended result.

CCC_RESULT_NO_ALLOCATION_FUNCTION 

Memory is needed but the container lacks allocation permission.

CCC_RESULT_ALLOCATOR_ERROR 

The container has allocation permission, but allocation failed.

CCC_RESULT_ARGUMENT_ERROR 

Bad arguments have been provided and operation returned early.

CCC_PRIVATE_RESULT_COUNT 

Internal helper, never returned to user. Always last result.

◆ CCC_Tribool

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 {}.

Enumerator
CCC_TRIBOOL_ERROR 

Intended value if CCC_FALSE or CCC_TRUE could not be returned.

CCC_FALSE 

Equivalent to boolean false, guaranteed to be falsey aka 0.

CCC_TRUE 

Equivalent to boolean true, guaranteed to be truthy aka 1.

Function Documentation

◆ CCC_array_range_begin()

CCC_Handle_index CCC_array_range_begin ( CCC_Handle_range const *  range)

Obtain a handle to the beginning user element stored in a container in the provided range.

Parameters
[in]rangea pointer to the range.
Returns
a handle to the user type stored in the container that serves as the beginning of the range.

Note the beginning of a range may be equivalent to the end or NULL.

◆ CCC_array_range_end()

CCC_Handle_index CCC_array_range_end ( CCC_Handle_range const *  range)

Obtain a handle to the end user element stored in a container in the provided range.

Parameters
[in]rangea pointer to the range.
Returns
a handle to the user type stored in the container that serves as the end of 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_array_range_reverse_begin()

CCC_Handle_index CCC_array_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.

Parameters
[in]rangea pointer to the range.
Returns
a handle to the user type stored in the container that serves as the reverse beginning of the range.

Note the reverse beginning of a range may be equivalent to the reverse end or 0.

◆ CCC_array_range_reverse_end()

CCC_Handle_index CCC_array_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.

Parameters
[in]rangea pointer to the range.
Returns
a handle to the user type stored in the container that serves as the reverse end of 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_entry_input_error()

CCC_Tribool CCC_entry_input_error ( CCC_Entry const *  entry)

Determine if an input error has occurred for a function that generates an entry.

Parameters
[in]entrythe pointer to the entry obtained from a container function.
Returns
true if an input error occurred usually meaning an invalid argument such as a NULL pointer was provided to a function. Error if entry is NULL.

◆ CCC_entry_insert_error()

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.

Parameters
[in]entrythe pointer to the entry obtained from a container insert.
Returns
true if an insertion error occurred usually meaning a insertion should have occurred but the container did not have permission to allocate new memory or allocation failed. Error if entry is NULL.

◆ CCC_entry_occupied()

CCC_Tribool CCC_entry_occupied ( CCC_Entry const *  entry)

Determine if an entry is Occupied in the container.

Parameters
[in]entrythe pointer to the entry obtained from a container.
Returns
true if Occupied false if Vacant. Error if entry is NULL.

◆ CCC_entry_status_message()

char const * CCC_entry_status_message ( CCC_Entry_status  status)

Obtain a string message with a description of the entry status.

Parameters
[in]statusthe status obtained from an entry.
Returns
a string message with more detailed information regarding the status.

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.

◆ CCC_entry_unwrap()

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.

Parameters
[in]entrythe pointer to the entry obtained from an operation.
Returns
a reference to the user type stored in the Occupied entry or NULL if the entry is Vacant or otherwise cannot be viewed.

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_get_entry_status()

CCC_Entry_status CCC_get_entry_status ( CCC_Entry const *  entry)

Obtain the entry status from a generic entry.

Parameters
[in]entrya pointer to the entry.
Returns
the status stored in the entry after the required action on the container completes. If entry is NULL an entry input error is returned so ensure e is non-NULL to avoid an inaccurate status returned.

◆ CCC_get_handle_status()

CCC_Handle_status CCC_get_handle_status ( CCC_Handle const *  handle)

Obtain the handle status from a generic handle.

Parameters
[in]handlea pointer to the handle.
Returns
the status stored in the handle after the required action on the container completes. If handle is NULL an handle input error is returned so ensure e is non-NULL to avoid an inaccurate status returned.

◆ CCC_handle_input_error()

CCC_Tribool CCC_handle_input_error ( CCC_Handle const *  handle)

Determine if an input error has occurred for a function that generates an handle.

Parameters
[in]handlethe pointer to the handle obtained from a container function.
Returns
true if an input error occurred usually meaning an invalid argument such as a NULL pointer was provided to a function. Error if handle is NULL.

◆ CCC_handle_insert_error()

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.

Parameters
[in]handlethe pointer to the handle obtained from a container insert.
Returns
true if an insertion error occurred usually meaning a insertion should have occurred but the container did not have permission to allocate new memory or allocation failed. Error if handle is NULL.

◆ CCC_handle_occupied()

CCC_Tribool CCC_handle_occupied ( CCC_Handle const *  handle)

Determine if an handle is Occupied in the container.

Parameters
[in]handlethe pointer to the handle obtained from a container.
Returns
true if Occupied false if Vacant. Error if handle is NULL.

◆ CCC_handle_status_message()

char const * CCC_handle_status_message ( CCC_Handle_status  status)

Obtain a string message with a description of the handle status.

Parameters
[in]statusthe status obtained from an handle.
Returns
a string message with more detailed information regarding the status.

Note that status for an handle is relevant when it is first obtained and when an action completes. Obtaining an 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_unwrap()

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.

Parameters
[in]handlethe pointer to the handle obtained from an operation.
Returns
a reference to the user type stored in the Occupied handle or NULL if the handle is Vacant or otherwise cannot be viewed.

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.

◆ CCC_range_begin()

void * CCC_range_begin ( CCC_Range const *  range)

Obtain a reference to the beginning user element stored in a container in the provided range.

Parameters
[in]rangea pointer to the range.
Returns
a reference to the user type stored in the container that serves as the beginning of the range.

Note the beginning of a range may be equivalent to the end or NULL.

◆ CCC_range_end()

void * CCC_range_end ( CCC_Range const *  range)

Obtain a reference to the end user element stored in a container in the provided range.

Parameters
[in]rangea pointer to the range.
Returns
a reference to the user type stored in the container that serves as the end of 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.

◆ CCC_range_reverse_begin()

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.

Parameters
[in]rangea pointer to the range.
Returns
a reference to the user type stored in the container that serves as the reverse beginning of the range.

Note the reverse beginning of a range may be equivalent to the reverse end or NULL.

◆ CCC_range_reverse_end()

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.

Parameters
[in]rangea pointer to the range.
Returns
a reference to the user type stored in the container that serves as the reverse end of 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.

◆ CCC_result_message()

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.

Parameters
[in]resultthe result obtained from a container operation.
Returns
a string message of the result. A CCC_RESULT_OK result is an empty string, the falsey NULL terminator. All other results have a string message.

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.