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_Inarrayeina_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_Iteratoreina_inarray_iterator_new (const Eina_Inarray *array)
 Returned a new iterator associated to an array. More...
 
Eina_Iteratoreina_inarray_iterator_reversed_new (const Eina_Inarray *array)
 Returned a new reversed iterator associated to an array. More...
 
Eina_Accessoreina_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:

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
arrayarray object
itrthe 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
arrayarray object
itrthe 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

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_sizesize of each member in the array.
stepwhen 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
arrayarray 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
arrayarray object to initialize.
member_sizesize of each member in the array.
stepwhen 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
arrayarray 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
arrayarray object
datadata 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
arrayarray object
sizenumber 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
arrayarray object
datadata to be copied
comparecompare 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
arrayarray object
datadata to be copied
comparecompare 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
arrayarray object
datadata 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
arrayarray 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
arrayarray object
positionmember 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
arrayarray object
positionwhere to insert the member
datadata 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
arrayarray object
positionwhere to insert first member (open/allocate space)
member_counthow 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
arrayarray object
positionwhere to replace the member
datadata 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
arrayarray object
positionposition 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
arrayarray 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
arrayarray object
comparecompare 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
arrayarray object
datamember to search using compare function.
comparecompare 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
arrayarray object
datamember to search using compare function.
comparecompare 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
arrayarray object
functioncallback function
user_datauser 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
arrayarray object
matchmatch function
user_datauser 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
arrayarray 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
arrayarray 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
arrayarray 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
arrayarray 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.