array.h File Reference

Dynamic arrays. More...

#include <stdbool.h>
#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	array_t
	O2S array implementation. More...

Functions
Modifiers
bool	array_push_back (array_t *self, const void *element)
	Adds one element at the end of the array.
bool	array_push_back_n (array_t *self, const void *elements, size_t count)
	Adds count elements at the end of the array.
bool	array_pop_back (array_t *self, void *destination)
	Moves to destination the last element of the array.
bool	array_pop_back_n (array_t *self, void *destination, size_t count)
	Moves to destination the n last elements of the array.
bool	array_pop_front (array_t *self, void *destination)
	Moves to destination the first element of self.
bool	array_pop_front_n (array_t *self, void *destination, size_t count)
	Moves to destination the count first elements of self.
Element access
void *	array_first (const array_t *self)
	Pointer to the first element of the array.
void *	array_last (const array_t *self)
	Pointer of the last element of the array.
void *	array_get (const array_t *self, size_t index)
	Pointer of the element at position index of the array.
void *	array_end (const array_t *self)
	One-past-the-end pointer of the array.
Capacity
bool	array_is_empty (const array_t *self)
	True if the array contains no element.
size_t	array_count (const array_t *self)
	Number of elements stored.
bool	array_reserve (array_t *self, size_t count)
	Ensures the array has enough capacity to fit count new elements, reallocating if needed.
bool	array_trim (array_t *self)
	Resizes the underlying storage to fit exactly the current elements count.

Initializing and destroying
#define	ArrayNew(Type)
	Convenient constructor wrapper.
#define	Array
	Automatically free the allocated storage when going out of scope.
array_t	array_new (size_t type_size)
	Contructs an empty array, no memory is allocated.
void	array_clear (array_t *self)
	Clears properly the array.
void	array_clear_f (array_t *self, void(*cleanup)(void *))
	Release the resources of each elements before clearing the array.

Iterators
#define	array_foreach(TYPE, ARRAY, ELEMENT)
	Iterate over the elements of the array.
#define	array_enumerate(TYPE, ARRAY, ELEMENT, INDEX)
	Iterate over the elements of the array, with the index.
void	array_iter (const array_t *self, void(*function)(void *))
	Call function on each element.

Detailed Description

Dynamic arrays.

Copyright

2023, SAFRAN T4DS, ALL RIGHTS RESERVED

Author

Antoine GAGNIERE

Hugo FOLCHER

Here is the intended usage of arrays:

#include <o2s/array.h>
 
#include <stdio.h>
 
int main()
{
    int   content[] = {42, 57, 123};
    // Create an array of integers, that will free the allocated storage when destroyed
    Array my_array  = ArrayNew(int);
 
    array_push_back_n(&my_array, content, 2); // append any number of elements at the end
    array_push_back(&my_array, content + 2); // append a single element at the end
 
    printf("We now have an array with %lu elements\n", array_count(&my_array));
    printf("It starts with %i and ends with %i\n",
            *(int*)array_first(&my_array),
            *(int*)array_last(&my_array));
    printf("The middle element is %i \n", *(int*)array_get(&my_array, 1));
 
    unsigned index;
    int      element;
 
    printf("\nArray content:\n");
    array_enumerate (int, &my_array, &element, &index)
    {
        printf("[%u] %i\n", index, element);
    }
}

We now have an array with 3 elements
It starts with 42 and end with 123
The middle element is 57
 
Array content:
[0] 42
[1] 57
[2] 123

Definition in file array.h.

Macro Definition Documentation

Array

#define Array

Automatically free the allocated storage when going out of scope.

In a situation where one wants to declare an array in a local scope, this "typedef" can be used for that array to release the allocated memory automatically when the variable goes out of scope.

It means this "typedef" can only be used like this:

{
    Array my_array = ArrayNew(float);
    ...
} // <- the underlying storage will be freed at that point

Definition at line 55 of file array.h.

array_enumerate

#define array_enumerate	(		TYPE,
			ARRAY,
			ELEMENT,
			INDEX )

Iterate over the elements of the array, with the index.

To be used like a for loop

Definition at line 104 of file array.h.

array_foreach

#define array_foreach	(		TYPE,
			ARRAY,
			ELEMENT )

Iterate over the elements of the array.

To be used like a for loop

Definition at line 95 of file array.h.

Function Documentation

array_clear()

void array_clear

(

array_t *

self

)

Clears properly the array.

Frees the underlying storage, and leaves the array in a usable state

Definition at line 33 of file constructors_destructors.c.

array_clear_f()

void array_clear_f	(	array_t *	self,
		void(*	cleanup )(void *) )

Release the resources of each elements before clearing the array.

In the case of an array storing elements that own resources, each element should be cleaned up before the array is emptied.

Definition at line 47 of file constructors_destructors.c.

array_end()

void * array_end

(

const array_t *

self

)

One-past-the-end pointer of the array.

Returns

NULL if the underlying storage isn't allocated

Definition at line 25 of file getters.c.

array_first()

void * array_first

(

const array_t *

self

)

Pointer to the first element of the array.

Returns

NULL if the array is empty.

Definition at line 36 of file getters.c.

array_get()

void * array_get	(	const array_t *	self,
		size_t	index )

Pointer of the element at position index of the array.

Returns

NULL if invalid index.

Definition at line 56 of file getters.c.

array_last()

void * array_last

(

const array_t *

self

)

Pointer of the last element of the array.

Returns

NULL if the array is empty.

Definition at line 45 of file getters.c.

array_pop_back()

bool array_pop_back	(	array_t *	self,
		void *	destination )

Moves to destination the last element of the array.

Returns

false if the array is empty.

Definition at line 68 of file push_pop.c.

array_pop_back_n()

bool array_pop_back_n	(	array_t *	self,
		void *	destination,
		size_t	count )

Moves to destination the n last elements of the array.

Destination can be NULL to just discard the elements.

Returns

false if not enough element in the array.

Definition at line 53 of file push_pop.c.

array_pop_front()

bool array_pop_front	(	array_t *	self,
		void *	destination )

Moves to destination the first element of self.

Returns

false if the array is empty

Definition at line 93 of file push_pop.c.

array_pop_front_n()

bool array_pop_front_n	(	array_t *	self,
		void *	destination,
		size_t	count )

Moves to destination the count first elements of self.

Returns

false if there are not enough elements in the array

Definition at line 77 of file push_pop.c.

array_push_back()

bool array_push_back	(	array_t *	self,
		const void *	element )

Adds one element at the end of the array.

Returns

false if allocation failed.

Definition at line 43 of file push_pop.c.

array_push_back_n()

bool array_push_back_n	(	array_t *	self,
		const void *	elements,
		size_t	count )

Adds count elements at the end of the array.

Returns

false if allocation failed.

Definition at line 28 of file push_pop.c.

array_reserve()

bool array_reserve	(	array_t *	self,
		size_t	count )

Ensures the array has enough capacity to fit count new elements, reallocating if needed.

Returns

false if allocation was needed and failed.

Definition at line 47 of file memory.c.

array_trim()

bool array_trim

(

array_t *

self

)

Resizes the underlying storage to fit exactly the current elements count.

Returns

false if allocation failed.

Definition at line 65 of file memory.c.