Libical API Documentation 3.0

Data Structures | Typedefs | Functions
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. More...
icalarray * | icalarray_copy (icalarray *array)
| Copies an existing icalarray and its elements, creating a new one. More...
void * | icalarray_element_at (icalarray *array, size_t position)
| Access an array element. More...
void | icalarray_free (icalarray *array)
| Frees an array object and everything that it contains. More...
icalarray * | icalarray_new (size_t element_size, size_t increment_size)
| Creates a new icalarray object. More...
void | icalarray_remove_element_at (icalarray *array, size_t position)
| Removes a given element from an array. 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.

## 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_free
void icalarray_free(icalarray *array)
Frees an array object and everything that it contains.
Definition: icalarray.c:90
icalarray_append
void icalarray_append(icalarray *array, const void *element)
Appends an element to an array.
Definition: icalarray.c:105
icalarray_new
icalarray * icalarray_new(size_t element_size, size_t increment_size)
Creates a new icalarray object.
Definition: icalarray.c:31
_icalarray
Definition: icalarray.h:36

## ◆ icalarray_copy()

icalarray * icalarray_copy | ( | 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.
Definition: icalarray.c:117
icalarray_copy
icalarray * icalarray_copy(icalarray *array)
Copies an existing icalarray and its elements, creating a new one.
Definition: icalarray.c:60

## ◆ 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).

Error handling
  If element_size or increment_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 functino 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_remove_element_at
void icalarray_remove_element_at(icalarray *array, size_t position)
Removes a given element from an array.
Definition: icalarray.c:125

## ◆ icalarray_sort()

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

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;
}
icalarray_sort
void icalarray_sort(icalarray *array, int(*compare)(const void *, const void *))
Sorts the elements of an icalarray using the given comparison function.
Definition: icalarray.c:136