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

Data Structures | Macros | Typedefs | Functions
Inline Array
Containers

Inline array is a container that stores the data itself not pointers to data, this means there is no memory fragmentation, also for small data types(such as char, short, int, etc.) it's more memory efficient. More...

## Data Structures
struct | _Eina_Inarray
| Inline array structure, use Eina_Inarray typedef instead. More...

## Macros
#define | EINA_INARRAY_FOREACH(array, itr)
| walks array linearly from head to tail More...
#define | EINA_INARRAY_REVERSE_FOREACH(array, itr)
| walks array linearly from tail to head More...

## Typedefs
typedef struct _Eina_Inarray | Eina_Inarray
| Inlined array type. More...

## Functions
Eina_Inarray * | eina_inarray_new (unsigned int member_size, unsigned int step)
| Create new inline array. More...
void | eina_inarray_free (Eina_Inarray *array)
| Free array and its members. More...
void | eina_inarray_step_set (Eina_Inarray *array, unsigned int sizeof_eina_inarray, unsigned int member_size, unsigned int step)
| Initialize inline array. More...
void | eina_inarray_flush (Eina_Inarray *array)
| Remove every member from array. More...
int | eina_inarray_push (Eina_Inarray *array, const void *data)
| Copy the data as the last member of the array. More...
void * | eina_inarray_grow (Eina_Inarray *array, unsigned int size)
| Allocate new item at the end of the array. More...
int | eina_inarray_insert (Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Copy the data to array at position found by comparison function. More...
int | eina_inarray_insert_sorted (Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Copy the data to array at position found by comparison function. More...
int | eina_inarray_remove (Eina_Inarray *array, const void *data)
| Find data and remove matching member. More...
void * | eina_inarray_pop (Eina_Inarray *array)
| Removes the last member of the array. More...
void * | eina_inarray_nth (const Eina_Inarray *array, unsigned int position)
| Get the member at given position. More...
Eina_Bool | eina_inarray_insert_at (Eina_Inarray *array, unsigned int position, const void *data)
| Copy the data at given position in the array. More...
void * | eina_inarray_alloc_at (Eina_Inarray *array, unsigned int position, unsigned int member_count)
| Opens a space at given position, returning its pointer. More...
Eina_Bool | eina_inarray_replace_at (Eina_Inarray *array, unsigned int position, const void *data)
| Copy the data over the given position. More...
Eina_Bool | eina_inarray_remove_at (Eina_Inarray *array, unsigned int position)
| Remove member at given position. More...
void | eina_inarray_reverse (Eina_Inarray *array)
| Reverse members in the array. More...
void | eina_inarray_sort (Eina_Inarray *array, Eina_Compare_Cb compare)
| Applies quick sort to array. More...
int | eina_inarray_search (const Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Search member (linear walk) More...
int | eina_inarray_search_sorted (const Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Search member (binary search walk) More...
Eina_Bool | eina_inarray_foreach (const Eina_Inarray *array, Eina_Each_Cb function, const void *user_data)
| Call function for each array member. More...
int | eina_inarray_foreach_remove (Eina_Inarray *array, Eina_Each_Cb match, const void *user_data)
| Remove all members that matched. More...
unsigned int | eina_inarray_count (const Eina_Inarray *array)
| number of members in array. More...
Eina_Iterator * | eina_inarray_iterator_new (const Eina_Inarray *array)
| Returned a new iterator associated to an array. More...
Eina_Iterator * | eina_inarray_iterator_reversed_new (const Eina_Inarray *array)
| Returned a new reversed iterator associated to an array. More...
Eina_Accessor * | eina_inarray_accessor_new (const Eina_Inarray *array)
| Returned a new accessor associated to an array. More...

## Detailed Description

Inline array is a container that stores the data itself not pointers to data, this means there is no memory fragmentation, also for small data types(such as char, short, int, etc.) it's more memory efficient.

Usage of the inline array is very similar to that of other Containers, like all arrays adding elements to the beginning of the array is a lot more costly than appending, so those operations should be minimized.

Examples:

- Eina inline array usage
- Eina inline array of strings

## Macro Definition Documentation

#define EINA_INARRAY_FOREACH | ( |  | array,
|  |  | itr
| ) |  |

Value:
for ((itr) = (array)->members; \
(itr) < (((__typeof__(*itr)*)(array)->members) + (array)->len); \
(itr)++)

walks array linearly from head to tail

Parameters

  array | array object
  itr | the iterator pointer

itr must be a pointer with sizeof(itr*) == array->member_size.

Warning
  This is fast as it does direct pointer access, but it will not check for `NULL` pointers or invalid array object! See eina_inarray_foreach() to do that.
  Do not modify array as you walk it! If that is desired, then use eina_inarray_foreach_remove()

Since
  1.2

Examples:
  eina_inarray_01.c, and eina_inarray_02.c.

#define EINA_INARRAY_REVERSE_FOREACH | ( |  | array,
|  |  | itr
| ) |  |

Value:
for ((itr) = ((((__typeof__(*(itr))*)(array)->members) + (array)->len) - 1); \
(((itr) >= (__typeof__(*(itr))*)(array)->members) \
&& ((array)->members != NULL)); \
(itr)--)

walks array linearly from tail to head

Parameters

  array | array object
  itr | the iterator pointer

itr must be a pointer with sizeof(itr*) == array->member_size.

Warning
  This is fast as it does direct pointer access, but it will not check for `NULL` pointers or invalid array object!
  Do not modify array as you walk it! If that is desired, then use eina_inarray_foreach_remove()

Since
  1.2

## Typedef Documentation

Eina_Inarray

Inlined array type.

Since
  1.2

## Function Documentation

Eina_Inarray* eina_inarray_new | ( | unsigned int | member_size,
|  | unsigned int | step
| ) |  |

Create new inline array.

Parameters

  member_size | size of each member in the array.
  step | when resizing the array, do this using the following extra amount.

Returns
  The new inline array table or `NULL` on failure.

Create a new array where members are inlined in a sequence. Each member has member_size bytes.

If the step is 0, then a safe default is chosen.

On failure, `NULL` is returned. If member_size is zero, then `NULL` is returned.

See Also
  eina_inarray_free()

Since
  1.2

void eina_inarray_free | ( | Eina_Inarray * | array | ) |

Free array and its members.

Parameters

  array | array object

See Also
  eina_inarray_flush()

Since
  1.2

References _Eina_Inarray::members.

void eina_inarray_step_set | ( | Eina_Inarray * | array,
|  | unsigned int | sizeof_eina_inarray,
|  | unsigned int | member_size,
|  | unsigned int | step
| ) |  |

Initialize inline array.

Parameters

  array | array object to initialize.
  member_size | size of each member in the array.
  step | when resizing the array, do this using the following extra amount.

Initialize array. If the step is `0`, then a safe default is chosen.

This is useful for arrays inlined into other structures or allocated at stack.

See Also
  eina_inarray_flush()

Since
  1.2

void eina_inarray_flush | ( | Eina_Inarray * | array | ) |

Remove every member from array.

Parameters

  array | array object

Since
  1.2

References _Eina_Inarray::len, _Eina_Inarray::max, and _Eina_Inarray::members.

int eina_inarray_push | ( | Eina_Inarray * | array,
|  | const void * | data
| ) |  |

Copy the data as the last member of the array.

Parameters

  array | array object
  data | data to be copied at the end

Returns
  the index of the new member or -1 on errors.

Copies the given pointer contents at the end of the array. The pointer is not referenced, instead it's contents is copied to the members array using the previously defined `member_size`.

See Also
  eina_inarray_insert_at().

Since
  1.2

References _Eina_Inarray::len, and _Eina_Inarray::member_size.

Referenced by eina_inarray_insert().

void* eina_inarray_grow | ( | Eina_Inarray * | array,
|  | unsigned int | size
| ) |  |

Allocate new item at the end of the array.

Parameters

  array | array object
  size | number of new item to allocate

The returned pointer is only valid until you use any other eina_inarray function.

Since
  1.8

References _Eina_Inarray::len.

Referenced by evas_async_events_put().

int eina_inarray_insert | ( | Eina_Inarray * | array,
|  | const void * | data,
|  | Eina_Compare_Cb | compare
| ) |  |

Copy the data to array at position found by comparison function.

Parameters

  array | array object
  data | data to be copied
  compare | compare function

Returns
  the index of the new member or `-1` on errors.

Copies the given pointer contents at the array position defined by given compare function. The pointer is not referenced, instead it's contents is copied to the members array using the previously defined `member_size`.

The data given to compare function are the pointer to member memory itself, do no change it.

See Also
  eina_inarray_insert_sorted()
  eina_inarray_insert_at()
  eina_inarray_push()

Since
  1.2

References eina_inarray_insert_at(), eina_inarray_push(), _Eina_Inarray::len, _Eina_Inarray::member_size, and _Eina_Inarray::members.

int eina_inarray_insert_sorted | ( | Eina_Inarray * | array,
|  | const void * | data,
|  | Eina_Compare_Cb | compare
| ) |  |

Copy the data to array at position found by comparison function.

Parameters

  array | array object
  data | data to be copied
  compare | compare function

Returns
  the index of the new member or `-1` on errors.

Copies the given pointer contents at the array position defined by given compare function. The pointer is not referenced, instead it's contents is copied to the members array using the previously defined `member_size`.

The data given to compare function are the pointer to member memory itself, do no change it.

This variation will optimize insertion position assuming the array is already sorted by doing binary search.

See Also
  eina_inarray_sort()

Since
  1.2

References eina_inarray_insert_at().

int eina_inarray_remove | ( | Eina_Inarray * | array,
|  | const void * | data
| ) |  |

Find data and remove matching member.

Parameters

  array | array object
  data | data to be found and removed

Returns
  the index of the removed member or `-1` on errors.

Find data in the array and remove it. Data may be an existing member of array (then optimized) or the contents will be matched using memcmp().

See Also
  eina_inarray_pop()
  eina_inarray_remove_at()

Since
  1.2

References eina_inarray_remove_at(), _Eina_Inarray::len, _Eina_Inarray::member_size, and _Eina_Inarray::members.

void* eina_inarray_pop | ( | Eina_Inarray * | array | ) |

Removes the last member of the array.

Parameters

  array | array object

Returns
  the data poped out of the array.

Note: The data could be considered valid only until any other operation touch the Inarray.

Since
  1.2

References _Eina_Inarray::len.

void* eina_inarray_nth | ( | const Eina_Inarray * | array,
|  | unsigned int | position
| ) |  |

Get the member at given position.

Parameters

  array | array object
  position | member position

Returns
  pointer to current member memory.

Gets the member given its position in the array. It is a pointer to its current memory, then it can be invalidated with functions that changes the array such as eina_inarray_push(), eina_inarray_insert_at() or eina_inarray_remove_at() or variants.

See also eina_inarray_lookup() and eina_inarray_lookup_sorted().

Since
  1.2

References _Eina_Inarray::len.

Eina_Bool eina_inarray_insert_at | ( | Eina_Inarray * | array,
|  | unsigned int | position,
|  | const void * | data
| ) |  |

Copy the data at given position in the array.

Parameters

  array | array object
  position | where to insert the member
  data | data to be copied at position

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

Copies the given pointer contents at the given position in the array. The pointer is not referenced, instead it's contents is copied to the members array using the previously defined `member_size`.

All the members from position to the end of the array are shifted to the end.

If position is equal to the end of the array (equals to eina_inarray_count()), then the member is appended.

If position is bigger than the array length, it will fail.

Since
  1.2

References EINA_FALSE, EINA_TRUE, _Eina_Inarray::len, and _Eina_Inarray::member_size.

Referenced by eina_inarray_insert(), and eina_inarray_insert_sorted().

void* eina_inarray_alloc_at | ( | Eina_Inarray * | array,
|  | unsigned int | position,
|  | unsigned int | member_count
| ) |  |

Opens a space at given position, returning its pointer.

Parameters

  array | array object
  position | where to insert first member (open/allocate space)
  member_count | how many times member_size bytes will be allocated.

Returns
  pointer to first member memory allocated or `NULL` on errors.

This is similar to eina_inarray_insert_at(), but useful if the members contents are still unknown or unallocated. It will make room for the required number of items and return the pointer to the first item, similar to malloc(member_count * member_size), with the guarantee all memory is within members array.

The new member memory is undefined, it's not automatically zeroed.

All the members from position to the end of the array are shifted to the end.

If position is equal to the end of the array (equals to eina_inarray_count()), then the member is appended.

If position is bigger than the array length, it will fail.

Since
  1.2

References _Eina_Inarray::len, and _Eina_Inarray::member_size.

Eina_Bool eina_inarray_replace_at | ( | Eina_Inarray * | array,
|  | unsigned int | position,
|  | const void * | data
| ) |  |

Copy the data over the given position.

Parameters

  array | array object
  position | where to replace the member
  data | data to be copied at position

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

Copies the given pointer contents at the given position in the array. The pointer is not referenced, instead it's contents is copied to the members array using the previously defined `member_size`.

If position does not exist, it will fail.

Since
  1.2

References EINA_FALSE, EINA_TRUE, _Eina_Inarray::len, and _Eina_Inarray::member_size.

Eina_Bool eina_inarray_remove_at | ( | Eina_Inarray * | array,
|  | unsigned int | position
| ) |  |

Remove member at given position.

Parameters

  array | array object
  position | position to be removed

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

The member is removed from array and any members after it are moved towards the array head.

See also eina_inarray_pop() and eina_inarray_remove().

Since
  1.2

References EINA_FALSE, EINA_TRUE, _Eina_Inarray::len, and _Eina_Inarray::member_size.

Referenced by eina_inarray_foreach_remove(), and eina_inarray_remove().

void eina_inarray_reverse | ( | Eina_Inarray * | array | ) |

Reverse members in the array.

Parameters

  array | array object

If you do not want to change the array, just walk its elements backwards, then use EINA_INARRAY_REVERSE_FOREACH() macro.

See Also
  EINA_INARRAY_REVERSE_FOREACH()

Since
  1.2

References _Eina_Inarray::len, _Eina_Inarray::member_size, and _Eina_Inarray::members.

void eina_inarray_sort | ( | Eina_Inarray * | array,
|  | Eina_Compare_Cb | compare
| ) |  |

Applies quick sort to array.

Parameters

  array | array object
  compare | compare function

Applies quick sort to the array.

The data given to compare function are the pointer to member memory itself, do no change it.

See Also
  eina_inarray_insert_sorted()

Since
  1.2

References _Eina_Inarray::len, _Eina_Inarray::member_size, and _Eina_Inarray::members.

int eina_inarray_search | ( | const Eina_Inarray * | array,
|  | const void * | data,
|  | Eina_Compare_Cb | compare
| ) |  |

Search member (linear walk)

Parameters

  array | array object
  data | member to search using compare function.
  compare | compare function

Returns
  the member index or -1 if not found.

Walks array linearly looking for given data as compared by compare function.

The data given to compare function are the pointer to member memory itself, do no change it.

See also eina_inarray_lookup_sorted().

Since
  1.2

int eina_inarray_search_sorted | ( | const Eina_Inarray * | array,
|  | const void * | data,
|  | Eina_Compare_Cb | compare
| ) |  |

Search member (binary search walk)

Parameters

  array | array object
  data | member to search using compare function.
  compare | compare function

Returns
  the member index or `-1` if not found.

Uses binary search for given data as compared by compare function.

The data given to compare function are the pointer to member memory itself, do no change it.

Since
  1.2

Eina_Bool eina_inarray_foreach | ( | const Eina_Inarray * | array,
|  | Eina_Each_Cb | function,
|  | const void * | user_data
| ) |  |

Call function for each array member.

Parameters

  array | array object
  function | callback function
  user_data | user data given to callback function

Returns
  EINA_TRUE if it successfully iterate all items of the array.

Call function for every given data in array.

Safe way to iterate over an array. `function` 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.

The data given to function are the pointer to member memory itself.

See Also
  EINA_INARRAY_FOREACH()

Since
  1.2

References EINA_FALSE, EINA_TRUE, _Eina_Inarray::len, _Eina_Inarray::member_size, and _Eina_Inarray::members.

int eina_inarray_foreach_remove | ( | Eina_Inarray * | array,
|  | Eina_Each_Cb | match,
|  | const void * | user_data
| ) |  |

Remove all members that matched.

Parameters

  array | array object
  match | match function
  user_data | user data given to callback match.

Returns
  number of removed entries or -1 on error.

Remove all entries in the array where match function returns EINA_TRUE.

Since
  1.2

References EINA_FALSE, and eina_inarray_remove_at().

unsigned int eina_inarray_count | ( | const Eina_Inarray * | array | ) |

number of members in array.

Parameters

  array | array object

Returns
  number of members in array.

Since
  1.2

References _Eina_Inarray::len.

Eina_Iterator* eina_inarray_iterator_new | ( | const Eina_Inarray * | array | ) |

Returned a new iterator associated to an array.

Parameters

  array | array object

Returns
  A new iterator.

This function returns a newly allocated iterator associated to `array`.

If the memory can not be allocated, `NULL` is returned. Otherwise, a valid iterator is returned.

Warning
  if the array structure changes then the iterator becomes invalid! That is, if you add or remove members this iterator behavior is undefined and your program may crash!

Since
  1.2

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

Eina_Iterator* eina_inarray_iterator_reversed_new | ( | const Eina_Inarray * | array | ) |

Returned a new reversed iterator associated to an array.

Parameters

  array | array object

Returns
  A new iterator.

This function returns a newly allocated iterator associated to `array`.

Unlike eina_inarray_iterator_new(), this will walk the array backwards.

If the memory can not be allocated, `NULL` is returned Otherwise, a valid iterator is returned.

Warning
  if the array structure changes then the iterator becomes invalid! That is, if you add or remove nodes this iterator behavior is undefined and your program may crash!

Since
  1.2

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, FUNC_ITERATOR_NEXT, and _Eina_Inarray::len.

Eina_Accessor* eina_inarray_accessor_new | ( | const Eina_Inarray * | array | ) |

Returned a new accessor associated to an array.

Parameters

  array | array object

Returns
  A new accessor.

This function returns a newly allocated accessor associated to `array`.

If the memory can not be allocated, `NULL` is returned. Otherwise, a valid accessor is returned.

Since
  1.2

References EINA_MAGIC_SET, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, FUNC_ACCESSOR_GET_CONTAINER, and _Eina_Inarray::version.