icalarray.h File Reference

An array of arbitrarily-sized elements which grows dynamically as elements are added. More...

Go to the source code of this file.

Functions
void	icalarray_append (icalarray *array, const void *element)
	Appends an element to an array. More...
icalarray *	icalarray_copy (const icalarray *array)
void *	icalarray_element_at (icalarray *array, size_t position)
	Access an array element. More...
void	icalarray_free (icalarray *array)
icalarray *	icalarray_new (size_t element_size, size_t increment_size)
void	icalarray_remove_element_at (icalarray *array, size_t position)
	Removes a given element from an array. More...
void	icalarray_set_element_at (icalarray *array, const void *element, size_t position)
	Overwrites an existing element in an array with a new value. More...
void	icalarray_sort (icalarray *array, int(*compare)(const void *, const void *))
	Sorts the elements of an icalarray using the given comparison function. More...

Detailed Description

An array of arbitrarily-sized elements which grows dynamically as elements are added.

Definition in file icalarray.h.

Function Documentation

void icalarray_append	(	icalarray *	array,
		const void *	element
	)

Appends an element to an array.

Parameters

array	The array to append the element to
element	The element to append

Appends the given element to the array, reallocating and expanding the array as needed.

Error handling

If array or element is NULL, using this function results in undefined behaviour (most likely a segfault).

Ownership

The element does not get consumed by the method, since it creates a copy of it

Usage

• ```c // create new array icalarray *array = icalarray_new(sizeof(int), 1);

  // append data to it int data = 42; icalarray_append(array, &data);

  // release array icalarray_free(array);

• ```

Definition at line 119 of file icalarray.c.

icalarray* icalarray_copy

(

const icalarray *

array

)

Copies an existing icalarray and its elements, creating a new one.

Parameters

array

The array to copy

Returns

A new array, holding all the elements of array

Creates a new icalarray object, copying all the existing elements from array as well as its properties (such as element_size and increment_size) over.

Error handling

If array is NULL, this method will return NULL. If there was an error allocating memory while creating the copy, it will set icalerrno to ICAL_ALLOCATION_ERROR.

Ownership

The created copy is owned by the caller of the function, and needs to be released with icalarray_free() after it's no longer being used.

Usage

• ```c // create new array icalarray *array = icalarray_new(sizeof(int), 1);

  // fill array int a = 4; icalarray_append(array, &a);

  // create copy of array icalarray *copy = icalarray_copy(array); assert(*icalarray_element_at(copy, 0) == a);

  // release arrays icalarray_free(array); icalarray_free(copy);

• ```

Definition at line 69 of file icalarray.c.

void* icalarray_element_at	(	icalarray *	array,
		size_t	position
	)

Access an array element.

Parameters

array	The array object in which the element is stored
position	The position of the element to access in the array

Returns

A pointer to the element inside the array

Accesses an array element by returning a pointer to it, given an array and a valid element position.

Error handling

If array is NULL, using this function results in undefined behaviour. If position is not a valid position in the array, using this function results in undefined behaviour.

Ownership

The element is owned by the icalarray, it must not be freed by the user.

Usage

• ```c // create new array icalarray *array = icalarray_new(sizeof(int), 1);

  // fill array int a = 4; icalarray_append(array, &a);

  // access array element int *element = icalarray_element_at(array, 0); assert(element != NULL); assert(*element == a);

  // change array element *element = 14; assert(*icalarray_element(array) == 14);

  // release memory icalarray_free(array);

• ```

Definition at line 135 of file icalarray.c.

void icalarray_free

(

icalarray *

array

)

Frees an array object and everything that it contains.

Parameters

array

The array to release

Example

• ```c // creating an array icalarray *array = icalarray_new(sizeof(int), 1);

  // releasing it icalarray_free(array);

• ```

Definition at line 104 of file icalarray.c.

icalarray* icalarray_new	(	size_t	element_size,
		size_t	increment_size
	)

Creates a new icalarray object.

Parameters

element_size	The size of the elements to be held by the array
increment_size	How many extra elements worth of space to allocate on expansion

Returns

The new icalarray object

See also

icalarray_free()

Creates a new icalarray object. The parameter element_size determines the size of the elements that the array will hold (in bytes). The parameter increment_size determines how many extra elements to be allocated when expanding the array for performance reasons (expansions are expensive, since it involves copying all existing elements). If increment_size is zero, then the default increment size specified during libical build time is chosen.

Error handling

If element_size is not at least 1, using the icalarray object results in undefined behaviour. If there is an error while creating the object, it returns NULL and sets icalerrno to ICAL_NEWFAILED_ERROR.

Ownership

The returned icalarray object is owned by the caller of the function, and needs to be released properly after it's no longer needed with icalarray_free().

Usage

• ```c // create new array icalarray *array = icalarray_new(sizeof(int), 1);

  // use array int a = 4; icalarray_append(array, &a); assert(*icalarray_element_at(array, 0) == a);

  // release memory icalarray_free(array);

• ```

Definition at line 36 of file icalarray.c.

void icalarray_remove_element_at	(	icalarray *	array,
		size_t	position
	)

Removes a given element from an array.

Parameters

array	The array from which to remove the element
position	The position of the element to remove

Removes the element at the given position from the array.

Error handling

If array is NULL, using this function results in undefined behaviour. If the array is empty, using this function results in undefined behaviour. If the position is non-existent, it removes the last element.

Usage

• ```c // create new array icalarray *array = icalarray_new(sizeof(int), 2);

  // fill array int data; data = 4; icalarray_append(array, &a); data = 9; icalarray_append(array, &a); data = 7; icalarray_append(array, &a); data = 10; icalarray_append(array, &a);

  // check array assert(*icalarray_element_at(array, 0) == 4); assert(*icalarray_element_at(array, 1) == 9); assert(*icalarray_element_at(array, 2) == 7); assert(*icalarray_element_at(array, 3) == 10);

  // remove the second element icalarray_remove_element_at(array, 1);

  // check array assert(*icalarray_element_at(array, 0) == 4); assert(*icalarray_element_at(array, 1) == 7); assert(*icalarray_element_at(array, 2) == 10);

  // release array icalarray_free(array);

• ```

Definition at line 148 of file icalarray.c.

void icalarray_set_element_at	(	icalarray *	array,
		const void *	element,
		size_t	position
	)

Overwrites an existing element in an array with a new value.

Parameters

array	The array to overwrite the element in
element	The element to set as the new value
position	The position of the element to overwrite

Sets the given element at the position in the array, overwriting the current element at that position.

Error handling

If array or element is NULL or position is higher than the last position in the array, using this function results in undefined behaviour (most likely a segfault).

Ownership

The element does not get consumed by the method, since it creates a copy of it. The existing element gets overwritten, callers are responsible to free any heap-allocated values of the element.

Since

4.0

Definition at line 143 of file icalarray.c.

void icalarray_sort	(	icalarray *	array,
		int(*)(const void *, const void *)	compare
	)

Sorts the elements of an icalarray using the given comparison function.

Parameters

array	The array to sort
compare	The comparison function to use

Error handling

Passing NULL as either array or compare results in undefined behaviour.

Usage

• ```c int compare_ints(const void <em>a, const void *b) { return *((int)a) - *((int*)b); }

  int main(int argc, char *argv[]) { int numbers[] = {5, 2, 7, 4, 3, 1, 0, 8, 6, 9};

  icalarray *array = icalarray_new(sizeof(int), 3);

  // fill array for(int i = 0; i < 10; i++) { icalarray_append(array, &numbers[i]); }

  // sort array icalarray_sort(array, compare_ints);

  // print numbers for(int i = 0; i < 10; i++) { printf("%i\n", *((int*)icalarray_element_at(array, i))); }

  return 0; }

• ```

Definition at line 182 of file icalarray.c.