Accessor Functions

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)
	Definition for helper macro to cast Function to a Eina_Accessor_Get_At_Callback.
#define	FUNC_ACCESSOR_GET_CONTAINER(Function)   ((Eina_Accessor_Get_Container_Callback)Function)
	Definition for helper macro to cast Function to a Eina_Accessor_Get_Container_Callback.
#define	FUNC_ACCESSOR_FREE(Function)   ((Eina_Accessor_Free_Callback)Function)
	Definition for helper macro to cast Function to a Eina_Accessor_Free_Callback.
#define	FUNC_ACCESSOR_LOCK(Function)   ((Eina_Accessor_Lock_Callback)Function)
	Definition for helper macro to cast Function to a Eina_Iterator_Lock_Callback.
#define	FUNC_ACCESSOR_CLONE(Function)   ((Eina_Accessor_Clone_Callback)Function)
	Definition for helper macro to cast Function to a Eina_Iterator_Clone_Callback. More...
#define	EINA_ACCESSOR_FOREACH(accessor, counter, data)
	Definition for helper macro to iterate over all the elements easily. More...
#define	EINA_C_ARRAY_ACCESSOR_NEW(Array)   eina_carray_length_accessor_new((void**) Array, sizeof (Array[0]), EINA_C_ARRAY_LENGTH(Array))
	Creates an Eina_Accessor that wraps a plain fixed size C array. More...
#define	EINA_C_ARRAY_ACCESSOR_PTR_NEW(Array)   eina_carray_length_ptr_accessor_new((void**) Array, sizeof (Array[0]), EINA_C_ARRAY_LENGTH(Array))

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
EINA_API void	eina_accessor_free (Eina_Accessor *accessor)
	Frees an accessor. More...
EINA_API Eina_Bool	eina_accessor_data_get (Eina_Accessor *accessor, unsigned int position, void **data)
	Gets the data of an accessor at the given position. More...
EINA_API void *	eina_accessor_container_get (Eina_Accessor *accessor)
	Gets the container of an accessor. More...
EINA_API 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. More...
EINA_API Eina_Bool	eina_accessor_lock (Eina_Accessor *accessor)
	Locks the container of the accessor. More...
EINA_API Eina_Accessor *	eina_accessor_clone (Eina_Accessor *accessor)
	Clones the container of the accessor. More...
EINA_API Eina_Bool	eina_accessor_unlock (Eina_Accessor *accessor)
	Unlocks the container of the accessor. More...
EINA_API Eina_Accessor *	eina_carray_length_accessor_new (void **array, unsigned int step, unsigned int length)
	Creates an Eina_Accessor that wraps a plain fixed size C array. More...
EINA_API Eina_Accessor *	eina_carray_length_ptr_accessor_new (void **array, unsigned int step, unsigned int length)
	Creates an Eina_Accessor that wraps a plain fixed size C array. 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)

Definition for 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)++)

Definition for helper macro to iterate over all the elements easily.

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

Parameters

[in]	accessor	The accessor to use
[out]	counter	A counter used by eina_accessor_data_get() when iterating over the container.
[out]	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 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.

EINA_C_ARRAY_ACCESSOR_NEW

#define EINA_C_ARRAY_ACCESSOR_NEW

(

Array

)

eina_carray_length_accessor_new((void**) Array, sizeof (Array[0]), EINA_C_ARRAY_LENGTH(Array))

Creates an Eina_Accessor that wraps a plain fixed size C array.

Parameters

[in]

Array

The array

Returns

The accessor that will give access to the passed array

You can create it like this: int array[] = {1, 2, 3, 4, 1337, 42};

Eina_Accessor* accessor = EINA_C_ARRAY_ACCESSOR_NEW(array)

Since

1.23

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()

EINA_API void eina_accessor_free

(

Eina_Accessor *

accessor

)

Frees an accessor.

This function frees accessor if it is not NULL.

Parameters

[in]

accessor

The accessor to free

References EINA_SAFETY_ON_NULL_RETURN, and _Eina_Accessor::free.

Referenced by elm_gengrid_nth_item_get(), and elm_genlist_nth_item_get().

eina_accessor_data_get()

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

Gets the data of an accessor at the given position.

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.

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

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and _Eina_Accessor::get_at.

Referenced by elm_gengrid_nth_item_get(), and elm_genlist_nth_item_get().

eina_accessor_container_get()

EINA_API void * eina_accessor_container_get

(

Eina_Accessor *

accessor

)

Gets the container of an accessor.

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

Parameters

[in]

accessor

The accessor

Returns

The container that created the accessor

References EINA_SAFETY_ON_NULL_RETURN_VAL, and _Eina_Accessor::get_container.

eina_accessor_over()

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

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.

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

References eina_accessor_lock(), eina_accessor_unlock(), EINA_SAFETY_ON_FALSE_RETURN, EINA_SAFETY_ON_NULL_RETURN, EINA_TRUE, _Eina_Accessor::get_at, and _Eina_Accessor::get_container.

eina_accessor_lock()

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

Warning

None of the existing eina data structures are lockable.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and _Eina_Accessor::lock.

Referenced by eina_accessor_over().

eina_accessor_clone()

EINA_API 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

References _Eina_Accessor::clone, and EINA_SAFETY_ON_NULL_RETURN_VAL.

eina_accessor_unlock()

EINA_API Eina_Bool eina_accessor_unlock

(

Eina_Accessor *

accessor

)

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

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and _Eina_Accessor::unlock.

Referenced by eina_accessor_over().

eina_carray_length_accessor_new()

EINA_API Eina_Accessor * eina_carray_length_accessor_new	(	void **	array,
		unsigned int	step,
		unsigned int	length
	)

Creates an Eina_Accessor that wraps a plain fixed size C array.

Parameters

[in]	array	The array
[in]	step	The size of one element in the array
[in]	length	The number of elements in the array

Returns

The accessor that will give access to the passed array

You can create it like this: int array[] = {1, 2, 3, 4, 1337, 42};

Eina_Accessor* accessor = eina_carray_length_accessor_new(array, sizeof(int), sizeof(array)/sizeof(int));

Since

1.23

References EINA_MAGIC_SET, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, and FUNC_ACCESSOR_GET_CONTAINER.

eina_carray_length_ptr_accessor_new()

EINA_API Eina_Accessor * eina_carray_length_ptr_accessor_new	(	void **	array,
		unsigned int	step,
		unsigned int	length
	)

Creates an Eina_Accessor that wraps a plain fixed size C array.

Parameters

[in]	array	The array
[in]	step	The size of one element in the array
[in]	length	The number of elements in the array

Returns

The accessor that will give access to the passed array

You can create it like this: int array[] = {1, 2, 3, 4, 1337, 42};

Eina_Accessor* accessor = eina_carray_length_accessor_new(array, sizeof(int), sizeof(array)/sizeof(int));

Note: The difference to eina_carray_length_accessor_new is that this will fill the pointer to the value into the data pointer. *

Since

1.24

References EINA_MAGIC_SET, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, and FUNC_ACCESSOR_GET_CONTAINER.