types.h File Reference

The C Container Collection Fundamental Types. More...

#include "impl/impl_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.

Data Structures
struct	ccc_cmp
	An element comparison helper. More...
struct	ccc_key_cmp
	A key comparison helper to avoid argument swapping. More...
struct	ccc_user_type
	A reference to a user type within the container. More...
struct	ccc_user_key
	A read only reference to a key type matching the key field type used for hash containers. More...

Container Types
Types used across many containers.
enum	ccc_result {   CCC_OK = 0 , CCC_NO_ALLOC , CCC_MEM_ERR , CCC_INPUT_ERR ,   CCC_RESULTS_SIZE }
	A result of actions on containers. More...
enum	ccc_threeway_cmp { CCC_LES = -1 , CCC_EQL , CCC_GRT , CCC_CMP_ERR }
	A three-way comparison for comparison functions. More...
typedef union ccc_range_	ccc_range
	The result of a range query on iterable containers.
typedef union ccc_rrange_	ccc_rrange
	The result of a rrange query on iterable containers.
typedef union ccc_entry_	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 void *	ccc_alloc_fn(void *ptr, size_t size, void *aux)
	An allocation function at the core of all containers.
typedef ccc_threeway_cmp	ccc_cmp_fn(ccc_cmp)
	A callback function for comparing two elements in a container.
typedef void	ccc_update_fn(ccc_user_type)
	A callback function for modifying an element in the container.
typedef void	ccc_destructor_fn(ccc_user_type)
	A callback function for destroying an element in the container.
typedef bool	ccc_key_eq_fn(ccc_key_cmp)
	A callback function to determining equality between two stored keys.
typedef ccc_threeway_cmp	ccc_key_cmp_fn(ccc_key_cmp)
	A callback function for three-way comparing two stored keys.
typedef uint64_t	ccc_hash_fn(ccc_user_key to_hash)
	A callback function to hash the key type used in a container.

Entry Interface
The generic interface for associative container entries.
bool	ccc_entry_occupied (ccc_entry const *e)
	Determine if an entry is Occupied in the container.
bool	ccc_entry_insert_error (ccc_entry const *e)
	Determine if an insertion error has occurred when a function that attempts to insert a value in a container is used.
bool	ccc_entry_input_error (ccc_entry const *e)
	Determine if an input error has occurred for a function that generates an entry.
void *	ccc_entry_unwrap (ccc_entry const *e)
	Unwraps the provided entry providing a reference to the user type obtained from the operation that provides the entry.

Range Interface
The generic range interface for associative containers.
void *	ccc_begin_range (ccc_range const *r)
	Obtain a reference to the beginning user element stored in a container in the provided range.
void *	ccc_end_range (ccc_range const *r)
	Obtain a reference to the end user element stored in a container in the provided range.
void *	ccc_rbegin_rrange (ccc_rrange const *r)
	Obtain a reference to the reverse beginning user element stored in a container in the provided range.
void *	ccc_rend_rrange (ccc_rrange const *r)
	Obtain a reference 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_msg (ccc_result res)
	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 *e)
	Obtain the entry status from a generic entry.
char const *	ccc_entry_status_msg (ccc_entry_status status)
	Obtain a string message with a description of the entry status.

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 allocation function interface.

Typedef Documentation

ccc_alloc_fn

typedef void * ccc_alloc_fn(void *ptr, size_t size, void *aux)

An allocation function at the core of all containers.

An allocation function implements the following behavior, where ptr is pointer to memory, size is number of bytes to allocate, and aux is a reference to any supplementary information required for allocation, deallocation, or reallocation. Aux is passed to a container upon its initialization and the programmer may choose how to best utilize this reference (more on aux later).

• If NULL is provided with a size of 0, NULL is returned.
• If NULL is provided with a non-zero size, new memory is allocated/returned.
• If ptr is non-NULL it has been previously allocated by the alloc function.
• If ptr is non-NULL with non-zero size, ptr is resized to at least size size. The pointer returned is NULL if resizing fails. Upon success, the pointer returned might not be equal to the pointer provided.
• If ptr is non-NULL and size is 0, ptr 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 aux parameter also discourages users from providing realloc. For example, one solution using the standard library allocator might be implemented as follows (aux is not needed):

void *
std_alloc(void *const ptr, size_t const size, void *)
{
    if (!ptr && !size)
    {
        return NULL;
    }
    if (!ptr)
    {
        return malloc(size);
    }
    if (!size)
    {
        free(ptr);
        return NULL;
    }
    return realloc(ptr, size);
}

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 aux parameter, see the sample programs. Using custom arena allocators or container compositions are cases when aux is needed.

ccc_cmp_fn

typedef ccc_threeway_cmp ccc_cmp_fn(ccc_cmp)

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. Aux may be NULL if no aux is provided on initialization.

ccc_destructor_fn

typedef void ccc_destructor_fn(ccc_user_type)

A callback function for destroying an element in the container.

A reference to the container type and any aux data provided on initialization is available. The container pointer points to the base of the user type and is not NULL. Aux may be NULL if no aux 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_entry

typedef union ccc_entry_ 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 auxiliary 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_msg() function for detailed string messages regarding the entry status. This may be helpful for debugging or logging.

ccc_hash_fn

typedef uint64_t ccc_hash_fn(ccc_user_key to_hash)

A callback function to hash the key type used in a container.

A reference to any aux data provided on initialization is also available. Return the complete hash value as determined by the user hashing algorithm.

ccc_key_cmp_fn

typedef ccc_threeway_cmp ccc_key_cmp_fn(ccc_key_cmp)

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_LES if the key is less than the key in key field of user type, CCC_EQL if equal, and CCC_GRT if greater.

ccc_key_eq_fn

typedef bool ccc_key_eq_fn(ccc_key_cmp)

A callback function to determining equality between two stored keys.

The function should return true if the key and key field in the user type are equivalent, else false.

ccc_range

typedef union ccc_range_ 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_rrange

typedef union ccc_rrange_ ccc_rrange

The result of a rrange query on iterable containers.

A rrange provides a view all elements that fit the equals rrange 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_update_fn

typedef void ccc_update_fn(ccc_user_type)

A callback function for modifying an element in the container.

A reference to the container type and any aux data provided on initialization is available. The container pointer points to the base of the user type and is not NULL. Aux may be NULL if no aux 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_result

enum ccc_result

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_OK	The operation has occurred without error.
CCC_NO_ALLOC	Memory is needed but the container lacks allocation permission.
CCC_MEM_ERR	The container has allocation permission, but allocation failed.
CCC_INPUT_ERR	Bad arguments have been provided to an operation.
CCC_RESULTS_SIZE	Internal helper, never returned to user. Always last result.

ccc_threeway_cmp

enum ccc_threeway_cmp

A three-way comparison for comparison functions.

A C style three way comparison value (e.g. ((a > b) - (a < b))). CCC_LES if left hand side is less than right hand side, CCC_EQL if they are equal, and CCC_GRT if left hand side is greater than right hand side.

Enumerator
CCC_LES	The left hand side is less than the right hand side.
CCC_EQL	The left hand side and right hand side are equal.
CCC_GRT	The left hand side is greater than the right hand side.
CCC_CMP_ERR	Comparison is not possible or other error has occurred.

Function Documentation

ccc_begin_range()

void * ccc_begin_range

(

ccc_range const *

r

)

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

Parameters

[in]

r

a 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_end_range()

void * ccc_end_range

(

ccc_range const *

r

)

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

Parameters

[in]

r

a 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_entry_input_error()

bool ccc_entry_input_error

(

ccc_entry const *

e

)

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

Parameters

[in]

e

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

ccc_entry_insert_error()

bool ccc_entry_insert_error

(

ccc_entry const *

e

)

Determine if an insertion error has occurred when a function that attempts to insert a value in a container is used.

Parameters

[in]

e

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

ccc_entry_occupied()

bool ccc_entry_occupied

(

ccc_entry const *

e

)

Determine if an entry is Occupied in the container.

Parameters

[in]

e

the pointer to the entry obtained from a container.

Returns

true if Occupied false if Vacant.

ccc_entry_status_msg()

char const * ccc_entry_status_msg

(

ccc_entry_status

status

)

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

Parameters

[in]

status

the 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 *

e

)

Unwraps the provided entry providing a reference to the user type obtained from the operation that provides the entry.

Parameters

[in]

e

the 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 *

e

)

Obtain the entry status from a generic entry.

Parameters

[in]

e

a pointer to the entry.

Returns

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

ccc_rbegin_rrange()

void * ccc_rbegin_rrange

(

ccc_rrange const *

r

)

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

Parameters

[in]

r

a 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_rend_rrange()

void * ccc_rend_rrange

(

ccc_rrange const *

r

)

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

Parameters

[in]

r

a 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_msg()

char const * ccc_result_msg

(

ccc_result

res

)

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]

res

the result obtained from a container operation.

Returns

a string message of the result. A CCC_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.