Dynamically-allocated, fixed size array. More...

Data Structures
struct	cstl_array_t
	The array object. More...

Macros
#define	CSTL_ARRAY_INITIALIZER(NAME)
	Initialize an array object at the time of declaration.

#define	DECLARE_CSTL_ARRAY(NAME)
	Declare (and initialize) an array object at compile time.

Functions
static void	cstl_array_init (cstl_array_t *const a)
	Initialize a previously declared/allocated array object.

static size_t	cstl_array_size (const cstl_array_t *const a)
	Get the number of elements in the array.

void	cstl_array_alloc (cstl_array_t *a, size_t nm, size_t sz)
	Allocate an array to be managed.

static void	cstl_array_reset (cstl_array_t *const a)
	Drop a reference to memory managed by this object.

const void *	cstl_array_data_const (const cstl_array_t *a)
	Return a pointer to the underlying array.

static void *	cstl_array_data (cstl_array_t *const a)
	Return a pointer to the underlying array.

const void *	cstl_array_at_const (const cstl_array_t *a, size_t i)
	Return a pointer to an element in the array.

static void *	cstl_array_at (cstl_array_t *const a, const size_t i)
	Return a pointer to an element in the array.

void	cstl_array_slice (cstl_array_t a, size_t beg, size_t end, cstl_array_t s)
	Create an array object referring to a slice of another.

void	cstl_array_unslice (cstl_array_t s, cstl_array_t a)
	Create an array object referring to the entire underlying array.

Danger Zone
Functions requiring extra careful handling Callers can use cstl_array_set() to use an externally allocated array, but the caller must cstl_array_release() that array. Otherwise, the code will try to return the array to the heap when the last reference to it goes away.
void	cstl_array_set (cstl_array_t const a, void buf, size_t nm, size_t sz)
	Manage an externally allocated array.

void	cstl_array_release (cstl_array_t const a, void *buf)
	Release an externally allocated array.

Raw Array Functions
void	cstl_raw_array_reverse (void arr, size_t count, size_t size, cstl_swap_func_t swap, void *tmp)
	Reverse the contents of an array.

ssize_t	cstl_raw_array_search (const void arr, size_t count, size_t size, const void ex, cstl_compare_func_t cmp, void priv)
	Perform a binary search of the array.

ssize_t	cstl_raw_array_find (const void arr, size_t count, size_t size, const void ex, cstl_compare_func_t cmp, void priv)
	Perform a linear search of the array.

void	cstl_raw_array_sort (void arr, size_t count, size_t size, cstl_compare_func_t cmp, void priv, cstl_swap_func_t swap, void *tmp, cstl_sort_algorithm_t algo)
	Sort the array using the specified algorithm.

Detailed Description

Dynamically-allocated, fixed size array.

Macro Definition Documentation

◆ CSTL_ARRAY_INITIALIZER

#define CSTL_ARRAY_INITIALIZER ( NAME )

Value:

    {                                                   \
        .ptr = CSTL_SHARED_PTR_INITIALIZER(NAME.ptr),   \
        .off = 0,                                       \
        .len = 0,                                       \
    }

Initialize an array object at the time of declaration.

Parameters

[in] NAME The name of the array object being initialized

Definition at line 43 of file array.h.

◆ DECLARE_CSTL_ARRAY

#define DECLARE_CSTL_ARRAY ( NAME )

Value:

cstl_array_t NAME = \

CSTL_ARRAY_INITIALIZER(NAME)

cstl_array_t

The array object.

Definition array.h:31

Declare (and initialize) an array object at compile time.

Parameters

[in] NAME The name of the array object being declared

Definition at line 54 of file array.h.

Function Documentation

◆ cstl_array_alloc()

void cstl_array_alloc	(	cstl_array_t *	a,
		size_t	nm,
		size_t	sz
	)

Allocate an array to be managed.

Parameters

[in,out]	a	A pointer to an initialized array object
[in]	nm	The number of elements in the underlying array
[in]	sz	The size of each element in the underlying array

A failed allocation will leave the array object in an initialized state

Definition at line 376 of file array.c.

◆ cstl_array_at()

static void * cstl_array_at	(	cstl_array_t *const	a,
		const size_t	i
	)

inlinestatic

Return a pointer to an element in the array.

Parameters

[in]	a	A pointer to an array object
[in]	i	The index of the sought element in the array

The function will abort() if the index is out of bounds.

Returns: A pointer to the sought element

Definition at line 176 of file array.h.

◆ cstl_array_at_const()

const void * cstl_array_at_const	(	const cstl_array_t *	a,
		size_t	i
	)

Return a pointer to an element in the array.

Parameters

[in]	a	A pointer to an array object
[in]	i	The index of the sought element in the array

The function will abort() if the index is out of bounds.

Returns: A pointer to the sought element

Definition at line 437 of file array.c.

◆ cstl_array_data()

static void * cstl_array_data ( cstl_array_t *const a )

inlinestatic

Return a pointer to the underlying array.

Parameters

[in] a A pointer to the array object

Returns: A pointer to the underlying array

Return values

NULL	The object does not manage an array

Definition at line 159 of file array.h.

◆ cstl_array_data_const()

const void * cstl_array_data_const ( const cstl_array_t * a )

Return a pointer to the underlying array.

Parameters

[in] a A pointer to the array object

Returns: A pointer to the underlying array

Return values

NULL	The object does not manage an array

Definition at line 427 of file array.c.

◆ cstl_array_init()

static void cstl_array_init ( cstl_array_t *const a )

inlinestatic

Initialize a previously declared/allocated array object.

Parameters

[in] a A pointer to an uninitialized array object

Definition at line 63 of file array.h.

◆ cstl_array_release()

void cstl_array_release	(	cstl_array_t *const	a,
		void **	buf
	)

Release an externally allocated array.

If the underlying array was not externally allocated, this function has no effect. Furthermore, there must be no other references to the underlying array from other cstl_array_t objects for this function to succeed. The underlying array will not be released while other references still exist.

Parameters

[in]	a	A pointer to an array object
[out]	buf	A pointer into which to return the externally allocated array. The array is returned on success or set to NULL on failure. This parameter may be NULL

Definition at line 409 of file array.c.

◆ cstl_array_reset()

static void cstl_array_reset ( cstl_array_t *const a )

inlinestatic

Drop a reference to memory managed by this object.

If this object is the last reference to the underlying memory, that memory will be freed.

Parameters

[in,out] a A pointer to an array object

Definition at line 143 of file array.h.

◆ cstl_array_set()

void cstl_array_set	(	cstl_array_t *const	a,
		void *	buf,
		size_t	nm,
		size_t	sz
	)

Manage an externally allocated array.

Parameters

[in,out]	a	A pointer to an initialized array object
[in]	buf	A pointer to an array containing `nm` elements, each of `sz` bytes
[in]	nm	The number of elements in the underlying array
[in]	sz	The size of each element in the underlying array

Definition at line 395 of file array.c.

◆ cstl_array_size()

static size_t cstl_array_size ( const cstl_array_t *const a )

inlinestatic

Get the number of elements in the array.

Parameters

[in] a A pointer to an array object

Returns: The number of elements in the array

Definition at line 76 of file array.h.

◆ cstl_array_slice()

void cstl_array_slice	(	cstl_array_t *	a,
		size_t	beg,
		size_t	end,
		cstl_array_t *	s
	)

Create an array object referring to a slice of another.

Parameters

[in]	a	A pointer to an array object
[in]	beg	The index in `a` at which the slice should begin
[in]	end	The index in `a` at which the slice should end
[in,out]	s	A pointer to an array object. `s` and `a` may point to the same object

If end < beg or if the slice would exceed the bounds of the array, the function abort()s. Otherwise the slice refers to the elements indicated by [beg, end).

Definition at line 449 of file array.c.

◆ cstl_array_unslice()

void cstl_array_unslice	(	cstl_array_t *	s,
		cstl_array_t *	a
	)

Create an array object referring to the entire underlying array.

Parameters

[in]	a	A pointer to an array object
[in,out]	s	A pointer to an array object. `s` and `a` may point to the same object

The resulting array object will refer to the entirety of the underlying array, as originally allocated.

Definition at line 469 of file array.c.

◆ cstl_raw_array_find()

ssize_t cstl_raw_array_find	(	const void *	arr,
		size_t	count,
		size_t	size,
		const void *	ex,
		cstl_compare_func_t *	cmp,
		void *	priv
	)

Perform a linear search of the array.

Parameters

[in,out]	arr	A pointer to the first element in an array
[in]	count	The number of elements in the array
[in]	size	The size of each element in the array
[in]	ex	A pointer to the element to be found
[in]	cmp	A pointer to a function to compare elements
[in]	priv	A pointer to be passed to the comparison function

Returns: The index of the sought element

Return values

-1	if the sought value is not found

Definition at line 54 of file array.c.

◆ cstl_raw_array_reverse()

void cstl_raw_array_reverse	(	void *	arr,
		size_t	count,
		size_t	size,
		cstl_swap_func_t *	swap,
		void *	tmp
	)

Reverse the contents of an array.

Parameters

[in,out]	arr	A pointer to the first element in an array
[in]	count	The number of elements in the array
[in]	size	The size of each element in the array
[in]	swap	A pointer to a function to swap elements in the array
	tmp	A pointer to scratch space to be used by the swap function

Definition at line 15 of file array.c.

◆ cstl_raw_array_search()

ssize_t cstl_raw_array_search	(	const void *	arr,
		size_t	count,
		size_t	size,
		const void *	ex,
		cstl_compare_func_t *	cmp,
		void *	priv
	)

Perform a binary search of the array.

Parameters

[in,out]	arr	A pointer to the first element in an array
[in]	count	The number of elements in the array
[in]	size	The size of each element in the array
[in]	ex	A pointer to the element to be found
[in]	cmp	A pointer to a function to compare elements
[in]	priv	A pointer to be passed to the comparison function

The array must be sorted, or the behavior is undefined

Returns: The index of the sought element

Return values

-1	if the sought value is not found

Definition at line 30 of file array.c.

◆ cstl_raw_array_sort()

void cstl_raw_array_sort	(	void *	arr,
		size_t	count,
		size_t	size,
		cstl_compare_func_t *	cmp,
		void *	priv,
		cstl_swap_func_t *	swap,
		void *	tmp,
		cstl_sort_algorithm_t	algo
	)

Sort the array using the specified algorithm.

Parameters

[in,out]	arr	A pointer to the first element in an array
[in]	count	The number of elements in the array
[in]	size	The size of each element in the array
[in]	cmp	A pointer to a function to compare elements
[in]	priv	A pointer to be passed to the comparison function
[in]	swap	A pointer to a function to swap elements in the array
	tmp	A pointer to scratch space to be used by the swap function
[in]	algo	The algorithm to use to sort the array

Definition at line 340 of file array.c.

Data Structures

Macros

Functions

Danger Zone

Raw Array Functions

Detailed Description

Macro Definition Documentation

◆ CSTL_ARRAY_INITIALIZER

◆ DECLARE_CSTL_ARRAY

Function Documentation

◆ cstl_array_alloc()

◆ cstl_array_at()

◆ cstl_array_at_const()

◆ cstl_array_data()

◆ cstl_array_data_const()

◆ cstl_array_init()

◆ cstl_array_release()

◆ cstl_array_reset()

◆ cstl_array_set()

◆ cstl_array_size()

◆ cstl_array_slice()

◆ cstl_array_unslice()

◆ cstl_raw_array_find()

◆ cstl_raw_array_reverse()

◆ cstl_raw_array_search()

◆ cstl_raw_array_sort()