Variable-sized array. More...

Data Structures
struct	cstl_vector
	Vector object. More...

Macros
#define	CSTL_VECTOR_INITIALIZER(TYPE)
	Constant initialization of a vector object.

#define	DECLARE_CSTL_VECTOR(NAME, TYPE) struct cstl_vector NAME = CSTL_VECTOR_INITIALIZER(TYPE)
	(Statically) declare and initialize a vector

Typedefs
typedef struct cstl_vector	cstl_vector_t
	Vector object.

Functions
static void	cstl_vector_init_complex (struct cstl_vector const v, const size_t sz, cstl_xtor_func_t const cons, cstl_xtor_func_t const dest, void const priv)
	Initialize a vector object.

static void	cstl_vector_init (struct cstl_vector *const v, const size_t sz)
	Initialize a vector object.

static size_t	cstl_vector_size (const struct cstl_vector *const v)
	Get the number of elements in the vector.

static size_t	cstl_vector_capacity (const struct cstl_vector *const v)
	Get the number of elements the vector can hold.

static void *	cstl_vector_data (struct cstl_vector *const v)
	Get a pointer to the start of the vector data.

void *	cstl_vector_at (struct cstl_vector *v, size_t i)
	Get a pointer to an element in the vector.

const void *	cstl_vector_at_const (const struct cstl_vector *v, size_t i)
	Get a const pointer to an element from a const vector.

void	cstl_vector_reserve (struct cstl_vector *v, size_t sz)
	Request to increase the capacity of the vector.

void	cstl_vector_shrink_to_fit (struct cstl_vector *v)
	Request to decrease the capacity of the vector.

void	cstl_vector_resize (struct cstl_vector *v, size_t sz)
	Change the number of valid elements in the vector.

void	__cstl_vector_sort (struct cstl_vector v, cstl_compare_func_t cmp, void priv, cstl_swap_func_t swap, cstl_sort_algorithm_t algo)
	Sort the elements in the vector.

static void	cstl_vector_sort (struct cstl_vector const v, cstl_compare_func_t const cmp, void *const priv)
	Sort the elements in the vector.

ssize_t	cstl_vector_search (const struct cstl_vector v, const void e, cstl_compare_func_t cmp, void priv)
	Perform a binary search of the vector.

ssize_t	cstl_vector_find (const struct cstl_vector v, const void e, cstl_compare_func_t cmp, void priv)
	Perform a linear search of the vector.

void	__cstl_vector_reverse (struct cstl_vector v, cstl_swap_func_t swap)
	Reverse the current order of the elements.

static void	cstl_vector_reverse (struct cstl_vector *const v)
	Reverse the current order of the elements.

void	cstl_vector_swap (struct cstl_vector a, struct cstl_vector b)
	Swap the vector objects at the two given locations.

void	cstl_vector_clear (struct cstl_vector *v)
	Return a vector to its initialized state.

Detailed Description

Variable-sized array.

Macro Definition Documentation

◆ CSTL_VECTOR_INITIALIZER

#define CSTL_VECTOR_INITIALIZER ( TYPE )

Value:

    {                                           \
        .elem = {                               \
            .base = NULL,                       \
            .size = sizeof(TYPE),               \
            .xtor = {                           \
                .cons = NULL,                   \
                .dest = NULL,                   \
                .priv = NULL,                   \
            },                                  \
        },                                      \
        .count = 0,                             \
        .cap = 0,                               \
    }

Constant initialization of a vector object.

Parameters

TYPE	The type of object that the vector will hold

Definition at line 54 of file vector.h.

◆ DECLARE_CSTL_VECTOR

#define DECLARE_CSTL_VECTOR	(	NAME,
		TYPE
	)	struct cstl_vector NAME = CSTL_VECTOR_INITIALIZER(TYPE)

(Statically) declare and initialize a vector

Parameters

NAME	The name of the variable being declared
TYPE	The type of object that the vector will hold

Definition at line 74 of file vector.h.

Typedef Documentation

◆ cstl_vector_t

typedef struct cstl_vector cstl_vector_t

Vector object.

Callers declare or allocate an object of this type to instantiate a vector. Users are encouraged to declare (and initialize) this object with the DECLARE_CSTL_VECTOR() macro. Any other declaration or allocation must be initialized via cstl_vector_init().

Function Documentation

◆ __cstl_vector_reverse()

void __cstl_vector_reverse	(	struct cstl_vector *	v,
		cstl_swap_func_t *	swap
	)

Reverse the current order of the elements.

Parameters

[in]	v	A pointer to the vector
[in]	swap	A function to be used to swap elements within the vector.

Definition at line 150 of file vector.c.

◆ __cstl_vector_sort()

void __cstl_vector_sort	(	struct cstl_vector *	v,
		cstl_compare_func_t *	cmp,
		void *	priv,
		cstl_swap_func_t *	swap,
		cstl_sort_algorithm_t	algo
	)

Sort the elements in the vector.

Parameters

[in]	v	A pointer to the vector
[in]	cmp	A pointer to a function to use to compare elements
[in]	priv	A pointer to be passed to each invocation of the comparison function
[in]	swap	A function to be used to swap elements within the vector.
[in]	algo	The algorithm to use for the sort

Definition at line 116 of file vector.c.

◆ cstl_vector_at()

void * cstl_vector_at	(	struct cstl_vector *	v,
		size_t	i
	)

Get a pointer to an element in the vector.

Parameters

[in]	v	A pointer to the vector
[in]	i	The 0-based index of the desired element in the vector

Returns: A pointer to the element indicated by the index

Note: The code will cause an abort if the index is outside the range of valid elements it the vector

Definition at line 28 of file vector.c.

◆ cstl_vector_at_const()

const void * cstl_vector_at_const	(	const struct cstl_vector *	v,
		size_t	i
	)

Get a const pointer to an element from a const vector.

Parameters

[in]	v	A pointer to the vector
[in]	i	The 0-based index of the desired element in the vector

Returns: A pointer to the element indicated by the index

Note: The code will cause an abort if the index is outside the range of valid elements it the vector

Definition at line 18 of file vector.c.

◆ cstl_vector_capacity()

static size_t cstl_vector_capacity ( const struct cstl_vector *const v )

inlinestatic

Get the number of elements the vector can hold.

The capacity of the vector can be changed, but the current capacity indicates the number of elements that the vector can hold without a memory reallocation

Parameters

[in] v A pointer to the vector object

Returns: The number of elements the vector can hold

Definition at line 154 of file vector.h.

◆ cstl_vector_clear()

void cstl_vector_clear ( struct cstl_vector * v )

Return a vector to its initialized state.

Parameters

[in] v A pointer to a vector

Definition at line 107 of file vector.c.

◆ cstl_vector_data()

static void * cstl_vector_data ( struct cstl_vector *const v )

inlinestatic

Get a pointer to the start of the vector data.

Parameters

[in] v A pointer to the vector object

Returns: A pointer to the start of the vector data

Definition at line 166 of file vector.h.

◆ cstl_vector_find()

ssize_t cstl_vector_find	(	const struct cstl_vector *	v,
		const void *	e,
		cstl_compare_func_t *	cmp,
		void *	priv
	)

Perform a linear search of the vector.

Parameters

[in]	v	A pointer to a vector
[in]	e	A pointer to an object having the same value as the sought object according to the provided comparison function
[in]	cmp	A pointer to a function use to compare objects
[in]	priv	A pointer to be passed to each invocation of the comparison function

Returns: The index of the sought element

Return values

-1	if the sought value is not found

Definition at line 139 of file vector.c.

◆ cstl_vector_init()

static void cstl_vector_init	(	struct cstl_vector *const	v,
		const size_t	sz
	)

inlinestatic

Initialize a vector object.

Parameters

[in,out]	v	A pointer to the vector object
[in]	sz	The size of the type of object that will be stored in the vector

Definition at line 125 of file vector.h.

◆ cstl_vector_init_complex()

static void cstl_vector_init_complex	(	struct cstl_vector *const	v,
		const size_t	sz,
		cstl_xtor_func_t *const	cons,
		cstl_xtor_func_t *const	dest,
		void *const	priv
	)

inlinestatic

Initialize a vector object.

This function is used when construction and/or destruction of objects in the vector, as they go in and out of scope, is necessary. Any or all of the construction/destruction parameters may be NULL.

Construction and/or destruction takes place (only) during a resize of the vector and only affects elements coming into or going out of scope, where in-scope refers to elements at locations less than the "count" of the number of elements in the vector. In other words, elements that exist between the size of the vector and the capacity of the vector are considered uninitialized, either because they have not yet been "constructed" or because they were "destroyed".

Parameters

[in,out]	v	A pointer to the vector object
[in]	sz	The size of the type of object that will be stored in the vector
[in]	cons	A pointer to a function to call for each element as it comes into scope
[in]	dest	A pointer to a function to call for each element as it goes out of scope
[in]	priv	A pointer to be passed to each call to `cons` or `dest`

Definition at line 102 of file vector.h.

◆ cstl_vector_reserve()

void cstl_vector_reserve	(	struct cstl_vector *	v,
		size_t	sz
	)

Request to increase the capacity of the vector.

Parameters

[in]	v	A pointer to the vector object
[in]	sz	The number of elements the vector should be able to hold

Requests to decrease the capacity are ignored. Requests to increase the capacity that fail do so quietly

Definition at line 59 of file vector.c.

◆ cstl_vector_resize()

void cstl_vector_resize	(	struct cstl_vector *	v,
		size_t	sz
	)

Change the number of valid elements in the vector.

Parameters

[in]	v	A pointer to the vector
[in]	sz	The number of elements desired in the vector

The function attempts to set the number of valid elements to the number indicated. If the number is less than or equal to the current capacity of the vector, the function always succeeds. If the number exceeds the capacity, and the function cannot increase the capacity, the function will cause an abort.

Definition at line 73 of file vector.c.

◆ cstl_vector_reverse()

static void cstl_vector_reverse ( struct cstl_vector *const v )

inlinestatic

Reverse the current order of the elements.

Parameters

[in] v A pointer to the vector

Note: Elements within the vector will be rearranged via a "simple copy".

Definition at line 314 of file vector.h.

◆ cstl_vector_search()

ssize_t cstl_vector_search	(	const struct cstl_vector *	v,
		const void *	e,
		cstl_compare_func_t *	cmp,
		void *	priv
	)

Perform a binary search of the vector.

Parameters

[in]	v	A pointer to a vector
[in]	e	A pointer to an object having the same value as the sought object according to the provided comparison function
[in]	cmp	A pointer to a function use to compare objects
[in]	priv	A pointer to be passed to each invocation of the comparison function

The behavior is undefined if the vector is not sorted.

Returns: The index of the sought element

Return values

-1	if the sought value is not found

Definition at line 128 of file vector.c.

◆ cstl_vector_shrink_to_fit()

void cstl_vector_shrink_to_fit ( struct cstl_vector * v )

Request to decrease the capacity of the vector.

Parameters

[in] v A pointer to the vector object

The function attempts to decrease the capacity of the vector to only that required to hold the current number of valid elements. The function may fail and will do so without error.

Definition at line 66 of file vector.c.

◆ cstl_vector_size()

static size_t cstl_vector_size ( const struct cstl_vector *const v )

inlinestatic

Get the number of elements in the vector.

Parameters

[in] v A pointer to the vector object

Returns: The number of elements in the vector

Definition at line 138 of file vector.h.

◆ cstl_vector_sort()

static void cstl_vector_sort	(	struct cstl_vector *const	v,
		cstl_compare_func_t *const	cmp,
		void *const	priv
	)

inlinestatic

Sort the elements in the vector.

Parameters

[in]	v	A pointer to the vector
[in]	cmp	A pointer to a function to use to compare elements
[in]	priv	A pointer to be passed to each invocation of the comparison function

Note: Elements within the vector will be rearranged via a "simple copy".

Definition at line 256 of file vector.h.

◆ cstl_vector_swap()

void cstl_vector_swap	(	struct cstl_vector *	a,
		struct cstl_vector *	b
	)

Swap the vector objects at the two given locations.

Parameters

[in,out]	a	A pointer to a vector
[in,out]	b	A pointer to a(nother) vector

The vectors at the given locations will be swapped such that upon return, a will contain the vector previously pointed to by b and vice versa.

Definition at line 158 of file vector.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ CSTL_VECTOR_INITIALIZER

◆ DECLARE_CSTL_VECTOR

Typedef Documentation

◆ cstl_vector_t

Function Documentation

◆ __cstl_vector_reverse()

◆ __cstl_vector_sort()

◆ cstl_vector_at()

◆ cstl_vector_at_const()

◆ cstl_vector_capacity()

◆ cstl_vector_clear()

◆ cstl_vector_data()

◆ cstl_vector_find()

◆ cstl_vector_init()

◆ cstl_vector_init_complex()

◆ cstl_vector_reserve()

◆ cstl_vector_resize()

◆ cstl_vector_reverse()

◆ cstl_vector_search()

◆ cstl_vector_shrink_to_fit()

◆ cstl_vector_size()

◆ cstl_vector_sort()

◆ cstl_vector_swap()