Tizen Native API  3.0

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 position, 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 frees the memory used by the Eina_Array itself, but does not free any memory used to store the data of each element. To free that memory you must iterate over the array and free each data element individually. A convenient way to do that is by using EINA_ARRAY_ITER_NEXT. An example of that pattern is given in the description of EINA_ARRAY_ITER_NEXT.

Warning:
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 that when you remove an element from an array it may shrink.

Allocating memory is expensive, so when the array needs to grow it allocates enough memory to hold step additional elements, not just the element currently being added. Similarly if you remove elements, it won't free space until you have removed step elements.

The following image illustrates how an Eina_Array grows:

eina_array-growth.png

Eina_Array only stores pointers but it can store data of any type in the form of void pointers.

See here some examples:

Functions

Eina_Arrayeina_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) 2)
 Rebuilds an array by specifying the data to keep.
static Eina_Bool eina_array_push (Eina_Array *array, const void *data) 2)
 Appends a data to an array.
static void * eina_array_pop (Eina_Array *array)
 Removes the last data of an array.
static void * eina_array_data_get (const Eina_Array *array, unsigned int idx)
 Returns the data at a 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 a given position in an array.
static unsigned int eina_array_count_get (const Eina_Array *array)
 Returns the number of elements in an array.
static unsigned int eina_array_count (const Eina_Array *array)
 Returns the number of elements in an array.
Eina_Iteratoreina_array_iterator_new (const Eina_Array *array)
 Gets a new iterator associated to an array.
Eina_Accessoreina_array_accessor_new (const Eina_Array *array)
 Gets 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
typedef void ** Eina_Array_Iterator

Defines

#define EINA_ARRAY_ITER_NEXT(array, index, item, iterator)
 Definition for the macro to iterate over an array easily.

Define Documentation

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

Definition for the macro to iterate over an array easily.

Parameters:
arrayThe array to iterate over.
indexThe integer number that is increased while iterating.
itemThe data
iteratorThe 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:

 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);
Examples:
eina_array_02.c.

Typedef Documentation

Type for a generic vector.

Type for an iterator on arrays, used with EINA_ARRAY_ITER_NEXT.


Function Documentation

Gets a new accessor associated to an array.

Parameters:
arrayThe 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. Otherwise, a valid accessor is returned.

Since :
2.3.1
Examples:
eina_accessor_01.c.
static void eina_array_clean ( Eina_Array array) [static]

Cleans an array.

Parameters:
arrayThe 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.

Examples:
eina_array_02.c.
static unsigned int eina_array_count ( const Eina_Array array) [static]

Returns the number of elements in an array.

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

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.

Examples:
eina_array_01.c.
static unsigned int eina_array_count_get ( const Eina_Array array) [static]

Returns the number of elements in an array.

Deprecated:
use eina_array_count()
Parameters:
arrayThe array.
Returns:
The number of elements.

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.

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

Returns the data at a given position in an array.

Parameters:
arrayThe array.
idxThe position of the data to retrieve.
Returns:
The retrieved data.

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

Examples:
eina_array_01.c.
static void eina_array_data_set ( const Eina_Array array,
unsigned int  idx,
const void *  data 
) [static]

Sets the data at a given position in an array.

Parameters:
arrayThe array.
idxThe position of the data to set.
dataThe 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.

Examples:
eina_array_02.c.
void eina_array_flush ( Eina_Array array)

Flushes an array.

Parameters:
arrayThe 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.

Since :
2.3.1
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.

Parameters:
arrayThe array to iterate over.
cbThe callback to call for each item.
fdataThe user data to pass to the callback.
Returns:
EINA_TRUE if it successfully iterate all items of the 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. If cb returns EINA_FALSE, iterations will stop and the function will also return EINA_FALSE.

Examples:
eina_array_01.c, and eina_simple_xml_parser_01.c.
void eina_array_free ( Eina_Array array)

Frees an array.

Parameters:
arrayThe 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, walk the array with EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check of array.

Since :
2.3.1
Examples:
eina_accessor_01.c, eina_array_01.c, eina_array_02.c, eina_iterator_01.c, and eina_simple_xml_parser_01.c.

Gets a new iterator associated to an array.

Parameters:
arrayThe 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. Otherwise, a valid iterator is returned.

Since :
2.3.1
Examples:
eina_iterator_01.c.
Eina_Array* eina_array_new ( unsigned int  step)

Creates a new array.

Parameters:
stepThe 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 by step elements again.

This function return a valid array on success, or NULL if memory allocation fails.

Since :
2.3.1
Examples:
eina_accessor_01.c, eina_array_01.c, eina_array_02.c, eina_iterator_01.c, and eina_simple_xml_parser_01.c.
static void* eina_array_pop ( Eina_Array array) [static]

Removes the last data of an array.

Parameters:
arrayThe 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.

Examples:
eina_array_01.c.
static Eina_Bool eina_array_push ( Eina_Array array,
const void *  data 
) [static]

Appends a data to an array.

Parameters:
arrayThe array.
dataThe 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 Otherwise, EINA_TRUE is returned.

Examples:
eina_accessor_01.c, eina_array_01.c, eina_array_02.c, eina_iterator_01.c, and eina_simple_xml_parser_01.c.
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.

Parameters:
arrayThe array.
keepThe functions which selects the data to keep.
gdataThe data to pass to the function keep.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

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.

Since :
2.3.1
Examples:
eina_array_02.c.
void eina_array_step_set ( Eina_Array array,
unsigned int  sizeof_eina_array,
unsigned int  step 
)

Sets the step of an array.

Parameters:
arrayThe array.
sizeof_eina_arrayShould be the value returned by sizeof(Eina_Array).
stepThe 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.

Warning:
This function can only be called on uninitialized arrays.
Since :
2.3.1
Examples:
eina_array_01.c.