Compact List

Data Structures | Macros | Typedefs | Functions
Compact List
Eina » Data Types » Containers

Eina_Clist is a compact (inline) list implementation. More...

## Data Structures
struct | _Eina_Clist
| The structure type for a compact list type. More...

## Macros
#define | EINA_CLIST_FOR_EACH(cursor, list) for ((cursor) = (list)->next; (cursor) != (list); (cursor) = (cursor)->next)
| Iterates through the list. More...
#define | EINA_CLIST_FOR_EACH_SAFE(cursor, cursor2, list)
| Iterates through the list, with safety against removal. More...
#define | EINA_CLIST_FOR_EACH_ENTRY(elem, list, type, field)
| Iterates through the list using a list entry. More...
#define | EINA_CLIST_FOR_EACH_ENTRY_SAFE(cursor, cursor2, list, type, field)
| Iterates through the list using a list entry, with safety against removal. More...
#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. More...
#define | EINA_CLIST_FOR_EACH_SAFE_REV(cursor, cursor2, list)
| Iterates through the list in the reverse order, with safety against removal. More...
#define | EINA_CLIST_FOR_EACH_ENTRY_REV(elem, list, type, field)
| Iterates through the list in the reverse order using a list entry. More...
#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. More...
#define | EINA_CLIST_INIT(list) { &(list), &(list) }
| Macros for statically initialized lists. More...
#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. More...

## Typedefs
typedef struct _Eina_Clist | Eina_Clist
| Type for _Eina_Clist structure containing the list head and the list entry. More...

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

## Detailed Description

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 );
_Eina_Clist
The structure type for a compact list type.
Definition: eina_clist.h:109

or

struct some_global_thing
{
Eina_Clist gadgets;
};
eina_clist_init( &some_global_thing->gadgets );
eina_clist_init
static void eina_clist_init(Eina_Clist *list)
Initializes a list.

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 );
eina_clist_remove
static void eina_clist_remove(Eina_Clist *elem)
Removes an element from its list.
eina_clist_add_after
static void eina_clist_add_after(Eina_Clist *elem, Eina_Clist *to_add)
Adds an element after the specified one.
eina_clist_add_head
static void eina_clist_add_head(Eina_Clist *list, Eina_Clist *elem)
Adds an element to the head of the list.

And to iterate over it:

struct gadget *gadget;
EINA_CLIST_FOR_EACH_ENTRY( gadget, &global_gadgets, struct gadget, entry )
{
...
}
EINA_CLIST_FOR_EACH_ENTRY
#define EINA_CLIST_FOR_EACH_ENTRY(elem, list, type, field)
Iterates through the list using a list entry.
Definition: eina_clist.h:343

## Macro Definition Documentation

## ◆ EINA_CLIST_FOR_EACH

#define EINA_CLIST_FOR_EACH | ( |  | cursor,
|  |  | list
| ) |  | for ((cursor) = (list)->next; (cursor) != (list); (cursor) = (cursor)->next)

Iterates through the list.

Parameters

  [out] | cursor | The pointer to be used during the interaction
  [in] | list | The list to be interacted with

## ◆ EINA_CLIST_FOR_EACH_SAFE

#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] | cursor | The pointer to be used during the interaction
  [out] | cursor2 | The auxiliary pointer to be used during the interaction
  [in] | list | The list to be interacted with

## ◆ EINA_CLIST_FOR_EACH_ENTRY

#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))
EINA_CLIST_ENTRY
#define EINA_CLIST_ENTRY(elem, type, field)
Gets a pointer to the object containing the list element.
Definition: eina_clist.h:438

Iterates through the list using a list entry.

Parameters

  [out] | elem | The element to be used
  [in] | list | The list to be iterated
  [in] | type | The type of the list
  [in] | field | The field of the element

## ◆ EINA_CLIST_FOR_EACH_ENTRY_SAFE

#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] | cursor | The pointer to be used during the interaction
  [out] | cursor2 | The auxiliary pointer to be used during the interaction
  [in] | list | The list to be interacted with
  [in] | type | The type of the list
  [in] | field | The field of the element

## ◆ EINA_CLIST_FOR_EACH_REV

#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] | cursor | The pointer to be used during the interaction
  [in] | list | The list to be interacted with

## ◆ EINA_CLIST_FOR_EACH_SAFE_REV

#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] | cursor | The pointer to be used during the interaction
  [out] | cursor2 | The auxiliary pointer to be used during the interaction
  [in] | list | The list to be interacted with

## ◆ EINA_CLIST_FOR_EACH_ENTRY_REV

#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] | elem | The element to be used
  [in] | list | The list to be iterated
  [in] | type | The type of the list
  [in] | field | The field of the element

## ◆ EINA_CLIST_FOR_EACH_ENTRY_SAFE_REV

#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] | cursor | The pointer to be used during the interaction
  [out] | cursor2 | The auxiliary pointer to be used during the interaction
  [in] | list | The list to be interacted with
  [in] | type | The type of the list
  [in] | field | The field of the element

## ◆ EINA_CLIST_INIT

#define EINA_CLIST_INIT | ( |  | list | ) | { &(list), &(list) }

Macros for statically initialized lists.

Parameters

  [in,out] | list | The list to be used

## ◆ EINA_CLIST_ENTRY

#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] | elem | The element to be used
  [in] | type | The type of the element
  [in] | field | The field of the element

## Typedef Documentation

## ◆ Eina_Clist

Eina_Clist

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

Since
  1.1.0

## Function Documentation

## ◆ eina_clist_add_after()

static void eina_clist_add_after | ( | Eina_Clist * | elem,
|  | Eina_Clist * | to_add
| ) |  |
| inlinestatic

Adds an element after the specified one.

Parameters

  [in,out] | elem | An element in the list
  [in] | to_add | The 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
  1.1.0

## ◆ eina_clist_add_before()

static void eina_clist_add_before | ( | Eina_Clist * | elem,
|  | Eina_Clist * | to_add
| ) |  |
| inlinestatic

Adds an element before the specified one.

Parameters

  [in,out] | elem | An element in the list
  [in] | to_add | The 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
  1.1.0

## ◆ eina_clist_add_head()

static void eina_clist_add_head | ( | Eina_Clist * | list,
|  | Eina_Clist * | elem
| ) |  |
| inlinestatic

Adds an element to the head of the list.

Parameters

  [in,out] | list | The list
  [in] | elem | An 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
  1.1.0

## ◆ eina_clist_add_tail()

static void eina_clist_add_tail | ( | Eina_Clist * | list,
|  | Eina_Clist * | elem
| ) |  |
| inlinestatic

Adds an element at the tail of the list.

Parameters

  [in,out] | list | The list
  [in] | elem | An 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
  1.1.0

## ◆ eina_clist_element_init()

static void eina_clist_element_init | ( | Eina_Clist * | elem | ) |
| inlinestatic

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] | elem | An 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
  1.1.0

## ◆ eina_clist_element_is_linked()

static int eina_clist_element_is_linked | ( | Eina_Clist * | elem | ) |
| inlinestatic

Checks whether an element is in a list.

Parameters

  [in] | elem | An 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
  1.1.0

## ◆ eina_clist_remove()

static void eina_clist_remove | ( | Eina_Clist * | elem | ) |
| inlinestatic

Removes an element from its list.

Parameters

  [in,out] | elem | An element

Precondition
  The element is already in a list.

Postcondition
  The element is marked as not being in any list.

Since
  1.1.0

## ◆ eina_clist_next()

static Eina_Clist* eina_clist_next | ( | const Eina_Clist * | list,
|  | const Eina_Clist * | elem
| ) |  |
| inlinestatic

Gets the next element.

Parameters

  [in] | list | The list
  [in] | elem | An element

Returns
  The element after `elem` in `list`, otherwise `NULL` if `elem` is last in `list`

Precondition
  `elem` is in `list`.

Since
  1.1.0

## ◆ eina_clist_prev()

static Eina_Clist* eina_clist_prev | ( | const Eina_Clist * | list,
|  | const Eina_Clist * | elem
| ) |  |
| inlinestatic

Gets the previous element.

Parameters

  [in] | list | The list
  [in] | elem | An element

Returns
  The element before `elem`, otherwise `NULL` if `elem` is first in `list`

Since
  1.1.0

## ◆ eina_clist_head()

static Eina_Clist* eina_clist_head | ( | const Eina_Clist * | list | ) |
| inlinestatic

Gets the first element.

Parameters

  [in] | list | The list

Returns
  The first element in `list`, otherwise `NULL` if `list` is empty

Since
  1.1.0

## ◆ eina_clist_tail()

static Eina_Clist* eina_clist_tail | ( | const Eina_Clist * | list | ) |
| inlinestatic

Gets the last element.

Parameters

  [in] | list | The list

Returns
  The last element in `list`, otherwise `NULL` if `list` is empty

Since
  1.1.0

## ◆ eina_clist_empty()

static int eina_clist_empty | ( | const Eina_Clist * | list | ) |
| inlinestatic

Checks whether a list is empty.

Parameters

  [in] | list | The list

Returns
  A non-zero value if `list` is empty, otherwise zero if it is not

Since
  1.1.0

## ◆ eina_clist_init()

static void eina_clist_init | ( | Eina_Clist * | list | ) |
| inlinestatic

Initializes a list.

Parameters

  [in,out] | list | The 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
  1.1.0

## ◆ eina_clist_count()

static unsigned int eina_clist_count | ( | const Eina_Clist * | list | ) |
| inlinestatic

Counts the elements of a list.

Parameters

  [in] | list | The list

Returns
  The number of items in the list

Since
  1.1.0

## ◆ eina_clist_move_tail()

static void eina_clist_move_tail | ( | Eina_Clist * | dst,
|  | Eina_Clist * | src
| ) |  |
| inlinestatic

Moves all elements from `src` to the tail of `dst`.

Parameters

  [in,out] | dst | The list to be appended to
  [in] | src | The list to append

Postcondition
  `src` is initialized, but is empty after this operation.

Since
  1.1.0

## ◆ eina_clist_move_head()

static void eina_clist_move_head | ( | Eina_Clist * | dst,
|  | Eina_Clist * | src
| ) |  |
| inlinestatic

Moves all elements from `src` to the head of `dst`.

Parameters

  [in,out] | dst | The list to be prepended to
  [in] | src | The list to prepend

Postcondition
  `src` is initialized, but is empty after this operation.

Since
  1.1.0