Array

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files
- Examples

Data Structures | Macros | Typedefs | Functions
Array
Eina » Data Types » Containers

These functions provide array management. More...

## Data Structures
struct | _Eina_Array
| Type for an array of data. 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
| Type for a generic vector.
typedef void ** | Eina_Array_Iterator
| Type for an iterator on arrays, used with EINA_ARRAY_ITER_NEXT.

## 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
| Append a data to an array. More...
EAPI Eina_Bool static Eina_Bool static void * | eina_array_pop (Eina_Array *array) EINA_ARG_NONNULL(1)
| Remove the last data of an array. More...
static void * | eina_array_data_get (const Eina_Array *array, unsigned int idx) EINA_ARG_NONNULL(1)
| Return the data at a given position in an array. More...
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
| Return the number of elements in an array. More...
static unsigned int | eina_array_count (const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT
| Return the number of elements in an array. More...
EAPI Eina_Iterator * | eina_array_iterator_new (const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT
| Get 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
| Get 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...

## Detailed Description

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` additonal 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 only stores pointers but it can store data of any type in the form of void pointers.

See here some examples:

- Basic array usage
- Removing array elements

## Macro Definition 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))
eina_array_count
static unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT
Return the number of elements in an array.

Macro to iterate over an array easily.

Parameters

  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:

1 Eina_Array *array;
2 char *item;
3 Eina_Array_Iterator iterator;
4 unsigned int i;
5
6 // array is already filled,
7 // its elements are just duplicated strings,
8 // EINA_ARRAY_ITER_NEXT will be used to free those strings
9
10 EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
11 free(item);

Examples:
  eina_array_02.c.

Referenced by eina_benchmark_free(), eina_module_find(), eina_module_list_free(), eina_module_list_load(), and eina_module_list_unload().

## Function Documentation

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 by `step` elements again.

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

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

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.

Parameters

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

References eina_array_flush().

Referenced by ecore_buffer_shutdown(), and eina_benchmark_free().

EAPI void eina_array_step_set | ( | Eina_Array * | array,
|  | unsigned int | sizeof_eina_array,
|  | unsigned int | step
| ) |  |

Set the step of an array.

Parameters

  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.

Warning
  This function can only be called on uninitialized arrays.

References _Eina_Array::count, _Eina_Array::data, EINA_MAGIC_SET, ERR, _Eina_Array::step, _Eina_Array::total, and _Eina_Array::version.

static void eina_array_clean | ( | Eina_Array * | array | ) |
| inlinestatic

Clean an array.

Parameters

  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.

Examples:
  eina_array_02.c.

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 efl::eina::ptr_array< Eo, std::conditional< std::is_same< CloneAllocator, default_clone_allocator_placeholder >::value, eo_clone_allocator, CloneAllocator >::type >::clear(), 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.

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 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.

Examples:
  eina_array_02.c.

EAPI Eina_Bool static Eina_Bool eina_array_push | ( | Eina_Array * | array,
|  | const void * | data
| ) |  |
| inlinestatic

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 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.

Referenced by eina_benchmark_run(), eina_file_split(), eldbus_service_property_changed(), evas_device_push(), efl::eina::ptr_array< Eo, std::conditional< std::is_same< CloneAllocator, default_clone_allocator_placeholder >::value, eo_clone_allocator, CloneAllocator >::type >::insert(), and efl::eina::ptr_array< Eo, std::conditional< std::is_same< CloneAllocator, default_clone_allocator_placeholder >::value, eo_clone_allocator, CloneAllocator >::type >::push_back().

EAPI Eina_Bool static Eina_Bool static void* eina_array_pop | ( | Eina_Array * | array | ) |
| inlinestatic

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.

Examples:
  eina_array_01.c.

Referenced by efl::eina::ptr_array< Eo, std::conditional< std::is_same< CloneAllocator, default_clone_allocator_placeholder >::value, eo_clone_allocator, CloneAllocator >::type >::erase(), evas_device_pop(), and efl::eina::ptr_array< Eo, std::conditional< std::is_same< CloneAllocator, default_clone_allocator_placeholder >::value, eo_clone_allocator, CloneAllocator >::type >::pop_back().

static void* eina_array_data_get | ( | const Eina_Array * | array,
|  | unsigned int | idx
| ) |  |
| inlinestatic

Return the data at a given position in an array.

Parameters

  array | The array.
  idx | The potition 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.

Referenced by eldbus_service_signal_emit().

static void eina_array_data_set | ( | const Eina_Array * | array,
|  | unsigned int | idx,
|  | const void * | data
| ) |  |
| inlinestatic

Set the data at a given position in an array.

Parameters

  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.

Examples:
  eina_array_02.c.

static unsigned int eina_array_count_get | ( | const Eina_Array * | array | ) |
| inlinestatic

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` (array->count). For performance reasons, there is no check of `array`. If it is `NULL` or invalid, the program may crash.

Deprecated:
  use eina_array_count()

static unsigned int eina_array_count | ( | const Eina_Array * | array | ) |
| inlinestatic

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` (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.

Referenced by ecore_buffer_init(), eldbus_service_signal_emit(), eldbus_service_signal_new(), and efl::eina::ptr_array< Eo, std::conditional< std::is_same< CloneAllocator, default_clone_allocator_placeholder >::value, eo_clone_allocator, CloneAllocator >::type >::size().

EAPI Eina_Iterator* eina_array_iterator_new | ( | const Eina_Array * | array | ) |

Get a new iterator associated 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. Otherwise, a valid iterator is returned.

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, FUNC_ITERATOR_NEXT, and _Eina_Array::version.

EAPI Eina_Accessor* eina_array_accessor_new | ( | const Eina_Array * | array | ) |

Get a new accessor associated 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. Otherwise, a valid accessor is returned.

References EINA_MAGIC_SET, FUNC_ACCESSOR_CLONE, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, FUNC_ACCESSOR_GET_CONTAINER, and _Eina_Array::version.

Referenced by efl::eina::ptr_array< Eo, std::conditional< std::is_same< CloneAllocator, default_clone_allocator_placeholder >::value, eo_clone_allocator, CloneAllocator >::type >::accessor().

static Eina_Bool eina_array_foreach | ( | Eina_Array * | array,
|  | Eina_Each_Cb | cb,
|  | void * | fdata
| ) |  |
| inlinestatic

Provide a safe way to iterate over an array.

Parameters

  array | The array to iterate over.
  cb | The callback to call for each item.
  fdata | The 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.