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.

Data Structures
struct	_icalarray

Typedefs
typedef struct _icalarray	icalarray
	A struct representing an icalarray object.

Functions
void	icalarray_append (icalarray *array, const void *element)
	Appends an element to an array.
icalarray *	icalarray_copy (const icalarray *array)
	Copies an existing icalarray and its elements, creating a new one.
void *	icalarray_element_at (icalarray *array, size_t position)
	Access an array element.
void	icalarray_free (icalarray *array)
	Frees an array object and everything that it contains.
icalarray *	icalarray_new (size_t element_size, size_t increment_size)
	Creates a new icalarray object.
void	icalarray_remove_element_at (icalarray *array, size_t position)
	Removes a given element from an array.
void	icalarray_set_element_at (icalarray *array, const void *element, size_t position)
	Overwrites an existing element in an array with a new value.
void	icalarray_sort (icalarray *array, int(*compare)(const void *, const void *))
	Sorts the elements of an icalarray using the given comparison function.

Detailed Description

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

Function Documentation

icalarray_append()

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

// 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);

icalarray_copy()

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

// 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);

icalarray_element_at()

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

// 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);

icalarray_free()

void icalarray_free

(

icalarray *

array

)

Frees an array object and everything that it contains.

Parameters

array

The array to release

Example

// creating an array
icalarray *array = icalarray_new(sizeof(int), 1);
 
// releasing it
icalarray_free(array);

icalarray_new()

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

// 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);

icalarray_remove_element_at()

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

// 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);

icalarray_set_element_at()

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

icalarray_sort()

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

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

int compare_ints(const void *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;
}