Array
[Containers]

These functions provide array management. More...

Data Structures

struct  _Eina_Array
 Type for an array of data. More...

Defines

#define EINA_ARRAY_ITER_NEXT(array, index, item, iterator)
 Macro to iterate over an array easily.

Typedefs

typedef struct _Eina_Array Eina_Array
 Type for a generic vector.
typedef void ** Eina_Array_Iterator
 Type for an iterator on arrays, used with EINA_ARRAY_ITER_NEXT.

Functions

EAPI int eina_array_init (void)
 Initialize the array module.
EAPI int eina_array_shutdown (void)
 Shut down the array module.
EAPI Eina_Arrayeina_array_new (unsigned int step)
 Create a new array.
EAPI void eina_array_free (Eina_Array *array)
 Free an array.
EAPI void eina_array_step_set (Eina_Array *array, unsigned int step)
 Set the step of an array.
EAPI void eina_array_clean (Eina_Array *array)
 Clean an array.
EAPI void eina_array_flush (Eina_Array *array)
 Flush an array.
EAPI Eina_Bool eina_array_remove (Eina_Array *array, Eina_Bool(*keep)(void *data, void *gdata), void *gdata)
 Rebuild an array by specifying the data to keep.
EAPI Eina_Bool static Eina_Bool eina_array_push (Eina_Array *array, const void *data)
 Append a data to an array.
EAPI Eina_Bool static
Eina_Bool static void * 
eina_array_pop (Eina_Array *array)
 Remove the last data of an array.
static void * eina_array_data_get (const Eina_Array *array, unsigned int index)
 Return the data at a given position in an array.
static void eina_array_data_set (const Eina_Array *array, unsigned int index, const void *data)
 Return the data at a given position in an array.
static void static unsigned int eina_array_count_get (const Eina_Array *array)
 Return the number of elements in an array.
EAPI Eina_Iteratoreina_array_iterator_new (const Eina_Array *array)
 Returned a new iterator asociated to an array.
EAPI Eina_Accessoreina_array_accessor_new (const Eina_Array *array)
 Returned a new accessor asociated to an array.

Detailed Description

These functions provide array management.

The Array data type in Eina is designed to have a very fast access to its data (compared to the Eina List). On the other hand, data can be added or removed only at the end of the array. To insert data at any place, the Eina List is the correct container to use.

To use the array data type, eina_array_init() must be called before any other array functions. When no more array function is used, eina_array_shutdown() must be called to free all the resources.

An array must be created with eina_array_new(). It allocated all the necessary data for an array. When not needed anymore, an array is freed with eina_array_free(). This function does not free any allocated memory used to store the data of each element. For that, just iterate over the array to free them. A convenient way to do that is by using EINA_ARRAY_ITER_NEXT. An example of code is given in the description of this macro.

Warning:
All the other functions do not check if the used array is valid or not. It's up to the user to be sure of that. It is designed like that for performance reasons.

The usual features of an array are classic ones: to append an element, use eina_array_push() and to remove the last element, use eina_array_pop(). To retrieve the element at a given positin, use eina_array_data_get(). The number of elements can be retrieved with eina_array_count_get().

For more information, you can look at the Array Tutorial.


Define Documentation

#define EINA_ARRAY_ITER_NEXT ( array,
index,
item,
iterator   ) 
Value:
for (index = 0, iterator = (array)->data; \
       (index < eina_array_count_get(array)) && ((item = *((iterator)++))); \
       ++(index))

Macro to iterate over an array easily.

Parameters:
array The array to iterate over.
index The integer number that is increased while itareting.
item The data
iterator The iterator

This macro allow the iteration over array in an easy way. It iterates from the first element to the last one. index is an integer that increase from 0 to the number of elements. item is the data of each element of array, so it is a pointer to a type chosen by the user. iterator is of type Eina_Array_Iterator.

This macro can be used for freeing the data of an array, like in the following example:

 Eina_Array         *array;
 char               *item;
 Eina_Array_Iterator iterator;
 unsigned int        i;

 // array is already filled,
 // its elements are just duplicated strings,
 // EINA_ARRAY_ITER_NEXT will be used to free those strings

 EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
   free(item);

Referenced by eina_module_list_flush(), and eina_module_list_load().


Function Documentation

EAPI int eina_array_init ( void   ) 

Initialize the array module.

Returns:
1 or greater on success, 0 on error.

This function sets up the error and magic modules or Eina. It is also called by eina_init(). It returns 0 on failure, otherwise it returns the number of times it has already been called. See eina_error_init() and eina_magic_string_init() for the documentation of the initialisation of the dependency modules.

When no more Eina arrays are used, call eina_array_shutdown() to shut down the array module.

See also:
eina_error_init()
eina_magic_string_init()
eina_init()

References eina_error_init(), EINA_ERROR_PERR, eina_error_shutdown(), and eina_magic_string_init().

Referenced by eina_benchmark_init(), and eina_init().

EAPI int eina_array_shutdown ( void   ) 

Shut down the array module.

Returns:
0 when the list module is completely shut down, 1 or greater otherwise.

This function shuts down the array module. It returns 0 when it has been called the same number of times than eina_array_init(). In that case it shut down the magic and error modules. This function is also called by eina_shutdown(). See eina_error_shutdown() and eina_magic_string_shutdown() for the documentation of the shutting down of the dependency modules.

See also:
eina_error_shutdown()
eina_magic_string_shutdown()
eina_shutdown()

References eina_error_shutdown(), and eina_magic_string_shutdown().

Referenced by eina_benchmark_init(), eina_benchmark_shutdown(), eina_init(), and eina_shutdown().

EAPI Eina_Array * eina_array_new ( unsigned int  step  ) 

Create a new array.

Parameters:
step The count of pointers to add when increasing the array size.
Returns:
NULL on failure, non NULL otherwise.

This function creates a new array. When adding an element, the array allocates step elements. When that buffer is full, then adding another element will increase the buffer of step elements again.

This function return a valid array on success, or NULL if memory allocation fails. In that case, the error is set to EINA_ERROR_OUT_OF_MEMORY.

References _Eina_Array::count, _Eina_Array::data, EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), _Eina_Array::step, and _Eina_Array::total.

Referenced by eina_benchmark_run(), eina_file_split(), and eina_module_list_get().

EAPI void eina_array_free ( Eina_Array array  ) 

Free an array.

Parameters:
array The array to free.

This function frees array. It calls first eina_array_flush() then free the memory of the pointeur. It does not free the memory allocated for the elements of array. To free them, use EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check of array.

References eina_array_flush().

EAPI void eina_array_step_set ( Eina_Array array,
unsigned int  step 
)

Set the step of an array.

Parameters:
array The array.
step The count of pointers to add when increasing the array size.

This function sets the step of array to step. For performance reasons, there is no check of array. If it is NULL or invalid, the program may crash.

References _Eina_Array::count, _Eina_Array::data, _Eina_Array::step, and _Eina_Array::total.

EAPI void eina_array_clean ( Eina_Array array  ) 

Clean an array.

Parameters:
array The array to clean.

This function sets the count member of array to 0. For performance reasons, there is no check of array. If it is NULL or invalid, the program may crash.

References _Eina_Array::count.

EAPI void eina_array_flush ( Eina_Array array  ) 

Flush an array.

Parameters:
array The array to flush.

This function sets the count and total members of array to 0, frees and set to NULL its data member. For performance reasons, there is no check of array. If it is NULL or invalid, the program may crash.

References _Eina_Array::count, _Eina_Array::data, and _Eina_Array::total.

Referenced by eina_array_free(), and eina_module_list_flush().

EAPI Eina_Bool eina_array_remove ( Eina_Array array,
Eina_Bool(*)(void *data, void *gdata)  keep,
void *  gdata 
)

Rebuild an array by specifying the data to keep.

Parameters:
array The array.
keep The functions which selects the data to keep.
gdata The data to pass to the function keep.
Returns:
EINA_TRUE on success, EINA_FALSE oterwise.

This function rebuilds array be specifying the elements to keep with the function keep. gdata is an additional data to pass to keep. For performance reasons, there is no check of array. If it is NULL or invalid, the program may crash.

This function always return a valid array. If it wasn't able to remove items due to an allocation failure, it will return EINA_FALSE and the error is set to EINA_ERROR_OUT_OF_MEMORY.

References _Eina_Array::count, _Eina_Array::data, eina_array_data_get(), EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), EINA_FALSE, EINA_TRUE, and _Eina_Array::total.

static Eina_Bool eina_array_push ( Eina_Array array,
const void *  data 
) [inline, static]

Append a data to an array.

Parameters:
array The array.
data The data to add.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

This function appends data to array. For performance reasons, there is no check of array. If it is NULL or invalid, the program may crash. If data is NULL, or if an allocation is necessary and fails, EINA_FALSE is returned and EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, EINA_TRUE is returned.

References _Eina_Array::count, _Eina_Array::data, EINA_FALSE, EINA_TRUE, and _Eina_Array::total.

Referenced by eina_benchmark_run(), and eina_file_split().

static void * eina_array_pop ( Eina_Array array  )  [inline, static]

Remove the last data of an array.

Parameters:
array The array.
Returns:
The retrieved data.

This function removes the last data of array, decreases the count of array and returns the data. For performance reasons, there is no check of array. If it is NULL or invalid, the program may crash. If the count member is less or equal than 0, NULL is returned.

References _Eina_Array::count, and _Eina_Array::data.

static void * eina_array_data_get ( const Eina_Array array,
unsigned int  index 
) [inline, static]

Return the data at a given position in an array.

Parameters:
array The array.
index The potition of the data to retrieve.
Returns:
The retrieved data.

This function returns the data at the position index in array. For performance reasons, there is no check of array or index. If it is NULL or invalid, the program may crash.

References _Eina_Array::data.

Referenced by eina_array_remove().

static void eina_array_data_set ( const Eina_Array array,
unsigned int  index,
const void *  data 
) [inline, static]

Return the data at a given position in an array.

Parameters:
array The array.
index The potition of the data to set.
data The data to set.

This function returns the data at the position index in array. For performance reasons, there is no check of array or index. If it is NULL or invalid, the program may crash.

References _Eina_Array::data.

static unsigned int eina_array_count_get ( const Eina_Array array  )  [inline, static]

Return the number of elements in an array.

Parameters:
array The array.
Returns:
The number of elements.

This function returns the number of elements in array. For performance reasons, there is no check of array. If it is NULL or invalid, the program may crash.

References _Eina_Array::count.

Referenced by eina_array_iterator_new().

EAPI Eina_Iterator * eina_array_iterator_new ( const Eina_Array array  ) 

Returned a new iterator asociated to an array.

Parameters:
array The array.
Returns:
A new iterator.

This function returns a newly allocated iterator associated to array. If array is NULL or the count member of array is less or equal than 0, this function returns NULL. If the memory can not be allocated, NULL is returned and EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is returned.

References eina_array_count_get(), EINA_ERROR_OUT_OF_MEMORY, and eina_error_set().

EAPI Eina_Accessor * eina_array_accessor_new ( const Eina_Array array  ) 

Returned a new accessor asociated to an array.

Parameters:
array The array.
Returns:
A new accessor.

This function returns a newly allocated accessor associated to array. If array is NULL or the count member of array is less or equal than 0, this function returns NULL. If the memory can not be allocated, NULL is returned and EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid accessor is returned.

References EINA_ERROR_OUT_OF_MEMORY, and eina_error_set().