forked from enlightenment/efl
* add accessor doc
* fix and add some links SVN revision: 35865
This commit is contained in:
parent
0b6f01fec5
commit
557107790a
|
@ -80,9 +80,9 @@
|
||||||
* @subsection eina_container_subsec Containers
|
* @subsection eina_container_subsec Containers
|
||||||
*
|
*
|
||||||
* Containers are data types that hold data and allow iteration over
|
* Containers are data types that hold data and allow iteration over
|
||||||
* their elements with an @ref eina_iterators, or eventually an
|
* their elements with an @ref eina_iterators_subsec, or eventually an
|
||||||
* @ref eina_accessors. The only data type that is not a container (in
|
* @ref eina_accessors_subsec. The only data type that is not a container (in
|
||||||
* that sense) is the @ref eina_stringshare.
|
* that sense) is the @ref eina_stringshare_subsec.
|
||||||
*
|
*
|
||||||
* @subsubsection eina_array_subsubsec Array
|
* @subsubsection eina_array_subsubsec Array
|
||||||
*
|
*
|
||||||
|
@ -98,20 +98,22 @@
|
||||||
*
|
*
|
||||||
* @section eina_access_contents_sec Accessing Data Struct Contents
|
* @section eina_access_contents_sec Accessing Data Struct Contents
|
||||||
*
|
*
|
||||||
* For the above data types, you can access to the elements
|
* For the container data types, you can access to the elements
|
||||||
* sequentially with iterators, or randomly with accessors. They are
|
* sequentially with iterators, or randomly with accessors. They are
|
||||||
* created from the data types (named 'containers') themselves and
|
* created from the data types themselves and allow a generic way to
|
||||||
* allow a genenric way to traverse these data types.
|
* traverse these data types.
|
||||||
*
|
*
|
||||||
* @subsection eina_iterators_subsec Iterator
|
* @subsection eina_iterators_subsec Iterator
|
||||||
*
|
*
|
||||||
* Iterators allow to access the data of a container in a sequential
|
* Iterators allow a sequential access of the data of a
|
||||||
* way. They can only access the next element. To look at the API, go
|
* container. They can only access the next element. To look at the
|
||||||
* to @ref Eina_Iterator_Group.
|
* API, go to @ref Eina_Iterator_Group.
|
||||||
*
|
*
|
||||||
* @subsection eina_accessors_subsec Accessor
|
* @subsection eina_accessors_subsec Accessor
|
||||||
*
|
*
|
||||||
* Accessors can access randomly the elements of a container.
|
* Accessors allow a random access of the data of a container. They
|
||||||
|
* can access an element at any position. To look at the API, go to
|
||||||
|
* @ref Eina_Accessor_Group.
|
||||||
*
|
*
|
||||||
* @section eina_tools_sec Eina Tools
|
* @section eina_tools_sec Eina Tools
|
||||||
*
|
*
|
||||||
|
|
|
@ -20,8 +20,17 @@
|
||||||
#define EINA_ACCESSOR_H__
|
#define EINA_ACCESSOR_H__
|
||||||
|
|
||||||
#include "eina_types.h"
|
#include "eina_types.h"
|
||||||
#include "eina_error.h"
|
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @defgroup Eina_Accessor_Group Accessor Functions
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Accessor
|
||||||
|
* Type for accessors.
|
||||||
|
*/
|
||||||
typedef struct _Eina_Accessor Eina_Accessor;
|
typedef struct _Eina_Accessor Eina_Accessor;
|
||||||
|
|
||||||
EAPI void eina_accessor_free (Eina_Accessor *accessor);
|
EAPI void eina_accessor_free (Eina_Accessor *accessor);
|
||||||
|
@ -35,4 +44,8 @@ EAPI void eina_accessor_over (Eina_Accessor *accessor,
|
||||||
unsigned int end,
|
unsigned int end,
|
||||||
const void *fdata);
|
const void *fdata);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
||||||
#endif
|
#endif
|
||||||
|
|
|
@ -36,19 +36,54 @@
|
||||||
* API *
|
* API *
|
||||||
*============================================================================*/
|
*============================================================================*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @addtogroup Eina_Content_Access_Group Content Access
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @addtogroup Eina_Accessor_Group Accessors Functions
|
||||||
|
*
|
||||||
|
* @brief 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
|
||||||
|
* @ref Eina_Iterator_Group.
|
||||||
|
*
|
||||||
|
* 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().
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Free an accessor.
|
||||||
|
*
|
||||||
|
* @param accessor The accessor to free.
|
||||||
|
*
|
||||||
|
* This function frees @p accessor if it is not @c NULL;
|
||||||
|
*/
|
||||||
EAPI void
|
EAPI void
|
||||||
eina_accessor_free(Eina_Accessor *accessor)
|
eina_accessor_free(Eina_Accessor *accessor)
|
||||||
{
|
{
|
||||||
if (accessor) accessor->free(accessor);
|
if (accessor) accessor->free(accessor);
|
||||||
}
|
}
|
||||||
|
|
||||||
EAPI Eina_Bool
|
/**
|
||||||
eina_accessor_data_get(Eina_Accessor *accessor, unsigned int position, void **data)
|
* @brief Return the container of an accessor.
|
||||||
{
|
*
|
||||||
if (!accessor) return EINA_FALSE;
|
* @param accessor The accessor.
|
||||||
return accessor->get_at(accessor, position, data);
|
* @return The container which created the accessor.
|
||||||
}
|
*
|
||||||
|
* This function returns the container which created @p accessor. If
|
||||||
|
* @p accessor is @c NULL, this function returns @c NULL.
|
||||||
|
*/
|
||||||
EAPI void *
|
EAPI void *
|
||||||
eina_accessor_container_get(Eina_Accessor *accessor)
|
eina_accessor_container_get(Eina_Accessor *accessor)
|
||||||
{
|
{
|
||||||
|
@ -56,6 +91,42 @@ eina_accessor_container_get(Eina_Accessor *accessor)
|
||||||
return accessor->get_container(accessor);
|
return accessor->get_container(accessor);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Retrieve the data of an accessor at a given position.
|
||||||
|
*
|
||||||
|
* @param accessor The accessor.
|
||||||
|
* @param position The position of the element.
|
||||||
|
* @param data The pointer that stores the data to retrieve.
|
||||||
|
* @return #EINA_TRUE on success, #EIA_FALSE otherwise.
|
||||||
|
*
|
||||||
|
* This function retrieves the data of the element pointed by
|
||||||
|
* @p accessor at the porition @p position, and stores it in
|
||||||
|
* @p data. If @p accessor is @c NULL or if an error occurred,
|
||||||
|
* #EINA_FALSE is returned, otherwise EINA_TRUE is returned.
|
||||||
|
*/
|
||||||
|
EAPI Eina_Bool
|
||||||
|
eina_accessor_data_get(Eina_Accessor *accessor, unsigned int position, void **data)
|
||||||
|
{
|
||||||
|
if (!accessor) return EINA_FALSE;
|
||||||
|
return accessor->get_at(accessor, position, data);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Iterate over the container and execute a callback on chosen elements.
|
||||||
|
*
|
||||||
|
* @param accessor The accessor.
|
||||||
|
* @param cb The callback called on the chosen elements.
|
||||||
|
* @param start The position of the first element.
|
||||||
|
* @param end The position of the last element.
|
||||||
|
* @param fdata The data passed to the callback.
|
||||||
|
*
|
||||||
|
* This function iterates over the elements pointed by @p accessor,
|
||||||
|
* starting from the element at position @p start and ending to the
|
||||||
|
* element at position @p end. For Each element, the callback
|
||||||
|
* @p cb is called with the data @p fdata. If @p accessor is @c NULL
|
||||||
|
* or if @p start is greter or equal than @p end, the function returns
|
||||||
|
* immediatly.
|
||||||
|
*/
|
||||||
EAPI void
|
EAPI void
|
||||||
eina_accessor_over(Eina_Accessor *accessor,
|
eina_accessor_over(Eina_Accessor *accessor,
|
||||||
Eina_Each cb,
|
Eina_Each cb,
|
||||||
|
@ -75,4 +146,10 @@ eina_accessor_over(Eina_Accessor *accessor,
|
||||||
if (cb(container, data, (void*) fdata) != EINA_TRUE) return ;
|
if (cb(container, data, (void*) fdata) != EINA_TRUE) return ;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
|
@ -37,15 +37,21 @@
|
||||||
*============================================================================*/
|
*============================================================================*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @addtogroup Eina_Iterators_Group Iterators Functions
|
* @addtogroup Eina_Content_Access_Group Content Access
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @addtogroup Eina_Iterator_Group Iterators Functions
|
||||||
*
|
*
|
||||||
* @brief These functions manage iterators on containers.
|
* @brief These functions manage iterators on containers.
|
||||||
*
|
*
|
||||||
* These functions allow to iterate over a container in a generic way,
|
* These functions allow to access elements of a container in a
|
||||||
* without knowing which container is used (a bit like iterators in
|
* generic way, without knowing which container is used (a bit like
|
||||||
* the C++ STL). Iterators only allows sequential iteration (that is,
|
* iterators in the C++ STL). Iterators only allows sequential access
|
||||||
* from an element to the next one). For random iteration, see
|
* (that is, from an element to the next one). For random access, see
|
||||||
* @ref Eina_Accessors.
|
* @ref Eina_Accessor_Group.
|
||||||
*
|
*
|
||||||
* An iterator is created from container data types, so no creation
|
* An iterator is created from container data types, so no creation
|
||||||
* function is available here. An iterator is deleted with
|
* function is available here. An iterator is deleted with
|
||||||
|
@ -57,7 +63,7 @@
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Free an iterator
|
* @brief Free an iterator.
|
||||||
*
|
*
|
||||||
* @param iterator The iterator to free.
|
* @param iterator The iterator to free.
|
||||||
*
|
*
|
||||||
|
@ -135,3 +141,7 @@ eina_iterator_foreach(Eina_Iterator *iterator,
|
||||||
/**
|
/**
|
||||||
* @}
|
* @}
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
Loading…
Reference in New Issue