Accessor Functions
[Content Access]

These functions manage accessor on containers. More...

Data Structures

struct  _Eina_Accessor

Defines

#define FUNC_ACCESSOR_GET_AT(Function)   ((Eina_Accessor_Get_At_Callback)Function)
 Helper macro to cast Function to a Eina_Accessor_Get_At_Callback.
#define FUNC_ACCESSOR_GET_CONTAINER(Function)   ((Eina_Accessor_Get_Container_Callback)Function)
 Helper macro to cast Function to a Eina_Accessor_Get_Container_Callback.
#define FUNC_ACCESSOR_FREE(Function)   ((Eina_Accessor_Free_Callback)Function)
 Helper macro to cast Function to a Eina_Accessor_Free_Callback.
#define FUNC_ACCESSOR_LOCK(Function)   ((Eina_Accessor_Lock_Callback)Function)
 Helper macro to cast Function to a Eina_Iterator_Lock_Callback.
#define EINA_ACCESSOR_FOREACH(accessor, counter, data)
 Macro to iterate over all elements easily.

Typedefs

typedef struct _Eina_Accessor Eina_Accessor
 Abstract type for accessors.
typedef Eina_Bool(* Eina_Accessor_Get_At_Callback )(Eina_Accessor *it, unsigned int index, void **data)
 Type for a callback that returns the data of a container as the given index.
typedef void *(* Eina_Accessor_Get_Container_Callback )(Eina_Accessor *it)
 Type for a callback that returns the container.
typedef void(* Eina_Accessor_Free_Callback )(Eina_Accessor *it)
 Type for a callback that frees the container.
typedef Eina_Bool(* Eina_Accessor_Lock_Callback )(Eina_Accessor *it)
 Type for a callback that lock the container.

Functions

void eina_accessor_free (Eina_Accessor *accessor)
 Free an accessor.
Eina_Bool eina_accessor_data_get (Eina_Accessor *accessor, unsigned int position, void **data)
 Retrieve the data of an accessor at a given position.
void * eina_accessor_container_get (Eina_Accessor *accessor)
 Return the container of an accessor.
void eina_accessor_over (Eina_Accessor *accessor, Eina_Each_Cb cb, unsigned int start, unsigned int end, const void *fdata)
 Iterate over the container and execute a callback on chosen elements.
Eina_Bool eina_accessor_lock (Eina_Accessor *accessor)
 Lock the container of the accessor.
Eina_Bool eina_accessor_unlock (Eina_Accessor *accessor)
 Unlock the container of the accessor.

Detailed Description

These functions manage accessor on containers.

These functions allow to access elements of a container in a generic way, without knowing which container is used (a bit like iterators in the C++ STL). Accessors allows random access (that is, any element in the container). For sequential access, see Iterator Functions.

An accessor is created from container data types, so no creation function is available here. An accessor is deleted with eina_accessor_free(). To get the data of an element at a given position, use eina_accessor_data_get(). To call a function on chosen elements of a container, use eina_accessor_over().

Define Documentation

#define EINA_ACCESSOR_FOREACH ( accessor,
counter,
data   ) 
Value:
for ((counter) = 0;                                                   \
       eina_accessor_data_get((accessor), (counter), (void **)(void *)&(data)); \
       (counter)++)

Macro to iterate over all elements easily.

Parameters:
accessor The accessor to use.
counter A counter used by eina_accessor_data_get() when iterating over the container.
data Where to store * data, must be a pointer support getting its address since * eina_accessor_data_get() requires a pointer to pointer!

This macro allows a convenient way to loop over all elements in an accessor, very similar to EINA_LIST_FOREACH().

This macro can be used for freeing the data of a list, like in the following example. It has the same goal as the one documented in EINA_LIST_FOREACH(), but using accessors:

 Eina_List     *list;
 Eina_Accessor *accessor;
 unsigned int   i;
 char          *data;

 // list is already filled,
 // its elements are just duplicated strings

 accessor = eina_list_accessor_new(list);
 EINA_ACCESSOR_FOREACH(accessor, i, data)
   free(data);
 eina_accessor_free(accessor);
 eina_list_free(list);
Note:
if the datatype provides both iterators and accessors prefer to use iterators to iterate over, as they're likely to be more optimized for such task.
this example is not optimal algorithm to release a list since it will walk the list twice, but it serves as an example. For optimized version use EINA_LIST_FREE()
Warning:
unless explicitly stated in functions returning accessors, do not modify the accessed object while you walk it, in this example using lists, do not remove list nodes or you might crash! This is not a limitiation of accessors themselves, rather in the accessors implementations to keep them as simple and fast as possible.

Function Documentation

void eina_accessor_free ( Eina_Accessor *  accessor  ) 

Free an accessor.

Parameters:
accessor The accessor to free.

This function frees accessor if it is not NULL;

Eina_Bool eina_accessor_data_get ( Eina_Accessor *  accessor,
unsigned int  position,
void **  data 
)

Retrieve the data of an accessor at a given position.

Parameters:
accessor The accessor.
position The position of the element.
data The pointer that stores the data to retrieve.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

This function retrieves the data of the element pointed by accessor at the porition position, and stores it in data. If accessor is NULL or if an error occurred, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

void * eina_accessor_container_get ( Eina_Accessor *  accessor  ) 

Return the container of an accessor.

Parameters:
accessor The accessor.
Returns:
The container which created the accessor.

This function returns the container which created accessor. If accessor is NULL, this function returns NULL.

void eina_accessor_over ( Eina_Accessor *  accessor,
Eina_Each_Cb  cb,
unsigned int  start,
unsigned int  end,
const void *  fdata 
)

Iterate over the container and execute a callback on chosen elements.

Parameters:
accessor The accessor.
cb The callback called on the chosen elements.
start The position of the first element.
end The position of the last element.
fdata The data passed to the callback.

This function iterates over the elements pointed by accessor, starting from the element at position start and ending to the element at position end. For Each element, the callback cb is called with the data fdata. If accessor is NULL or if start is greter or equal than end, the function returns immediately.

Eina_Bool eina_accessor_lock ( Eina_Accessor *  accessor  ) 

Lock the container of the accessor.

Parameters:
accessor The accessor.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

If the container of the accessor permit it, it will be locked. If accessor is NULL or if a problem occurred, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container is not lockable, it will return EINA_TRUE.

Eina_Bool eina_accessor_unlock ( Eina_Accessor *  accessor  ) 

Unlock the container of the accessor.

Parameters:
accessor The accessor.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

If the container of the accessor permit it and was previously locked, it will be unlocked. If accessor is NULL or if a problem occurred, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container is not lockable, it will return EINA_TRUE.