Accessor Functions

Data Structures | Macros | Typedefs | Functions
Accessor Functions
Eina » Data Types » Content Access

This group discusses the functions to manage an accessor on containers. More...

## Data Structures
struct | _Eina_Accessor
| Structure 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 | FUNC_ACCESSOR_CLONE(Function) ((Eina_Accessor_Clone_Callback)Function)
| Helper macro to cast `Function` to a Eina_Iterator_Clone_Callback. More...
#define | EINA_ACCESSOR_FOREACH(accessor, counter, data)
| Helper macro to iterate over all the elements easily. More...

## Typedefs
typedef struct _Eina_Accessor | Eina_Accessor
| Type for a accessor structure.
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 to return the container of the accessor.
typedef void(* | Eina_Accessor_Free_Callback) (Eina_Accessor *it)
| Type for a callback to free the accessor.
typedef Eina_Bool(* | Eina_Accessor_Lock_Callback) (Eina_Accessor *it)
| Type for a callback to lock the accessor.
typedef Eina_Accessor *(* | Eina_Accessor_Clone_Callback) (Eina_Accessor *it)
| Type for a callback to return a clone for the accessor. More...

## Functions
EAPI void | eina_accessor_free (Eina_Accessor *accessor)
| Frees an accessor. More...
EAPI Eina_Bool | eina_accessor_data_get (Eina_Accessor *accessor, unsigned int position, void **data) EINA_ARG_NONNULL(1)
| Gets the data of an accessor at the given position. More...
EAPI void * | eina_accessor_container_get (Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE
| Gets 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)
| Iterates over the container and executes a callback on the chosen elements. More...
EAPI Eina_Bool | eina_accessor_lock (Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
| Locks the container of the accessor. More...
EAPI Eina_Accessor * | eina_accessor_clone (Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
| Clones 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

This group discusses the functions to manage an 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 an 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 by 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

## ◆ FUNC_ACCESSOR_CLONE

#define FUNC_ACCESSOR_CLONE | ( |  | Function | ) | ((Eina_Accessor_Clone_Callback)Function)

Helper macro to cast `Function` to a Eina_Iterator_Clone_Callback.

Since
  1.10

## ◆ EINA_ACCESSOR_FOREACH

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

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

Helper macro to iterate over all the elements easily.

Parameters

  accessor | The accessor to use
  counter | A counter used by eina_accessor_data_get() when iterating over the container.
  data | A pointer to store the data It must be a pointer to support getting its address since eina_accessor_data_get() requires a 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 data type provides both iterators and accessors, prefer to use iterators to iterate over, as they're likely to be more optimized for such a task.
  This example is not an optimal algorithm to release a list as it walks through the list twice, but it serves as an example. For an optimized version use EINA_LIST_FREE().

Warning
  Unless explicitly stated in the function's returning accessors, do not modify the accessed object while you walk through it. In this example using lists, do not remove list nodes or the program might crash. This is not a limitation of the accessors themselves, but a limitation in the accessors implementations to keep them as simple and fast as possible.

## Typedef Documentation

## ◆ Eina_Accessor_Clone_Callback

Eina_Accessor_Clone_Callback

Type for a callback to return a clone for the accessor.

Since
  1.10

## Function Documentation

## ◆ eina_accessor_free()

EAPI void eina_accessor_free | ( | Eina_Accessor * | accessor | ) |

Frees an accessor.

Parameters

  [in] | accessor | The accessor to free

This function frees accessor if it is not `NULL`.

Referenced by efl::eina::accessor_common_base< T >::operator=(), and efl::eina::accessor_common_base< T >::~accessor_common_base().

## ◆ eina_accessor_data_get()

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

Gets the data of an accessor at the given position.

Parameters

  [in] | accessor | The accessor
  [in] | position | The position of the element
  [in] | data | The pointer that stores the data to retrieve

Returns
  EINA_TRUE on success, otherwise EINA_FALSE

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

Referenced by efl::eina::accessor< T, typename std::enable_if< ! std::is_base_of<::efl::eo::concrete, T >::value, T >::type >::operator[](), and efl::eina::accessor< T, typename std::enable_if< std::is_base_of<::efl::eo::concrete, T >::value, T >::type >::operator[]().

## ◆ eina_accessor_container_get()

EAPI void* eina_accessor_container_get | ( | Eina_Accessor * | accessor | ) |

Gets the container of an accessor.

Parameters

  [in] | accessor | The accessor

Returns
  The container that created the accessor

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

## ◆ eina_accessor_over()

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

Iterates over the container and executes a callback on the chosen elements.

Parameters

  [in] | accessor | The accessor
  [in] | cb | The callback called on the chosen elements
  [in] | start | The position of the first element
  [in] | end | The position of the last element
  [in] | 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 at 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 greater than or equal to `end`, the function returns immediately.

## ◆ eina_accessor_lock()

EAPI Eina_Bool eina_accessor_lock | ( | Eina_Accessor * | accessor | ) |

Locks the container of the accessor.

Parameters

  [in] | accessor | The accessor

Returns
  EINA_TRUE on success, otherwise EINA_FALSE

Note
  If the container of the `accessor` permits it, it is locked. When a container is locked by calling eina_accessor_over() on it, it returns immediately. If `accessor` is `NULL` or if a problem occurs, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container is not lockable, it returns EINA_TRUE.

None of the existing eina data structures are lockable.

## ◆ eina_accessor_clone()

EAPI Eina_Accessor* eina_accessor_clone | ( | Eina_Accessor * | accessor | ) |

Clones the container of the accessor.

Parameters

  [in] | accessor | The accessor.

Returns
  Another accessor

Since
  1.10

Referenced by efl::eina::accessor_common_base< T >::operator=().

## ◆ eina_accessor_unlock()

EAPI Eina_Bool eina_accessor_unlock | ( | Eina_Accessor * | accessor | ) |

Unlock the container of the accessor.

Parameters

  [in] | accessor | The accessor

Returns
  EINA_TRUE on success, otherwise EINA_FALSE

Note
  If the container of the `accessor` permits it and is previously locked, it is unlocked. If `accessor` is `NULL` or if a problem occurs, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container is not lockable, it returns EINA_TRUE.

Warning
  None of the existing eina data structures are lockable.