universe@390: universe@390:

Dynamically allocated array implementation. universe@390: More...

universe@390:

#include "ucx.h"
universe@390: #include "allocator.h"
universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Data Structures
struct	UcxArray
	UCX array type. More...

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Macros
#define	ucx_array_util_set(array, capacity, elmsize, idx, data)
	Sets an element in an arbitrary user defined array. More...

#define	ucx_array_util_setptr(array, capacity, idx, ptr)
	Stores a pointer in an arbitrary user defined array. More...

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Functions
int	ucx_array_util_set_a (UcxAllocator alloc, void array, size_t capacity, size_t elmsize, size_t idx, void *data)
	Sets an element in an arbitrary user defined array. More...

int	ucx_array_util_setptr_a (UcxAllocator alloc, void array, size_t capacity, size_t idx, void *ptr)
	Stores a pointer in an arbitrary user defined array. More...

UcxArray *	ucx_array_new (size_t capacity, size_t elemsize)
	Creates a new UCX array with the given capacity and element size. More...

UcxArray *	ucx_array_new_a (size_t capacity, size_t elemsize, UcxAllocator *allocator)
	Creates a new UCX array using the specified allocator. More...

void	ucx_array_init (UcxArray *array, size_t capacity, size_t elemsize)
	Initializes a UCX array structure with the given capacity and element size. More...

void	ucx_array_init_a (UcxArray array, size_t capacity, size_t elemsize, UcxAllocator allocator)
	Initializes a UCX array structure using the specified allocator. More...

int	ucx_array_clone (UcxArray dest, UcxArray const src)
	Creates an shallow copy of an array. More...

int	ucx_array_equals (UcxArray const array1, UcxArray const array2, cmp_func cmpfnc, void *data)
	Compares two UCX arrays element-wise by using a compare function. More...

void	ucx_array_destroy (UcxArray *array)
	Destroys the array. More...

void	ucx_array_free (UcxArray *array)
	Destroys and frees the array. More...

int	ucx_array_append_from (UcxArray array, void data, size_t count)
	Inserts elements at the end of the array. More...

int	ucx_array_prepend_from (UcxArray array, void data, size_t count)
	Inserts elements at the beginning of the array. More...

int	ucx_array_set_from (UcxArray array, size_t index, void data, size_t count)
	Sets elements starting at the specified index. More...

int	ucx_array_concat (UcxArray array1, const UcxArray array2)
	Concatenates two arrays. More...

void *	ucx_array_at (UcxArray const *array, size_t index)
	Returns a pointer to the array element at the specified index. More...

size_t	ucx_array_find (UcxArray const array, void elem, cmp_func cmpfnc, void *data)
	Returns the index of an element containing the specified data. More...

int	ucx_array_contains (UcxArray const array, void elem, cmp_func cmpfnc, void *data)
	Checks, if an array contains a specific element. More...

void	ucx_array_sort (UcxArray array, cmp_func cmpfnc, void data)
	Sorts a UcxArray with the best available sort algorithm. More...

void	ucx_array_remove (UcxArray *array, size_t index)
	Removes an element from the array. More...

void	ucx_array_remove_fast (UcxArray *array, size_t index)
	Removes an element from the array. More...

int	ucx_array_shrink (UcxArray *array)
	Shrinks the memory to exactly fit the contents. More...

int	ucx_array_resize (UcxArray *array, size_t capacity)
	Sets the capacity of the array. More...

int	ucx_array_reserve (UcxArray *array, size_t capacity)
	Resizes the array only, if the capacity is insufficient. More...

int	ucx_array_grow (UcxArray *array, size_t count)
	Resizes the capacity, if the specified number of elements would not fit. More...

universe@390:

Detailed Description

universe@390:

Dynamically allocated array implementation.

universe@390:

Author: Mike Becker; universe@390: Olaf Wintermann

universe@390:

Macro Definition Documentation

universe@390: universe@390:

◆ ucx_array_util_set

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_array_util_set	(	array,
		capacity,
		elmsize,
		idx,
		data
	)

universe@390:

universe@390: Value:

ucx_array_util_set_a(ucx_default_allocator(), (void**)(array), capacity, \

elmsize, idx, data)

ucx_array_util_set_a

int ucx_array_util_set_a(UcxAllocator *alloc, void **array, size_t *capacity, size_t elmsize, size_t idx, void *data)

Sets an element in an arbitrary user defined array.

Definition: array.c:72

universe@390:

ucx_default_allocator

UcxAllocator * ucx_default_allocator()

Returns a pointer to the default allocator.

Definition: allocator.c:41

universe@390:

Sets an element in an arbitrary user defined array.

universe@390:

The data is copied from the specified data location.

universe@390:

If the capacity is insufficient, the array is automatically reallocated and the possibly new pointer is stored in the array argument.

universe@390:

On reallocation the capacity of the array is doubled until it is sufficient. The new capacity is stored back to capacity.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

array	a pointer to location of the array pointer
capacity	a pointer to the capacity
elmsize	the size of each element
idx	the index of the element to set
data	a pointer to the element data

universe@390:

Returns: zero on success or non-zero on error (errno will be set)

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_util_setptr

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_array_util_setptr	(	array,
		capacity,
		idx,
		ptr
	)

universe@390:

universe@390: Value:

ucx_array_util_setptr_a(ucx_default_allocator(), (void**)(array), \

capacity, idx, ptr)

ucx_default_allocator

UcxAllocator * ucx_default_allocator()

Returns a pointer to the default allocator.

Definition: allocator.c:41

universe@390:

ucx_array_util_setptr_a

int ucx_array_util_setptr_a(UcxAllocator *alloc, void **array, size_t *capacity, size_t idx, void *ptr)

Stores a pointer in an arbitrary user defined array.

Definition: array.c:112

universe@390:

Stores a pointer in an arbitrary user defined array.

universe@390:

The element size of the array must be sizeof(void*).

universe@390:

If the capacity is insufficient, the array is automatically reallocated and the possibly new pointer is stored in the array argument.

universe@390:

On reallocation the capacity of the array is doubled until it is sufficient. The new capacity is stored back to capacity.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

array	a pointer to location of the array pointer
capacity	a pointer to the capacity
idx	the index of the element to set
ptr	the pointer to store

universe@390:

Returns: zero on success or non-zero on error (errno will be set)

universe@390: universe@390:

universe@390:

Function Documentation

universe@390: universe@390:

◆ ucx_array_append_from()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_append_from	(	UcxArray *	array,
		void *	data,
		size_t	count
	)

universe@390:

universe@390: universe@390:

Inserts elements at the end of the array.

universe@390:

This is an O(1) operation. The array will automatically grow, if the capacity is exceeded. If a pointer to data is provided, the data is copied into the array with memcpy(). Otherwise the new elements are completely zeroed.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

array	a pointer the array where to append the data
data	a pointer to the data to insert (may be `NULL`)
count	number of elements to copy from data (if data is `NULL`, zeroed elements are appended)

universe@390:

Returns: zero on success, non-zero if a reallocation was necessary but failed

universe@390:

See also: ucx_array_set_from(); universe@390: ucx_array_append()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_at()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void* ucx_array_at	(	UcxArray const *	array,
		size_t	index
	)

universe@390:

universe@390: universe@390:

Returns a pointer to the array element at the specified index.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

array	the array to retrieve the element from
index	index of the element to return

universe@390:

Returns: a pointer to the element at the specified index or NULL, if the index is greater than the array size

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_clone()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_clone	(	UcxArray *	dest,
		UcxArray const *	src
	)

universe@390:

universe@390: universe@390:

Creates an shallow copy of an array.

universe@390:

This function clones the specified array by using memcpy(). If the destination capacity is insufficient, an automatic reallocation is attempted.

universe@390:

Note: if the destination array is uninitialized, the behavior is undefined.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

dest	the array to copy to
src	the array to copy from

universe@390:

Returns: zero on success, non-zero on reallocation failure.

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_concat()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_concat	(	UcxArray *	array1,
		const UcxArray *	array2
	)

universe@390:

universe@390: universe@390:

Concatenates two arrays.

universe@390:

The contents of the second array are appended to the first array in one single operation. The second array is otherwise left untouched.

universe@390:

The first array may grow automatically. If this fails, both arrays remain unmodified.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

array1	first array
array2	second array

universe@390:

Returns: zero on success, non-zero if reallocation was necessary but failed or the element size does not match

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_contains()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_contains	(	UcxArray const *	array,
		void *	elem,
		cmp_func	cmpfnc,
		void *	data
	)

universe@390:

universe@390: universe@390:

Checks, if an array contains a specific element.

universe@390:

An element is found, if ucx_array_find() returns a value less than the size.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

array	the array where to search for the data
elem	the element data
cmpfnc	the compare function
data	additional data for the compare function

universe@390:

Returns: 1, if and only if the array contains the specified element data

universe@390:

See also: ucx_array_find()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_destroy()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_array_destroy ( UcxArray * array )

universe@390:

universe@390: universe@390:

Destroys the array.

universe@390:

The data is freed and both capacity and count are reset to zero. If the array structure itself has been dynamically allocated, it has to be freed separately.

universe@390:

Parameters

universe@390: universe@390: universe@390:

array the array to destroy

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_equals()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_equals	(	UcxArray const *	array1,
		UcxArray const *	array2,
		cmp_func	cmpfnc,
		void *	data
	)

universe@390:

universe@390: universe@390:

Compares two UCX arrays element-wise by using a compare function.

universe@390:

Elements of the two specified arrays are compared by using the specified compare function and the additional data. The type and content of this additional data depends on the cmp_func() used.

universe@390:

This function always returns zero, if the element sizes of the arrays do not match and performs no comparisons in this case.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

array1	the first array
array2	the second array
cmpfnc	the compare function
data	additional data for the compare function

universe@390:

Returns: 1, if and only if the two arrays equal element-wise, 0 otherwise

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_find()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

size_t ucx_array_find	(	UcxArray const *	array,
		void *	elem,
		cmp_func	cmpfnc,
		void *	data
	)

universe@390:

universe@390: universe@390:

Returns the index of an element containing the specified data.

universe@390:

This function uses a cmp_func() to compare the data of each list element with the specified data. If no cmp_func is provided, memcmp() is used.

universe@390:

If the array contains the data more than once, the index of the first occurrence is returned. If the array does not contain the data, the size of array is returned.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

array	the array where to search for the data
elem	the element data
cmpfnc	the compare function
data	additional data for the compare function

universe@390:

Returns: the index of the element containing the specified data or the size of the array, if the data is not found in this array

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_free()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_array_free ( UcxArray * array )

universe@390:

universe@390: universe@390:

Destroys and frees the array.

universe@390:

Parameters

universe@390: universe@390: universe@390:

array the array to free

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_grow()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_grow	(	UcxArray *	array,
		size_t	count
	)

universe@390:

universe@390: universe@390:

Resizes the capacity, if the specified number of elements would not fit.

universe@390:

A call to ucx_array_grow(array, count) is effectively the same as ucx_array_reserve(array, array->size+count).

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

array	a pointer to the array
count	the number of elements that should additionally fit into the array

universe@390:

Returns: zero on success, non-zero if reallocation failed

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_init()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_array_init	(	UcxArray *	array,
		size_t	capacity,
		size_t	elemsize
	)

universe@390:

universe@390: universe@390:

Initializes a UCX array structure with the given capacity and element size.

universe@390:

The structure must be uninitialized as the data pointer will be overwritten.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

array	the structure to initialize
capacity	the initial capacity
elemsize	the element size

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_init_a()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_array_init_a	(	UcxArray *	array,
		size_t	capacity,
		size_t	elemsize,
		UcxAllocator *	allocator
	)

universe@390:

universe@390: universe@390:

Initializes a UCX array structure using the specified allocator.

universe@390:

The structure must be uninitialized as the data pointer will be overwritten.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

array	the structure to initialize
capacity	the initial capacity
elemsize	the element size
allocator	the allocator to use

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_new()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

UcxArray* ucx_array_new	(	size_t	capacity,
		size_t	elemsize
	)

universe@390:

universe@390: universe@390:

Creates a new UCX array with the given capacity and element size.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

capacity	the initial capacity
elemsize	the element size

universe@390:

Returns: a pointer to a new UCX array structure

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_new_a()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

UcxArray* ucx_array_new_a	(	size_t	capacity,
		size_t	elemsize,
		UcxAllocator *	allocator
	)

universe@390:

universe@390: universe@390:

Creates a new UCX array using the specified allocator.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

capacity	the initial capacity
elemsize	the element size
allocator	the allocator to use

universe@390:

Returns: a pointer to new UCX array structure

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_prepend_from()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_prepend_from	(	UcxArray *	array,
		void *	data,
		size_t	count
	)

universe@390:

universe@390: universe@390:

Inserts elements at the beginning of the array.

universe@390:

This is an expensive operation, because the contents must be moved. If there is no particular reason to prepend data, you should use ucx_array_append_from() instead.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

array	a pointer the array where to prepend the data
data	a pointer to the data to insert (may be `NULL`)
count	number of elements to copy from data (if data is `NULL`, zeroed elements are inserted)

universe@390:

Returns: zero on success, non-zero if a reallocation was necessary but failed

universe@390:

See also: ucx_array_append_from(); universe@390: ucx_array_set_from(); universe@390: ucx_array_prepend()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_remove()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_array_remove	(	UcxArray *	array,
		size_t	index
	)

universe@390:

universe@390: universe@390:

Removes an element from the array.

universe@390:

This is in general an expensive operation, because several elements may be moved. If the order of the elements is not relevant, use ucx_array_remove_fast() instead.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

array	pointer to the array from which the element shall be removed
index	the index of the element to remove

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_remove_fast()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_array_remove_fast	(	UcxArray *	array,
		size_t	index
	)

universe@390:

universe@390: universe@390:

Removes an element from the array.

universe@390:

This is an O(1) operation, but does not maintain the order of the elements. The last element in the array is moved to the location of the removed element.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

array	pointer to the array from which the element shall be removed
index	the index of the element to remove

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_reserve()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_reserve	(	UcxArray *	array,
		size_t	capacity
	)

universe@390:

universe@390: universe@390:

Resizes the array only, if the capacity is insufficient.

universe@390:

If the requested capacity is smaller than the current capacity, this function does nothing.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

array	a pointer to the array
capacity	the guaranteed capacity

universe@390:

Returns: zero on success, non-zero if reallocation failed

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_resize()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_resize	(	UcxArray *	array,
		size_t	capacity
	)

universe@390:

universe@390: universe@390:

Sets the capacity of the array.

universe@390:

If the new capacity is smaller than the size of the array, the elements are removed and the size is adjusted accordingly.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

array	a pointer to the array
capacity	the new capacity

universe@390:

Returns: zero on success, non-zero if reallocation failed

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_set_from()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_set_from	(	UcxArray *	array,
		size_t	index,
		void *	data,
		size_t	count
	)

universe@390:

universe@390: universe@390:

Sets elements starting at the specified index.

universe@390:

If the any index is out of bounds, the array automatically grows. The pointer to the data may be NULL, in which case the elements are zeroed.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

array	a pointer the array where to set the data
index	the index of the element to set
data	a pointer to the data to insert (may be `NULL`)
count	number of elements to copy from data (if data is `NULL`, the memory in the array is zeroed)

universe@390:

Returns: zero on success, non-zero if a reallocation was necessary but failed

universe@390:

See also: ucx_array_append_from(); universe@390: ucx_array_set()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_shrink()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_shrink ( UcxArray * array )

universe@390:

universe@390: universe@390:

Shrinks the memory to exactly fit the contents.

universe@390:

After this operation, the capacity equals the size.

universe@390:

Parameters

universe@390: universe@390: universe@390:

array a pointer to the array

universe@390:

Returns: zero on success, non-zero if reallocation failed

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_sort()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_array_sort	(	UcxArray *	array,
		cmp_func	cmpfnc,
		void *	data
	)

universe@390:

universe@390: universe@390:

Sorts a UcxArray with the best available sort algorithm.

universe@390:

The qsort_r() function is used, if available (glibc, FreeBSD or MacOS). The order of arguments is automatically adjusted for the FreeBSD and MacOS version of qsort_r().

universe@390:

If qsort_r() is not available, a merge sort algorithm is used, which is guaranteed to use no more additional memory than for exactly one element.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

array	the array to sort
cmpfnc	the function that shall be used to compare the element data
data	additional data for the cmp_func() or `NULL`

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_util_set_a()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_util_set_a	(	UcxAllocator *	alloc,
		void **	array,
		size_t *	capacity,
		size_t	elmsize,
		size_t	idx,
		void *	data
	)

universe@390:

universe@390: universe@390:

Sets an element in an arbitrary user defined array.

universe@390:

The data is copied from the specified data location.

universe@390:

If the capacity is insufficient, the array is automatically reallocated using the specified allocator and the possibly new pointer is stored in the array argument.

universe@390:

On reallocation the capacity of the array is doubled until it is sufficient. The new capacity is stored back to capacity.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

alloc	the allocator that shall be used to reallocate the array
array	a pointer to location of the array pointer
capacity	a pointer to the capacity
elmsize	the size of each element
idx	the index of the element to set
data	a pointer to the element data

universe@390:

Returns: zero on success or non-zero on error (errno will be set)

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_array_util_setptr_a()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_array_util_setptr_a	(	UcxAllocator *	alloc,
		void **	array,
		size_t *	capacity,
		size_t	idx,
		void *	ptr
	)

universe@390:

universe@390: universe@390:

Stores a pointer in an arbitrary user defined array.

universe@390:

The element size of the array must be sizeof(void*).

universe@390:

If the capacity is insufficient, the array is automatically reallocated using the specified allocator and the possibly new pointer is stored in the array argument.

universe@390:

On reallocation the capacity of the array is doubled until it is sufficient. The new capacity is stored back to capacity.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

alloc	the allocator that shall be used to reallocate the array
array	a pointer to location of the array pointer
capacity	a pointer to the capacity
idx	the index of the element to set
ptr	the pointer to store

universe@390:

Returns: zero on success or non-zero on error (errno will be set)

universe@390: universe@390:

universe@390:

universe@390: Data Structures

universe@390: Macros

universe@390: Functions

Detailed Description

Macro Definition Documentation

◆ ucx_array_util_set

◆ ucx_array_util_setptr

Function Documentation

◆ ucx_array_append_from()

◆ ucx_array_at()

◆ ucx_array_clone()

◆ ucx_array_concat()

◆ ucx_array_contains()

◆ ucx_array_destroy()

◆ ucx_array_equals()

◆ ucx_array_find()

◆ ucx_array_free()

◆ ucx_array_grow()

◆ ucx_array_init()

◆ ucx_array_init_a()

◆ ucx_array_new()

◆ ucx_array_new_a()

◆ ucx_array_prepend_from()

◆ ucx_array_remove()

◆ ucx_array_remove_fast()

◆ ucx_array_reserve()

◆ ucx_array_resize()

◆ ucx_array_set_from()

◆ ucx_array_shrink()

◆ ucx_array_sort()

◆ ucx_array_util_set_a()

◆ ucx_array_util_setptr_a()