forked from enlightenment/efl
Iterator and Accessor doc improvements.
SVN revision: 74004
This commit is contained in:
parent
30cff2b5fb
commit
b03e262ed8
|
@ -100,6 +100,7 @@
|
||||||
*
|
*
|
||||||
* @defgroup Eina_Containers_Group Containers
|
* @defgroup Eina_Containers_Group Containers
|
||||||
*
|
*
|
||||||
|
* @section Intro Introduction
|
||||||
* 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_Iterator_Group, or eventually an
|
* their elements with an @ref Eina_Iterator_Group, or eventually an
|
||||||
* @ref Eina_Accessor_Group.
|
* @ref Eina_Accessor_Group.
|
||||||
|
@ -108,6 +109,8 @@
|
||||||
* of this is that they @b don't check the validity of data structures given to
|
* of this is that they @b don't check the validity of data structures given to
|
||||||
* them(@ref Eina_Magic_Group).
|
* them(@ref Eina_Magic_Group).
|
||||||
*
|
*
|
||||||
|
* @section Choice Choosing container type
|
||||||
|
*
|
||||||
* The choice of which container to use in each situation is very important in
|
* The choice of which container to use in each situation is very important in
|
||||||
* achieving good performance and readable code. The most common container types
|
* achieving good performance and readable code. The most common container types
|
||||||
* to be used are:
|
* to be used are:
|
||||||
|
@ -130,6 +133,19 @@
|
||||||
* @warning These are general considerations, every situation is different,
|
* @warning These are general considerations, every situation is different,
|
||||||
* don't follow these recommendations blindly.
|
* don't follow these recommendations blindly.
|
||||||
*
|
*
|
||||||
|
* @section Creation Creating custom container types
|
||||||
|
*
|
||||||
|
* @note Before creating a custom container check if one of the existing ones
|
||||||
|
* doesn't suit your needs. For example, while there is no stack type @ref
|
||||||
|
* Eina_Array_Group is a very good substitute, similarly there is no queue type
|
||||||
|
* however an @ref Eina_List_Group works very well as a queue.
|
||||||
|
*
|
||||||
|
* If creating a custom container type consider allowing access to the data in
|
||||||
|
* your container through @ref Eina_Iterator_Group "Iterators" and @ref
|
||||||
|
* Eina_Accessor_Group "Accessors". To do so your container should have an
|
||||||
|
* iterator creation function and an accessor creation function, these functions
|
||||||
|
* should return properly populated @ref _Eina_Iterator and @ref _Eina_Accessor.
|
||||||
|
*
|
||||||
* @defgroup Eina_Tools_Group Tools
|
* @defgroup Eina_Tools_Group Tools
|
||||||
*
|
*
|
||||||
* Eina tools aims to help application development, providing ways to
|
* Eina tools aims to help application development, providing ways to
|
||||||
|
|
|
@ -86,9 +86,15 @@
|
||||||
* element in the container). For sequential access, see
|
* element in the container). For sequential access, see
|
||||||
* @ref Eina_Iterator_Group.
|
* @ref Eina_Iterator_Group.
|
||||||
*
|
*
|
||||||
* An accessor is created from container data types, so no creation
|
* Getting an accessor to access elements of a given container is done through
|
||||||
* function is available here. An accessor is deleted with
|
* the functions of that particular container. There is no function to create
|
||||||
* eina_accessor_free(). To get the data of an element at a given
|
* 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
|
* position, use eina_accessor_data_get(). To call a function on
|
||||||
* chosen elements of a container, use eina_accessor_over().
|
* chosen elements of a container, use eina_accessor_over().
|
||||||
*
|
*
|
||||||
|
@ -142,6 +148,8 @@ typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it);
|
||||||
/**
|
/**
|
||||||
* @struct _Eina_Accessor
|
* @struct _Eina_Accessor
|
||||||
* Type to provide random access to data structures.
|
* Type to provide random access to data structures.
|
||||||
|
*
|
||||||
|
* If creating an accessor remember to set the type using @ref EINA_MAGIC_SET.
|
||||||
*/
|
*/
|
||||||
struct _Eina_Accessor
|
struct _Eina_Accessor
|
||||||
{
|
{
|
||||||
|
|
|
@ -93,11 +93,16 @@
|
||||||
* (that is, from an element to the next one). For random access, see
|
* (that is, from an element to the next one). For random access, see
|
||||||
* @ref Eina_Accessor_Group.
|
* @ref Eina_Accessor_Group.
|
||||||
*
|
*
|
||||||
* An iterator is created from container data types, so no creation
|
* Getting an iterator to access elements of a given container is done through
|
||||||
* function is available here. An iterator is deleted with
|
* the functions of that particular container. There is no function to create
|
||||||
* eina_iterator_free(). To get the data and iterate, use
|
* a generic iterator as iterators absolutely depend on the container. This
|
||||||
* eina_iterator_next(). To call a function on all the elements of a
|
* means you won't find iterator creation function here, those can be found on
|
||||||
* container, use eina_iterator_foreach().
|
* the documentation of the container type you're using. Though created with
|
||||||
|
* container specific functions iterators are always deleted with the same
|
||||||
|
* function: eina_iterator_free().
|
||||||
|
*
|
||||||
|
* To get the data and iterate, use eina_iterator_next(). To call a function on
|
||||||
|
* all the elements of a container, use eina_iterator_foreach().
|
||||||
*
|
*
|
||||||
* Here an @ref eina_iterator_example_page "example"
|
* Here an @ref eina_iterator_example_page "example"
|
||||||
*/
|
*/
|
||||||
|
@ -147,6 +152,8 @@ typedef Eina_Bool (*Eina_Iterator_Lock_Callback)(Eina_Iterator *it);
|
||||||
/**
|
/**
|
||||||
* @struct _Eina_Iterator
|
* @struct _Eina_Iterator
|
||||||
* structure of an iterator
|
* structure of an iterator
|
||||||
|
*
|
||||||
|
* If creating an iterator remember to set the type using @ref EINA_MAGIC_SET.
|
||||||
*/
|
*/
|
||||||
struct _Eina_Iterator
|
struct _Eina_Iterator
|
||||||
{
|
{
|
||||||
|
|
Loading…
Reference in New Issue