Tizen Native API  5.0

Eina_Clist is a compact (inline) list implementation.

Elements of this list are members of the structs stored in the list.

Advantages over Eina_List and Eina_Inlist :

  • Uses less memory (two machine words per item).
  • Allows removing items without knowing which list they're in while using O(1) time.
  • Doesn't need to keep updating the head pointer as the list is changed.

Disadvantages:

  • O(N) time to calculate the list length.
  • Requires one list entry in a struct per list (i.e. it's an inlist).
  • Requires a head/tail pointer.
  • Needs to know the list head when moving to the next or previous pointer.
Note:
There's no NULL at the end of the list, the last item points to the head.
List heads must be initialized with EINA_CLIST_INIT or by calling eina_clist_element_init.

Define a list as follows:

   struct gadget
   {
       struct Eina_Clist  entry;   <-- doesn't have to be the first item in the struct
       int                a, b;
   };

   static Eina_Clist global_gadgets = EINA_CLIST_INIT( global_gadgets );

or

   struct some_global_thing
   {
       Eina_Clist gadgets;
   };

   eina_clist_init( &some_global_thing->gadgets );

Manipulate it like this:

   eina_clist_add_head( &global_gadgets, &new_gadget->entry );
   eina_clist_remove( &new_gadget->entry );
   eina_clist_add_after( &some_random_gadget->entry, &new_gadget->entry );

And to iterate over it:

   struct gadget *gadget;
   EINA_CLIST_FOR_EACH_ENTRY( gadget, &global_gadgets, struct gadget, entry )
   {
       ...
   }

Functions

static void eina_clist_add_after (Eina_Clist *elem, Eina_Clist *to_add)
 Adds an element after the specified one.
static void eina_clist_add_before (Eina_Clist *elem, Eina_Clist *to_add)
 Adds an element before the specified one.
static void eina_clist_add_head (Eina_Clist *list, Eina_Clist *elem)
 Adds an element to the head of the list.
static void eina_clist_add_tail (Eina_Clist *list, Eina_Clist *elem)
 Adds an element at the tail of the list.
static void eina_clist_element_init (Eina_Clist *elem)
 Inits an (unlinked) element.
static int eina_clist_element_is_linked (Eina_Clist *elem)
 Checks whether an element is in a list.
static void eina_clist_remove (Eina_Clist *elem)
 Removes an element from its list.
static Eina_Clisteina_clist_next (const Eina_Clist *list, const Eina_Clist *elem)
 Gets the next element.
static Eina_Clisteina_clist_prev (const Eina_Clist *list, const Eina_Clist *elem)
 Gets the previous element.
static Eina_Clisteina_clist_head (const Eina_Clist *list)
 Gets the first element.
static Eina_Clisteina_clist_tail (const Eina_Clist *list)
 Gets the last element.
static int eina_clist_empty (const Eina_Clist *list)
 Checks whether a list is empty.
static void eina_clist_init (Eina_Clist *list)
 Initializes a list.
static unsigned int eina_clist_count (const Eina_Clist *list)
 Counts the elements of a list.
static void eina_clist_move_tail (Eina_Clist *dst, Eina_Clist *src)
 Moves all elements from src to the tail of dst.
static void eina_clist_move_head (Eina_Clist *dst, Eina_Clist *src)
 Moves all elements from src to the head of dst.

Typedefs

typedef struct _Eina_Clist Eina_Clist
 Type for _Eina_Clist structure containing the list head and the list entry.

Defines

#define EINA_CLIST_FOR_EACH(cursor, list)   for ((cursor) = (list)->next; (cursor) != (list); (cursor) = (cursor)->next)
 Iterates through the list.
#define EINA_CLIST_FOR_EACH_SAFE(cursor, cursor2, list)
 Iterates through the list, with safety against removal.
#define EINA_CLIST_FOR_EACH_ENTRY(elem, list, type, field)
 Iterates through the list using a list entry.
#define EINA_CLIST_FOR_EACH_ENTRY_SAFE(cursor, cursor2, list, type, field)
 Iterates through the list using a list entry, with safety against removal.
#define EINA_CLIST_FOR_EACH_REV(cursor, list)   for ((cursor) = (list)->prev; (cursor) != (list); (cursor) = (cursor)->prev)
 Iterates through the list in the reverse order.
#define EINA_CLIST_FOR_EACH_SAFE_REV(cursor, cursor2, list)
 Iterates through the list in the reverse order, with safety against removal.
#define EINA_CLIST_FOR_EACH_ENTRY_REV(elem, list, type, field)
 Iterates through the list in the reverse order using a list entry.
#define EINA_CLIST_FOR_EACH_ENTRY_SAFE_REV(cursor, cursor2, list, type, field)
 Iterates through the list in the reverse order using a list entry, with safety against removal.
#define EINA_CLIST_INIT(list)   { &(list), &(list) }
 Macros for statically initialized lists.
#define EINA_CLIST_ENTRY(elem, type, field)   ((type *)((char *)(elem) - (uintptr_t)(&((type *)0)->field)))
 Gets a pointer to the object containing the list element.

Define Documentation

#define EINA_CLIST_ENTRY (   elem,
  type,
  field 
)    ((type *)((char *)(elem) - (uintptr_t)(&((type *)0)->field)))

Gets a pointer to the object containing the list element.

Parameters:
[out]elemThe element to be used
[in]typeThe type of the element
[in]fieldThe field of the element
#define EINA_CLIST_FOR_EACH (   cursor,
  list 
)    for ((cursor) = (list)->next; (cursor) != (list); (cursor) = (cursor)->next)

Iterates through the list.

Parameters:
[out]cursorThe pointer to be used during the interaction
[in]listThe list to be interacted with
#define EINA_CLIST_FOR_EACH_ENTRY (   elem,
  list,
  type,
  field 
)
Value:
for ((elem) = EINA_CLIST_ENTRY((list)->next, type, field); \
         &(elem)->field != (list); \
         (elem) = EINA_CLIST_ENTRY((elem)->field.next, type, field))

Iterates through the list using a list entry.

Parameters:
[out]elemThe element to be used
[in]listThe list to be iterated
[in]typeThe type of the list
[in]fieldThe field of the element
#define EINA_CLIST_FOR_EACH_ENTRY_REV (   elem,
  list,
  type,
  field 
)
Value:
for ((elem) = EINA_CLIST_ENTRY((list)->prev, type, field); \
         &(elem)->field != (list); \
         (elem) = EINA_CLIST_ENTRY((elem)->field.prev, type, field))

Iterates through the list in the reverse order using a list entry.

Parameters:
[out]elemThe element to be used
[in]listThe list to be iterated
[in]typeThe type of the list
[in]fieldThe field of the element
#define EINA_CLIST_FOR_EACH_ENTRY_SAFE (   cursor,
  cursor2,
  list,
  type,
  field 
)
Value:
for ((cursor) = EINA_CLIST_ENTRY((list)->next, type, field), \
         (cursor2) = EINA_CLIST_ENTRY((cursor)->field.next, type, field); \
         &(cursor)->field != (list); \
         (cursor) = (cursor2), \
         (cursor2) = EINA_CLIST_ENTRY((cursor)->field.next, type, field))

Iterates through the list using a list entry, with safety against removal.

Parameters:
[out]cursorThe pointer to be used during the interaction
[out]cursor2The auxiliary pointer to be used during the interaction
[in]listThe list to be interacted with
[in]typeThe type of the list
[in]fieldThe field of the element
#define EINA_CLIST_FOR_EACH_ENTRY_SAFE_REV (   cursor,
  cursor2,
  list,
  type,
  field 
)
Value:
for ((cursor) = EINA_CLIST_ENTRY((list)->prev, type, field), \
         (cursor2) = EINA_CLIST_ENTRY((cursor)->field.prev, type, field); \
         &(cursor)->field != (list); \
         (cursor) = (cursor2), \
         (cursor2) = EINA_CLIST_ENTRY((cursor)->field.prev, type, field))

Iterates through the list in the reverse order using a list entry, with safety against removal.

Parameters:
[out]cursorThe pointer to be used during the interaction
[out]cursor2The auxiliary pointer to be used during the interaction
[in]listThe list to be interacted with
[in]typeThe type of the list
[in]fieldThe field of the element
#define EINA_CLIST_FOR_EACH_REV (   cursor,
  list 
)    for ((cursor) = (list)->prev; (cursor) != (list); (cursor) = (cursor)->prev)

Iterates through the list in the reverse order.

Parameters:
[out]cursorThe pointer to be used during the interaction
[in]listThe list to be interacted with
#define EINA_CLIST_FOR_EACH_SAFE (   cursor,
  cursor2,
  list 
)
Value:
for ((cursor) = (list)->next, (cursor2) = (cursor)->next; \
         (cursor) != (list); \
         (cursor) = (cursor2), (cursor2) = (cursor)->next)

Iterates through the list, with safety against removal.

Parameters:
[out]cursorThe pointer to be used during the interaction
[out]cursor2The auxiliary pointer to be used during the interaction
[in]listThe list to be interacted with
#define EINA_CLIST_FOR_EACH_SAFE_REV (   cursor,
  cursor2,
  list 
)
Value:
for ((cursor) = (list)->prev, (cursor2) = (cursor)->prev; \
         (cursor) != (list); \
         (cursor) = (cursor2), (cursor2) = (cursor)->prev)

Iterates through the list in the reverse order, with safety against removal.

Parameters:
[out]cursorThe pointer to be used during the interaction
[out]cursor2The auxiliary pointer to be used during the interaction
[in]listThe list to be interacted with
#define EINA_CLIST_INIT (   list)    { &(list), &(list) }

Macros for statically initialized lists.

Parameters:
[in,out]listThe list to be used

Typedef Documentation

Type for _Eina_Clist structure containing the list head and the list entry.

Since (EFL) :
1.1.0

Function Documentation

static void eina_clist_add_after ( Eina_Clist elem,
Eina_Clist to_add 
) [static]

Adds an element after the specified one.

Parameters:
[in,out]elemAn element in the list
[in]to_addThe element to add to the list
Precondition:
The list head must be initialized once before adding anything.
The element is not in any list.
Note:
There is no need to initialize an element before adding it to the list.
Since (EFL) :
1.1.0
static void eina_clist_add_before ( Eina_Clist elem,
Eina_Clist to_add 
) [static]

Adds an element before the specified one.

Parameters:
[in,out]elemAn element in the list
[in]to_addThe element to add to the list
Precondition:
The list head must be initialized once before adding anything.
The element is not in any list.
Note:
There is no need to initialize an element before adding it to the list.
Since (EFL) :
1.1.0
static void eina_clist_add_head ( Eina_Clist list,
Eina_Clist elem 
) [static]

Adds an element to the head of the list.

Parameters:
[in,out]listThe list
[in]elemAn element
Precondition:
The list head must be initialized once before adding anything.
The element is not in any list.
Note:
There is no need to initialize an element before adding it to the list.
Since (EFL) :
1.1.0
static void eina_clist_add_tail ( Eina_Clist list,
Eina_Clist elem 
) [static]

Adds an element at the tail of the list.

Parameters:
[in,out]listThe list
[in]elemAn element
Precondition:
The list head must be initialized once before adding anything.
The element is not in any list.
Note:
There is no need to initialize an element before adding it to the list.
Since (EFL) :
1.1.0
static unsigned int eina_clist_count ( const Eina_Clist list) [static]

Counts the elements of a list.

Parameters:
[in]listThe list
Returns:
The number of items in the list
Since (EFL) :
1.1.0
static void eina_clist_element_init ( Eina_Clist elem) [static]

Inits an (unlinked) element.

This function is called on elements that have not been added to the list so that eina_clist_element_init() works correctly.

Parameters:
[in,out]elemAn element
Precondition:
The element is not in any list.
Postcondition:
The element is marked as not being in any list.
Note:
It is not necessary to call this before adding an element to this list.
Since (EFL) :
1.1.0
static int eina_clist_element_is_linked ( Eina_Clist elem) [static]

Checks whether an element is in a list.

Parameters:
[in]elemAn element
Returns:
TRUE if the element is in a list, else FALSE.
Precondition:
Either eina_clist_element_init() has been called on elem, or it has been added to a list or removed from a list.
Since (EFL) :
1.1.0
static int eina_clist_empty ( const Eina_Clist list) [static]

Checks whether a list is empty.

Parameters:
[in]listThe list
Returns:
A non-zero value if list is empty, otherwise zero if it is not
Since (EFL) :
1.1.0
static Eina_Clist* eina_clist_head ( const Eina_Clist list) [static]

Gets the first element.

Parameters:
[in]listThe list
Returns:
The first element in list, otherwise NULL if list is empty
Since (EFL) :
1.1.0
static void eina_clist_init ( Eina_Clist list) [static]

Initializes a list.

Parameters:
[in,out]listThe list
Precondition:
The list is uninitialized
Postcondition:
The list contains no items
Note:
Don't call this function on a list with items
This function must be called. Don't try to initialize the list by zeroing out the list head.
Since (EFL) :
1.1.0
static void eina_clist_move_head ( Eina_Clist dst,
Eina_Clist src 
) [static]

Moves all elements from src to the head of dst.

Parameters:
[in,out]dstThe list to be prepended to
[in]srcThe list to prepend
Postcondition:
src is initialized, but is empty after this operation.
Since (EFL) :
1.1.0
static void eina_clist_move_tail ( Eina_Clist dst,
Eina_Clist src 
) [static]

Moves all elements from src to the tail of dst.

Parameters:
[in,out]dstThe list to be appended to
[in]srcThe list to append
Postcondition:
src is initialized, but is empty after this operation.
Since (EFL) :
1.1.0
static Eina_Clist* eina_clist_next ( const Eina_Clist list,
const Eina_Clist elem 
) [static]

Gets the next element.

Parameters:
[in]listThe list
[in]elemAn element
Returns:
The element after elem in list, otherwise NULL if elem is last in list
Precondition:
elem is in list.
Since (EFL) :
1.1.0
static Eina_Clist* eina_clist_prev ( const Eina_Clist list,
const Eina_Clist elem 
) [static]

Gets the previous element.

Parameters:
[in]listThe list
[in]elemAn element
Returns:
The element before elem, otherwise NULL if elem is first in list
Since (EFL) :
1.1.0
static void eina_clist_remove ( Eina_Clist elem) [static]

Removes an element from its list.

Parameters:
[in,out]elemAn element
Precondition:
The element is already in a list.
Postcondition:
The element is marked as not being in any list.
Since (EFL) :
1.1.0
static Eina_Clist* eina_clist_tail ( const Eina_Clist list) [static]

Gets the last element.

Parameters:
[in]listThe list
Returns:
The last element in list, otherwise NULL if list is empty
Since (EFL) :
1.1.0