FTS array
[FTS Utilitiy Data Structures]

---

Detailed Description

FTS array data structure.

Growable array of atoms.

FTS array contains atoms that can be accessed by index. Its size can grow and shrink to accomodate adding elements or by call to fts_array_set_size().

Typically the array base structure is allocated within another data structure or on the stack.

fts_array_t my_array;

fts_array_init(&my_array, 0, NULL);
...
fts_array_destroy(&my_array);

An array has a allocation_increment. The array memory is increased by chunks of allocation_increment. To reduce the amount of reallocation, this allocation_increment can be made larger before adding a large number of elements.

Typedefs
typedef struct fts_array	fts_array_t
	FTS array data type.
Functions
FTS_API void	fts_array_init (fts_array_t *array, int ac, const fts_atom_t *at)
	Initialise an array.
FTS_API void	fts_array_destroy (fts_array_t *array)
	Destroy (deinitialise) an array.
FTS_API void	fts_array_clear (fts_array_t *array)
	Clear the content of an array (set size to 0).
FTS_API void	fts_array_set_size (fts_array_t *array, int new_size)
	Set the size of an array.
FTS_API void	fts_array_set (fts_array_t *array, int ac, const fts_atom_t *at)
	Set the content of an array.
FTS_API void	fts_array_append (fts_array_t *array, int ac, const fts_atom_t *at)
	Append elements at the end of an array.
FTS_API void	fts_array_append_int (fts_array_t *array, int i)
	Append an int element at the end of an array.
FTS_API void	fts_array_append_float (fts_array_t *array, float f)
	Append a float element at the end of array.
FTS_API void	fts_array_append_symbol (fts_array_t *array, fts_symbol_t s)
	Append a symbol element at the end of an array.
FTS_API void	fts_array_append_object (fts_array_t *array, fts_object_t *obj)
	Append an object element at the end of an array.
FTS_API void	fts_array_prepend (fts_array_t *array, int ac, const fts_atom_t *at)
	Prepend elements at the beginning of an array.
FTS_API void	fts_array_prepend_int (fts_array_t *array, int i)
	Prepend an int element at the beginning of an array.
FTS_API void	fts_array_prepend_float (fts_array_t *array, float f)
	Prepend a float element at the beginning of an array.
FTS_API void	fts_array_prepend_symbol (fts_array_t *array, fts_symbol_t s)
	Prepend a symbol element at the beginning of the array.
FTS_API void	fts_array_insert (fts_array_t *array, int index, int ac, const fts_atom_t *at)
	Insert elements at given index of an array.
FTS_API void	fts_array_cut (fts_array_t *array, int index, int n)
	Cut given number of elements from given index of the array.
FTS_API void	fts_array_copy (fts_array_t *org, fts_array_t *copy)
	Copy the values of an array to another.
FTS_API fts_atom_t *	fts_array_get_atoms (fts_array_t *array)
	Get a pointer to the values (atoms) of an array.
FTS_API int	fts_array_get_size (fts_array_t *array)
	Get the size of an array.
FTS_API void	fts_array_set_element (fts_array_t *array, int index, const fts_atom_t *at)
	Set the value of an element at a given index.
FTS_API fts_atom_t *	fts_array_get_element (fts_array_t *array, int index)
	Get a pointer to the value of an element at a given index.
FTS_API void	fts_array_get_values (fts_array_t *array, fts_iterator_t *iter)
	Get an iterator on the elements of an array.
FTS_API void	fts_array_sort (fts_array_t *array, int ascending)
	Sort the elements of an array.

---

Function Documentation

FTS_API void fts_array_append	(	fts_array_t *	array,
		int	ac,
		const fts_atom_t *	at
	)

Append elements at the end of an array.

Parameters:

	array	the array
	ac	the atoms count
	at	atoms to append

FTS_API void fts_array_append_float	(	fts_array_t *	array,
		float	f
	)

Append a float element at the end of array.

Parameters:

	array	the array
	f	the float to append

FTS_API void fts_array_append_int	(	fts_array_t *	array,
		int	i
	)

Append an int element at the end of an array.

Parameters:

	array	the array
	i	the int to append

FTS_API void fts_array_append_object	(	fts_array_t *	array,
		fts_object_t *	obj
	)

Append an object element at the end of an array.

Parameters:

	array	the array
	obj	the object

FTS_API void fts_array_append_symbol	(	fts_array_t *	array,
		fts_symbol_t	s
	)

Append a symbol element at the end of an array.

Parameters:

	array	the array
	s	the symbol to append

FTS_API void fts_array_clear

(

fts_array_t *

array

)

Clear the content of an array (set size to 0).

After calling fts_array_clear(), array will contain no elements, but will keep its allocation state (i.e. its capacity will be its capacity before call).

clears the content of the array

Parameters:

array

the array

FTS_API void fts_array_copy	(	fts_array_t *	org,
		fts_array_t *	copy
	)

Copy the values of an array to another.

Parameters:

	org	the source
	copy	the destination of the copy

FTS_API void fts_array_cut	(	fts_array_t *	array,
		int	index,
		int	n
	)

Cut given number of elements from given index of the array.

Parameters:

	array	the array
	index	the index
	n	the atoms count

FTS_API void fts_array_destroy

(

fts_array_t *

array

)

Destroy (deinitialise) an array.

Parameters:

array

the array

FTS_API fts_atom_t* fts_array_get_atoms

(

fts_array_t *

array

)

Get a pointer to the values (atoms) of an array.

Parameters:

array

the array

Returns:

a pointer to the content of the array

FTS_API fts_atom_t* fts_array_get_element	(	fts_array_t *	array,
		int	index
	)

Get a pointer to the value of an element at a given index.

Parameters:

	array	the array
	index	the index

Returns:

a pointer to the specified element of the array

FTS_API int fts_array_get_size

(

fts_array_t *

array

)

Get the size of an array.

Parameters:

array

the array

Returns:

the size of the array

Get the number of elements in an array

FTS_API void fts_array_get_values	(	fts_array_t *	array,
		fts_iterator_t *	iter
	)

Get an iterator on the elements of an array.

Parameters:

	array	the array
	iter	the iterator

FTS_API void fts_array_init	(	fts_array_t *	array,
		int	ac,
		const fts_atom_t *	at
	)

Initialise an array.

Parameters:

	array	the array
	ac	the atoms count
	at	atoms to initialize the content of the array

FTS_API void fts_array_insert	(	fts_array_t *	array,
		int	index,
		int	ac,
		const fts_atom_t *	at
	)

Insert elements at given index of an array.

Parameters:

	array	the array
	index	the index
	ac	the atoms count
	at	atoms to append

FTS_API void fts_array_prepend	(	fts_array_t *	array,
		int	ac,
		const fts_atom_t *	at
	)

Prepend elements at the beginning of an array.

Parameters:

	array	the array
	ac	the atoms count
	at	atoms to append

FTS_API void fts_array_prepend_float	(	fts_array_t *	array,
		float	f
	)

Prepend a float element at the beginning of an array.

Parameters:

	array	the array
	f	the float to prepend

FTS_API void fts_array_prepend_int	(	fts_array_t *	array,
		int	i
	)

Prepend an int element at the beginning of an array.

Parameters:

	array	the array
	i	the int to prepend

FTS_API void fts_array_prepend_symbol	(	fts_array_t *	array,
		fts_symbol_t	s
	)

Prepend a symbol element at the beginning of the array.

Parameters:

	array	the array
	s	the symbol to prepend

FTS_API void fts_array_set	(	fts_array_t *	array,
		int	ac,
		const fts_atom_t *	at
	)

Set the content of an array.

Parameters:

	array	the array
	ac	the atoms count
	at	atoms to initialize the content of the array

FTS_API void fts_array_set_element	(	fts_array_t *	array,
		int	index,
		const fts_atom_t *	at
	)

Set the value of an element at a given index.

If index >= size, the array will be extended.

Parameters:

	array	the array
	index	the index
	at	element value

FTS_API void fts_array_set_size	(	fts_array_t *	array,
		int	new_size
	)

Set the size of an array.

If new size is greater that current size, VOID atoms will be added to the end. If new size is smaller, all elements between new_size and current size will be made VOID.

Parameters:

	array	the array
	new_size	the new size

FTS_API void fts_array_sort	(	fts_array_t *	array,
		int	ascending
	)

Sort the elements of an array.

Parameters:

	array	the array
	ascending	flag wether the elements are sorted in ascending order (or descending)