These functions provide array management. More...
Macros | |
#define | EINA_ARRAY_ITER_NEXT(array, index, item, iterator) |
Macro to iterate over an array easily. More... | |
Typedefs | |
typedef struct _Eina_Array | Eina_Array |
typedef void ** | Eina_Array_Iterator |
Type for an iterator on arrays, used with EINA_ARRAY_ITER_NEXT. | |
typedef struct _Eina_Array | Eina_Array |
Type for a generic vector. | |
Functions | |
EAPI Eina_Array * | eina_array_new (unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT |
Create a new array. More... | |
EAPI void | eina_array_free (Eina_Array *array) EINA_ARG_NONNULL(1) |
Free an array. More... | |
EAPI void | eina_array_step_set (Eina_Array *array, unsigned int sizeof_eina_array, unsigned int step) EINA_ARG_NONNULL(1) |
Set the step of an array. More... | |
static void | eina_array_clean (Eina_Array *array) EINA_ARG_NONNULL(1) |
Clean an array. More... | |
EAPI void | eina_array_flush (Eina_Array *array) EINA_ARG_NONNULL(1) |
Flush an array. More... | |
EAPI Eina_Bool | eina_array_remove (Eina_Array *array, Eina_Bool(*keep)(void *data, void *gdata), void *gdata) EINA_ARG_NONNULL(1 |
Rebuild an array by specifying the data to keep. More... | |
EAPI Eina_Bool static Eina_Bool | eina_array_push (Eina_Array *array, const void *data) EINA_ARG_NONNULL(1 |
EAPI Eina_Bool static Eina_Bool static void * | eina_array_pop (Eina_Array *array) EINA_ARG_NONNULL(1) |
static void * | eina_array_data_get (const Eina_Array *array, unsigned int idx) EINA_ARG_NONNULL(1) |
static void | eina_array_data_set (const Eina_Array *array, unsigned int idx, const void *data) EINA_ARG_NONNULL(1) |
Set the data at a given position in an array. More... | |
static unsigned int | eina_array_count_get (const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT |
static unsigned int | eina_array_count (const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT |
EAPI Eina_Iterator * | eina_array_iterator_new (const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT |
Returned a new iterator associated to an array. More... | |
EAPI Eina_Accessor * | eina_array_accessor_new (const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT |
Returned a new accessor associated to an array. More... | |
static Eina_Bool | eina_array_foreach (Eina_Array *array, Eina_Each_Cb cb, void *fdata) |
Provide a safe way to iterate over an array. More... | |
These functions provide array management.
The Array data type in Eina is designed to have 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_init() must be called before any other array functions. When no more eina array functions are used, eina_shutdown() must be called to free all the resources.
An array must be created with eina_array_new(). It allocates 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.
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 position, use eina_array_data_get(). The number of elements can be retrieved with eina_array_count().
Eina_Array is different from a conventional C array in a number of ways, most importantly they grow and shrink dynamically, this means that if you add an element to a full array it grows and that when you remove an element from an array it may shrink.
When the array needs to grow it allocates memory not just for the element currently being added since that would mean allocating memory(which is computationally expensive) often, instead it grows to be able to hold step
more elements. Similarly if you remove elements in such a way that that the array is left holding its capacity - step
elements it will shrink.
The following image illustrates how an Eina_Array grows:
Eina_Array only stores pointers but it can store data of any type in the form of void pointers.
See here some examples:
#define EINA_ARRAY_ITER_NEXT | ( | array, | |
index, | |||
item, | |||
iterator | |||
) |
Macro to iterate over an array easily.
array | The array to iterate over. |
index | The integer number that is increased while iterating. |
item | The data |
iterator | The iterator |
This macro allows the iteration over array
in an easy way. It iterates from the first element to the last one. index
is an integer that increases 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:
Referenced by eina_benchmark_free(), eina_module_find(), eina_module_list_free(), eina_module_list_load(), and eina_module_list_unload().
EAPI Eina_Array* eina_array_new | ( | unsigned int | step | ) |
Create a new array.
step | The count of pointers to add when increasing the array size. |
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 by step
elements again.
This function return a valid array on success, or NULL
if memory allocation fails.
References EINA_MAGIC_SET.
Referenced by eina_benchmark_run(), eina_file_split(), eina_module_arch_list_get(), eina_module_list_get(), eldbus_service_property_changed(), and evas_device_push().
EAPI void eina_array_free | ( | Eina_Array * | array | ) |
Free an array.
array | The array to free. |
This function frees array
. It calls first eina_array_flush() then free the memory of the pointer. 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().
Referenced by eina_benchmark_free(), and eldbus_service_interface_register().
EAPI void eina_array_step_set | ( | Eina_Array * | array, |
unsigned int | sizeof_eina_array, | ||
unsigned int | step | ||
) |
Set the step of an array.
array | The array. |
sizeof_eina_array | Should be the value returned by sizeof(Eina_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_MAGIC_SET.
|
inlinestatic |
Clean an array.
array | The array to clean. |
This function sets the count member of array
to 0, however it doesn't free any space. This is particularly useful if you need to empty the array and add lots of elements quickly. For performance reasons, there is no check of array
. If it is NULL
or invalid, the program may crash.
EAPI void eina_array_flush | ( | Eina_Array * | array | ) |
Flush an array.
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.
Referenced by eina_array_free(), and eina_module_list_free().
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.
array | The array. |
keep | The functions which selects the data to keep. |
gdata | The data to pass to the function keep. |
This function rebuilds array
be specifying the elements to keep with the function keep
. No empty/invalid fields are left in the array. 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.
If it wasn't able to remove items due to an allocation failure, it will return EINA_FALSE.
|
inlinestatic |
Set the data at a given position in an array.
array | The array. |
idx | The position of the data to set. |
data | The data to set. |
This function sets the data at the position idx
in array
to data
, this effectively replaces the previously held data, you must therefore get a pointer to it first if you need to free it. For performance reasons, there is no check of array
or idx
. If it is NULL
or invalid, the program may crash.
EAPI Eina_Iterator* eina_array_iterator_new | ( | const Eina_Array * | array | ) |
Returned a new iterator associated to an array.
array | The array. |
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. Otherwise, a valid iterator is returned.
References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.
EAPI Eina_Accessor* eina_array_accessor_new | ( | const Eina_Array * | array | ) |
Returned a new accessor associated to an array.
array | The array. |
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 Otherwise, a valid accessor is returned.
References EINA_MAGIC_SET, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, and FUNC_ACCESSOR_GET_CONTAINER.
|
inlinestatic |
Provide a safe way to iterate over an array.
array | The array to iterate over. |
cb | The callback to call for each item. |
fdata | The user data to pass to the callback. |
This function provide a safe way to iterate over an array. cb
should return EINA_TRUE as long as you want the function to continue iterating, by returning EINA_FALSE it will stop and return EINA_FALSE as a result.