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

Data Structures

struct  _Eina_Inarray
 Inline array structure, use Eina_Inarray typedef instead. More...

Defines

#define EINA_INARRAY_FOREACH(array, itr)
 walks array linearly from head to tail
#define EINA_INARRAY_REVERSE_FOREACH(array, itr)
 walks array linearly from tail to head

Typedefs

typedef struct _Eina_Inarray Eina_Inarray
 Inlined array type.

Functions

Eina_Inarrayeina_inarray_new (unsigned int member_size, unsigned int step)
 Create new inline array.
void eina_inarray_free (Eina_Inarray *array)
 Free array and its members.
void eina_inarray_step_set (Eina_Inarray *array, unsigned int sizeof_eina_inarray, unsigned int member_size, unsigned int step)
 Initialize inline array.
void eina_inarray_flush (Eina_Inarray *array)
 Remove every member from array.
int eina_inarray_push (Eina_Inarray *array, const void *data)
 Copy the data as the last member of the array.
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.
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.
int eina_inarray_remove (Eina_Inarray *array, const void *data)
 Find data and remove matching member.
void * eina_inarray_pop (Eina_Inarray *array)
 Removes the last member of the array.
void * eina_inarray_nth (const Eina_Inarray *array, unsigned int position)
 Get the member at given position.
Eina_Bool eina_inarray_insert_at (Eina_Inarray *array, unsigned int position, const void *data)
 Copy the data at given position in the array.
void * eina_inarray_alloc_at (Eina_Inarray *array, unsigned int position, unsigned int member_count)
 Opens a space at given position, returning its pointer.
Eina_Bool eina_inarray_replace_at (Eina_Inarray *array, unsigned int position, const void *data)
 Copy the data over the given position.
Eina_Bool eina_inarray_remove_at (Eina_Inarray *array, unsigned int position)
 Remove member at given position.
void eina_inarray_reverse (Eina_Inarray *array)
 Reverse members in the array.
void eina_inarray_sort (Eina_Inarray *array, Eina_Compare_Cb compare)
 Applies quick sort to array.
int eina_inarray_search (const Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
 Search member (linear walk).
int eina_inarray_search_sorted (const Eina_Inarray *array, const void *data, Eina_Compare_Cb compare)
 Search member (binary search walk).
Eina_Bool eina_inarray_foreach (const Eina_Inarray *array, Eina_Each_Cb function, const void *user_data)
 Call function for each array member.
int eina_inarray_foreach_remove (Eina_Inarray *array, Eina_Each_Cb match, const void *user_data)
 Remove all members that matched.
unsigned int eina_inarray_count (const Eina_Inarray *array)
 number of members in array.
Eina_Iteratoreina_inarray_iterator_new (const Eina_Inarray *array)
 Returned a new iterator associated to an array.
Eina_Iteratoreina_inarray_iterator_reversed_new (const Eina_Inarray *array)
 Returned a new reversed iterator associated to an array.
Eina_Accessoreina_inarray_accessor_new (const Eina_Inarray *array)
 Returned a new accessor associated to an array.

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:


Define 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

#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

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 and EINA_ERROR_OUT_OF_MEMORY is set. If member_size is zero, then NULL is returned.

See also:
eina_inarray_free()
Since:
1.2

References EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), and EINA_SAFETY_ON_TRUE_RETURN_VAL.

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

References EINA_SAFETY_ON_NULL_RETURN, and EINA_SAFETY_ON_TRUE_RETURN.

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_SAFETY_ON_NULL_RETURN_VAL, _Eina_Inarray::len, and _Eina_Inarray::member_size.

Referenced by eina_inarray_insert().

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_SAFETY_ON_NULL_RETURN_VAL, _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(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

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_SAFETY_ON_NULL_RETURN_VAL, _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_SAFETY_ON_TRUE_RETURN_VAL, and _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_SAFETY_ON_TRUE_RETURN_VAL, and _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_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().

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_SAFETY_ON_TRUE_RETURN_VAL, _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_SAFETY_ON_TRUE_RETURN_VAL, 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_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().

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_SAFETY_ON_NULL_RETURN, _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_SAFETY_ON_NULL_RETURN, _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

References EINA_SAFETY_ON_NULL_RETURN_VAL.

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

References EINA_SAFETY_ON_NULL_RETURN_VAL.

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_SAFETY_ON_NULL_RETURN_VAL, 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, eina_inarray_remove_at(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

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 and EINA_ERROR_OUT_OF_MEMORY is set. 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_ERROR_OUT_OF_MEMORY, eina_error_set(), 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 and EINA_ERROR_OUT_OF_MEMORY is set. 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_ERROR_OUT_OF_MEMORY, eina_error_set(), 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 and EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid accessor is returned.

Since:
1.2

References EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), EINA_MAGIC_SET, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, FUNC_ACCESSOR_GET_CONTAINER, and _Eina_Inarray::version.