Tizen Native API
|
Functions | |
Eina_Array * | eina_array_new (unsigned int step) |
Creates a new array. | |
void | eina_array_free (Eina_Array *array) |
Frees an array. | |
void | eina_array_step_set (Eina_Array *array, unsigned int sizeof_eina_array, unsigned int step) |
Sets the step of an array. | |
static void | eina_array_clean (Eina_Array *array) |
Cleans an array. | |
void | eina_array_flush (Eina_Array *array) |
Flushes an array. | |
Eina_Bool | eina_array_remove (Eina_Array *array, Eina_Bool(*keep)(void *data, void *gdata), void *gdata) |
Rebuilds an array by specifying the data to keep. | |
static Eina_Bool | eina_array_push (Eina_Array *array, const void *data) |
Append a data to an array. | |
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 idx) |
Sets the data at the given position in an array. | |
static void | eina_array_data_set (const Eina_Array *array, unsigned int idx, const void *data) |
Sets the data at the given position in an array. | |
static unsigned int | eina_array_count_get (const Eina_Array *array) |
Return the number of elements in an array. | |
static unsigned int | eina_array_count (const Eina_Array *array) |
Return the number of elements in an array. | |
Eina_Iterator * | eina_array_iterator_new (const Eina_Array *array) |
Returns a new iterator associated to an array. | |
Eina_Accessor * | eina_array_accessor_new (const Eina_Array *array) |
Returns a new accessor associated to an array. | |
static Eina_Bool | eina_array_foreach (Eina_Array *array, Eina_Each_Cb cb, void *fdata) |
Provides a safe way to iterate over an array. | |
Typedefs | |
typedef struct _Eina_Array | Eina_Array |
The structure type for a generic vector. | |
typedef void ** | Eina_Array_Iterator |
The structure type for an iterator on arrays, used with EINA_ARRAY_ITER_NEXT. | |
Defines | |
#define | EINA_ARRAY_ITER_NEXT(array, index, item, iterator) |
Definition of the macro to iterate over an array easily. |
This group discusses the functions to 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 function. 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.
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 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 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 the array is left holding its capacity, step elements shrink.
The following image illustrates how an Eina_Array grows:
#define EINA_ARRAY_ITER_NEXT | ( | array, | |
index, | |||
item, | |||
iterator | |||
) |
for (index = 0, iterator = (array)->data; \ (index < eina_array_count(array)) && ((item = *((iterator)++))); \ ++(index))
Definition of the macro to iterate over an array easily.
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.
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);
array | The array to iterate over |
index | The integer number that is increased while iterating |
item | The data |
iterator | The iterator |
Eina_Accessor* eina_array_accessor_new | ( | const Eina_Array * | array | ) |
Returns a new accessor associated to an array.
This function returns a newly allocated accessor associated to array. If array is NULL
or the count member of array is less than or equal to 0
, this function returns NULL
. If the memory cannot be allocated, NULL
is returned and EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid accessor is returned.
[in] | array | The array |
static void eina_array_clean | ( | Eina_Array * | array | ) | [static] |
Cleans an array.
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 on array. If it is NULL
or invalid, the program may crash.
[in] | array | The array to clean |
static unsigned int eina_array_count | ( | const Eina_Array * | array | ) | [static] |
Return the number of elements in an array.
This function returns the number of elements in array
(array->count). For performance reasons, there is no check of array
. If it is NULL
or invalid, the program may crash.
[in] | array | The array. |
static unsigned int eina_array_count_get | ( | const Eina_Array * | array | ) | [static] |
Return the number of elements in an array.
This function returns the number of elements in array
(array->count). For performance reasons, there is no check of array
. If it is NULL
or invalid, the program may crash.
[in] | array | The array. |
static void* eina_array_data_get | ( | const Eina_Array * | array, |
unsigned int | idx | ||
) | [static] |
Sets the data at the given position in an array.
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 on array or idx. If it is NULL
or invalid, the program may crash.
[in] | array | The array |
[in] | idx | The position of the data to set |
static void eina_array_data_set | ( | const Eina_Array * | array, |
unsigned int | idx, | ||
const void * | data | ||
) | [static] |
Sets the data at the given position in an array.
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 on array or idx. If it is NULL
or invalid, the program may crash.
[in] | array | The array |
[in] | idx | The position of the data to set |
[in] | data | The data to set |
void eina_array_flush | ( | Eina_Array * | array | ) |
Flushes an array.
This function sets the count and total members of array to 0, frees and sets its data member to NULL
. For performance reasons, there is no check on array. If it is NULL
or invalid, the program may crash.
[in] | array | The array to flush |
static Eina_Bool eina_array_foreach | ( | Eina_Array * | array, |
Eina_Each_Cb | cb, | ||
void * | fdata | ||
) | [static] |
Provides a safe way to iterate over an array.
This function provides 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 stops and returns EINA_FALSE
as a result.
[in] | array | The array to iterate over |
[in] | cb | The callback to call for each item |
[in] | fdata | The user data to pass to the callback |
EINA_TRUE
if it successfully iterates all the items of the array, otherwise EINA_FALSE
void eina_array_free | ( | Eina_Array * | array | ) |
Frees an array.
This function frees array. It calls first eina_array_flush() then frees 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 on array.
[in] | array | The array to free |
Eina_Iterator* eina_array_iterator_new | ( | const Eina_Array * | array | ) |
Returns a new iterator associated to an array.
This function returns a newly allocated iterator associated to array. If array is NULL
or the count member of array is less than or equal to 0, this function returns NULL
. If the memory cannot be allocated, NULL
is returned and EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is returned.
[in] | array | The array |
Eina_Array* eina_array_new | ( | unsigned int | step | ) |
Creates a new array.
This function creates a new array. When adding an element, the array allocates step elements. When that buffer is full, adding another element increases the buffer by step elements again.
NULL
if memory allocation fails. In that case, the error is set to EINA_ERROR_OUT_OF_MEMORY.[in] | step | The count of pointers to add when increasing the array size |
NULL
on failure, otherwise a non NULL
value static void* eina_array_pop | ( | Eina_Array * | array | ) | [static] |
Remove the last data of an array.
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.
[in] | array | The array. |
static Eina_Bool eina_array_push | ( | Eina_Array * | array, |
const void * | data | ||
) | [static] |
Append a data to an array.
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 Otherwise, EINA_TRUE is returned.
[in] | array | The array. |
[in] | data | The data to add. |
Eina_Bool eina_array_remove | ( | Eina_Array * | array, |
Eina_Bool(*)(void *data, void *gdata) | keep, | ||
void * | gdata | ||
) |
Rebuilds an array by specifying the data to keep.
This function rebuilds array by 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 on array. If it is NULL
or invalid, the program may crash.
EINA_FALSE
and the error is set to EINA_ERROR_OUT_OF_MEMORY.[in] | array | The array |
[in] | keep | The functions that selects the data to keep |
[in] | gdata | The data to pass to the function keep |
EINA_TRUE
on success, otherwise EINA_FALSE
void eina_array_step_set | ( | Eina_Array * | array, |
unsigned int | sizeof_eina_array, | ||
unsigned int | step | ||
) |
Sets the step of an array.
This function sets the step of array to step. For performance reasons, there is no check on array. If it is NULL
or invalid, the program may crash.
[in] | array | The array |
[in] | sizeof_eina_array | The value returned by sizeof(Eina_Array) |
[in] | step | The count of pointers to add when increasing the array size |