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

Data Structures | Macros | Typedefs | Functions
Accessor Functions
Content Access

These functions manage accessor on containers. More...

## Data Structures
struct | _Eina_Accessor
| Type to provide random access to data structures. More...

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

## Typedefs
typedef struct _Eina_Accessor | Eina_Accessor
| Abstract type for accessors.
typedef Eina_Bool(* | Eina_Accessor_Get_At_Callback )(Eina_Accessor *it, unsigned int idx, 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
EAPI void | eina_accessor_free (Eina_Accessor *accessor)
| Free an accessor. More...
EAPI Eina_Bool | eina_accessor_data_get (Eina_Accessor *accessor, unsigned int position, void **data) EINA_ARG_NONNULL(1)
| Retrieve the data of an accessor at a given position. More...
EAPI void * | eina_accessor_container_get (Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE
| Return the container of an accessor. More...
EAPI void | eina_accessor_over (Eina_Accessor *accessor, Eina_Each_Cb cb, unsigned int start, unsigned int end, const void *fdata) EINA_ARG_NONNULL(2)
| Iterate over the container and execute a callback on chosen elements. More...
EAPI Eina_Bool | eina_accessor_lock (Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
| Lock the container of the accessor. More...
EAPI Eina_Bool | eina_accessor_unlock (Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
| Unlock the container of the accessor. More...

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

Getting an accessor to access elements of a given container is done through the functions of that particular container. There is no function to create a generic accessor as accessors absolutely depend on the container. This means you won't find accessor creation function here, those can be found on the documentation of the container type you're using. Though created with container specific functions accessors are always deleted with the same function: 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().

See an example here.

## Macro Definition Documentation

#define EINA_ACCESSOR_FOREACH | ( |  | accessor,
|  |  | counter,
|  |  | data
| ) |  |

Value:
for ((counter) = 0; \
eina_accessor_data_get((accessor), (counter), (void **)(void *)&(data)); \
(counter)++)
eina_accessor_data_get
EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor, unsigned int position, void **data) EINA_ARG_NONNULL(1)
Retrieve the data of an accessor at a given position.
Definition: eina_accessor.c:116

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 limitation of accessors themselves, rather in the accessors implementations to keep them as simple and fast as possible.

## Function Documentation

EAPI 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`;

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

References EINA_FALSE.

EAPI 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`.

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

References eina_accessor_lock(), eina_accessor_unlock(), and EINA_TRUE.

EAPI 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` permits it, it will be locked. When a container is locked calling eina_accessor_over() on it will return immediately. If `accessor` is `NULL` or if a problem occurred, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container isn't lockable, it will return EINA_TRUE.

Warning
  None of the existing eina data structures are lockable.

References EINA_FALSE, and EINA_TRUE.

Referenced by eina_accessor_over().

EAPI 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` permits 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.

Warning
  None of the existing eina data structures are lockable.

References EINA_FALSE, and EINA_TRUE.

Referenced by eina_accessor_over().