Inline Array
Eina » Data Types » Containers

Inline array is a container that stores the data itself, not the pointers to the data. More...

## Data Structures

struct | _Eina_Inarray
| Inline array structure. More...

## Macros

#define | EINA_INARRAY_FOREACH(array, itr)
| Walks through an array linearly from head to tail.
#define | EINA_INARRAY_REVERSE_FOREACH(array, itr)
| Walks through an array linearly from tail to head.

## Typedefs

typedef struct _Eina_Inarray | Eina_Inarray
| Type for the inlined array.

## Functions

EINA_API Eina_Inarray * | eina_inarray_new (unsigned int member_size, unsigned int step)
| Creates a new inline array.
EINA_API void | eina_inarray_free (Eina_Inarray *array)
| Frees an array and its members.
EINA_API void | eina_inarray_step_set (Eina_Inarray *array, unsigned int sizeof_eina_inarray, unsigned int member_size, unsigned int step)
| Initializes an inline array.
EINA_API void | eina_inarray_flush (Eina_Inarray *array)
| Removes every member from the array.
EINA_API int | eina_inarray_push (Eina_Inarray *array, const void *data)
| Copies the data as the last member of the array.
EINA_API void * | eina_inarray_grow (Eina_Inarray *array, unsigned int size)
| Allocates new item at the end of the array.
EINA_API int | eina_inarray_insert (Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Copies the data to the array at a position found by the comparison function.
EINA_API int | eina_inarray_insert_sorted (Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Copies the data to the array at a position found by the comparison function.
EINA_API int | eina_inarray_remove (Eina_Inarray *array, const void *data)
| Finds data and removes the matching member.
EINA_API void * | eina_inarray_pop (Eina_Inarray *array)
| Removes the last member of the array.
EINA_API void * | eina_inarray_nth (const Eina_Inarray *array, unsigned int position)
| Gets the member at the given position.
EINA_API Eina_Bool | eina_inarray_insert_at (Eina_Inarray *array, unsigned int position, const void *data)
| Copies the data at the given position in the array.
EINA_API void * | eina_inarray_alloc_at (Eina_Inarray *array, unsigned int position, unsigned int member_count)
| Opens a space at the given position, returning its pointer.
EINA_API Eina_Bool | eina_inarray_replace_at (Eina_Inarray *array, unsigned int position, const void *data)
| Copies the data to the given position.
EINA_API Eina_Bool | eina_inarray_remove_at (Eina_Inarray *array, unsigned int position)
| Removes a member from the given position.
EINA_API void | eina_inarray_reverse (Eina_Inarray *array)
| Reverses members in the array.
EINA_API void | eina_inarray_sort (Eina_Inarray *array, Eina_Compare_Cb compare)
| Applies a quick sort to the array.
EINA_API int | eina_inarray_search (const Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Searches for a member (linear walk).
EINA_API int | eina_inarray_search_sorted (const Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
| Searches for member (binary search walk).
EINA_API Eina_Bool | eina_inarray_foreach (const Eina_Inarray *array, Eina_Each_Cb function, const void *user_data)
| Calls `function` for each array member.
EINA_API int | eina_inarray_foreach_remove (Eina_Inarray *array, Eina_Each_Cb match, const void *user_data)
| Removes all the members that match.
EINA_API Eina_Bool | eina_inarray_resize (Eina_Inarray *array, unsigned int new_size)
| Resizes array to new size.
EINA_API unsigned int | eina_inarray_count (const Eina_Inarray *array)
| Counts the number of members in an array.
EINA_API Eina_Iterator * | eina_inarray_iterator_new (const Eina_Inarray *array)
| Returns a new iterator associated to an array.
EINA_API Eina_Iterator * | eina_inarray_iterator_reversed_new (const Eina_Inarray *array)
| Returns a new reversed iterator associated to an array.
EINA_API Eina_Accessor * | eina_inarray_accessor_new (const Eina_Inarray *array)
| Returns a new accessor associated to an array.

## Detailed Description

Inline array is a container that stores the data itself, not the pointers to the data.

Since
  1.2

This means there is no memory fragmentation, also for small data types (such as char, short, int, and so on) 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

## EINA_INARRAY_FOREACH

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

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

Walks through an array linearly from head to tail.

Parameters

  [in] | array | The array object
  [in] | itr | An iterator pointer

Note
  `itr` must be a pointer with sizeof(itr*) == array->member_size.
  This is fast as it does direct pointer access, but it does not check for `NULL` pointers or invalid array objects. Use eina_inarray_foreach() to do that.
  Do not modify an array as you walk through it. If that is desired, then use eina_inarray_foreach_remove().

Since
  1.2

Examples
  eina_inarray_01.c, eina_inarray_02.c, and eina_inarray_03.c.

## EINA_INARRAY_REVERSE_FOREACH

#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 through an array linearly from tail to head.

Parameters

  [in] | array | The array object
  [in] | itr | An iterator pointer

Note
  `itr` must be a pointer with sizeof(itr*) == array->member_size.
  This is fast as it does direct pointer access, but it does not check for `NULL` pointers or invalid array objects.
  Do not modify an array as you walk through it. If that is desired, then use eina_inarray_foreach_remove().

Since
  1.2

## Typedef Documentation

## Eina_Inarray

typedef struct _Eina_Inarray Eina_Inarray

Type for the inlined array.

Since
  1.2

Examples
  eina_inarray_01.c, eina_inarray_02.c, and eina_inarray_03.c.

## Function Documentation

## eina_inarray_new()

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

Creates a new inline array.

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

Parameters

  [in] | member_size | The size of each member in the array
  [in] | step | The step size by which to resize the array, do this using the following extra amount

Returns
  The new inline array table, otherwise `NULL` on failure

Note
  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

References EINA_SAFETY_ON_TRUE_RETURN_VAL.

## eina_inarray_free()

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

Frees an array and its members.

Parameters

  [in] | array | The array object

See also
  eina_inarray_flush()

Since
  1.2

References _Eina_Inarray::members.

## eina_inarray_step_set()

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

Initializes an inline array.

This initializes an array. If the `step` is `0`, then a safe default is chosen.

Parameters

  [in] | array | The array object to initialize
  [in] | sizeof_eina_inarray | The size of array object
  [in] | member_size | The size of each member in the array
  [in] | step | The step size by which to resize the array, do this using the following extra amount

Note
  This is useful for arrays inlined into other structures or allocated to a stack.

See also
  eina_inarray_flush()

Since
  1.2

References EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, and ERR.

## eina_inarray_flush()

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

Removes every member from the array.

Parameters

  [in] | array | The array object

Since
  1.2

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

## eina_inarray_push()

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

Copies the data as the last member of the array.

This copies the given pointer contents at the end of the array. The pointer is not referenced, instead its contents are copied to the members array using the previously defined `member_size`.

Parameters

  [in] | array | The array object
  [in] | data | The data to be copied at the end

Returns
  The index of the new member, otherwise `-1` on errors

See also
  eina_inarray_insert_at()

Since
  1.2

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

Referenced by eina_inarray_insert().

## eina_inarray_grow()

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

Allocates new item at the end of the array.

Parameters

  [in] | array | The array object
  [in] | size | The number of new item to allocate

Note
  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().

## eina_inarray_insert()

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

Copies the data to the array at a position found by the comparison function.

This copies the given pointer contents at the array position defined by the given compare function. The pointer is not referenced, instead its contents are copied to the members array using the previously defined `member_size`.

Parameters

  [in] | array | The array object
  [in] | data | The data to be copied
  [in] | compare | The compare function

Returns
  The index of the new member, otherwise `-1` on errors

Note
  The data given to the `compare` function is a pointer to the 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_SAFETY_ON_NULL_RETURN_VAL, _Eina_Inarray::len, _Eina_Inarray::member_size, and _Eina_Inarray::members.

## eina_inarray_insert_sorted()

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

Copies the data to the array at a position found by the comparison function.

This copies the given pointer contents at the array position defined by the given `compare` function. The pointer is not referenced, instead its contents are copied to the members array using the previously defined `member_size`.

Parameters

  [in] | array | The array object
  [in] | data | The data to be copied
  [in] | compare | The compare function

Returns
  The index of the new member, otherwise `-1` on errors

Note
  The data given to the `compare` function is a pointer to the member memory itself, do no change it.
  This variation optimizes the insertion position assuming that the array is already sorted by doing a binary search.

See also
  eina_inarray_sort()

Since
  1.2

References eina_inarray_insert_at(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_inarray_remove()

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

Finds data and removes the matching member.

This finds data in the array and removes it. Data may be an existing member of the array (then optimized) or the contents are matched using memcmp().

Parameters

  [in] | array | The array object
  [in] | data | The data to be found and removed

Returns
  The index of the removed member, otherwise `-1` on errors

See also
  eina_inarray_pop()
  eina_inarray_remove_at()

Since
  1.2

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

## eina_inarray_pop()

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

Removes the last member of the array.

Parameters

  [in] | array | The array object

Returns
  The data popped out of the array

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

Since
  1.2

References _Eina_Inarray::len.

## eina_inarray_nth()

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

Gets the member at the given position.

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

Parameters

  [in] | array | The array object
  [in] | position | The member position

Returns
  A pointer to current the member memory

Since
  1.2

References EINA_SAFETY_ON_TRUE_RETURN_VAL, and _Eina_Inarray::len.

## eina_inarray_insert_at()

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

Copies the data at the given position in the array.

This copies the given pointer contents at the given `position` in the array. The pointer is not referenced, instead its contents are copied to the members array using the previously defined `member_size`.

Parameters

  [in] | array | The array object
  [in] | position | The position to insert the member at
  [in] | data | The data to be copied at the position

Returns
  EINA_TRUE on success, otherwise EINA_FALSE on failure

Note
  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 (equal to eina_inarray_count()), then the member is appended.
  If position is bigger than the array length, it fails.

Since
  1.2

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

Referenced by eina_inarray_insert(), and eina_inarray_insert_sorted().

## eina_inarray_alloc_at()

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

Opens a space at the given position, returning its pointer.

Parameters

  [in] | array | The array object
  [in] | position | The position to insert first member at (open/allocate space)
  [in] | member_count | The number of times `member_size` bytes are allocated

Returns
  A pointer to the first member memory allocated, otherwise `NULL` on errors

Note
  This is similar to eina_inarray_insert_at(), but useful if the members contents are still unknown or unallocated. It makes room for the required number of items and returns the pointer to the first item, similar to malloc(member_count * member_size), with the guarantee that all the memory is within the 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 (equal to eina_inarray_count()), then the member is appended.
  If position is bigger than the array length, it fails.

Since
  1.2

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

## eina_inarray_replace_at()

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

Copies the data to the given position.

This copies the given pointer contents at the given `position` in the array. The pointer is not referenced, instead its contents are copied to the members array using the previously defined `member_size`.

Parameters

  [in] | array | The array object
  [in] | position | The position to copy the member at
  [in] | data | The data to be copied at the position

Returns
  EINA_TRUE on success, otherwise EINA_FALSE on failure

Note
  If `position` does not exist, it fails.

Since
  1.2

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

## eina_inarray_remove_at()

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

Removes a member from the given position.

Parameters

  [in] | array | The array object
  [in] | position | The position from which to remove a member

Returns
  EINA_TRUE on success, otherwise EINA_FALSE on failure

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

See also
  eina_inarray_pop()
  eina_inarray_remove()

Since
  1.2

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

Referenced by eina_inarray_foreach_remove(), and eina_inarray_remove().

## eina_inarray_reverse()

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

Reverses members in the array.

Parameters

  [in] | array | The array object

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

See also
  EINA_INARRAY_REVERSE_FOREACH()

Since
  1.2

References alloca(), EINA_SAFETY_ON_NULL_RETURN, _Eina_Inarray::len, _Eina_Inarray::member_size, and _Eina_Inarray::members.

## eina_inarray_sort()

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

Applies a quick sort to the array.

This applies a quick sort to the array.

Parameters

  [in] | array | The array object
  [in] | compare | The compare function

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

See also
  eina_inarray_insert_sorted()

Since
  1.2

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

## eina_inarray_search()

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

Searches for a member (linear walk).

This walks through an array by linearly looking for the given data compared by the `compare` function.

Parameters

  [in] | array | The array object
  [in] | data | The member to search using the `compare` function
  [in] | compare | The compare function

Returns
  The member index, otherwise `-1` if not found

Note
  The data given to the `compare` function is a pointer to the member memory itself, do no change it.

Since
  1.2

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_inarray_search_sorted()

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

Searches for member (binary search walk).

Parameters

  [in] | array | The array object
  [in] | data | The member to search using the `compare` function
  [in] | compare | The compare function

Returns
  The member index, otherwise `-1` if not found

Note
  Uses a binary search for the given data as compared by the `compare` function.
  The data given to the `compare` function is a pointer to the member memory itself, do no change it.

Since
  1.2

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_inarray_foreach()

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

Calls `function` for each array member.

This calls `function` for every given data in `array`.

Parameters

  [in] | array | The array object
  [in] | function | The callback function
  [in] | user_data | The user data given to a callback function

Returns
  EINA_TRUE if it successfully iterates all the items of the array

Note
  This is a 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 stops and returns EINA_FALSE as the result.
  The data given to `function` is a pointer to the member memory itself.

See also
  EINA_INARRAY_FOREACH()

Since
  1.2

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

## eina_inarray_foreach_remove()

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

Removes all the members that match.

This removes all the entries in `array`, where the `match` function returns EINA_TRUE.

Parameters

  [in] | array | The array object
  [in] | match | The match function
  [in] | user_data | The user data given to callback `match`

Returns
  The number of removed entries, otherwise `-1` on error

Since
  1.2

References EINA_FALSE, eina_inarray_remove_at(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_inarray_resize()

EINA_API Eina_Bool eina_inarray_resize | ( | Eina_Inarray * | array,
|  | unsigned int | new_size )

Resizes array to new size.

Parameters

  [in] | array | The array object
  [in] | new_size | New size for resize

Returns
  EINA_TRUE if it resized the array successfully.

Since
  1.10

References EINA_FALSE, EINA_TRUE, and _Eina_Inarray::len.

## eina_inarray_count()

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

Counts the number of members in an array.

Parameters

  [in] | array | The array object

Returns
  The number of members in the array

Since
  1.2

References _Eina_Inarray::len.

## eina_inarray_iterator_new()

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

Returns a new iterator associated to an array.

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

Parameters

  [in] | array | The array object

Returns
  A new iterator

Note
  If the memory cannot 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's 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_inarray_iterator_reversed_new()

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

Returns a new reversed iterator associated to an array.

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

Parameters

  [in] | array | The array object

Returns
  A new iterator

Note
  Unlike eina_inarray_iterator_new(), this walks through the array backwards.
  If the memory cannot 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's 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_inarray_accessor_new()

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

Returns a new accessor associated to an array.

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

Parameters

  [in] | array | The array object

Returns
  A new accessor

Note
  If the memory cannot 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.