List

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

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

These functions provide double linked list management. More...

## Data Structures
struct | _Eina_List
| Type for a generic double linked list. More...
struct | _Eina_List_Accounting
| Cache used to store the last element of a list and the number of elements, for fast access. More...

## Macros
#define | EINA_LIST_FOREACH(list, l, _data)
| Definition for the macro to iterate over a list.
#define | EINA_LIST_REVERSE_FOREACH(list, l, _data)
| Definition for the macro to iterate over a list in the reverse order.
#define | EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
| Definition for the macro to iterate over a list with support for node deletion.
#define | EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
| Definition for the macro to iterate over a list in the reverse order with support for deletion.
#define | EINA_LIST_FREE(list, data)
| Definition for the macro to remove each list node while having access to each node's data.

## Typedefs
typedef struct _Eina_List | Eina_List
| Type for a generic double linked list.
typedef struct _Eina_List_Accounting | Eina_List_Accounting
| Cache used to store the last element of a list and the number of elements, for fast access.

## Functions
EINA_API Eina_List * | eina_list_append (Eina_List *list, const void *data)
| Appends the given data to the given linked list.
EINA_API Eina_List * | eina_list_prepend (Eina_List *list, const void *data)
| Prepends the given data to the given linked list.
EINA_API Eina_List * | eina_list_append_relative (Eina_List *list, const void *data, const void *relative)
| Inserts the given data into the given linked list after the specified data.
EINA_API Eina_List * | eina_list_append_relative_list (Eina_List *list, const void *data, Eina_List *relative)
| Appends a list node to a linked list after the specified member.
EINA_API Eina_List * | eina_list_prepend_relative (Eina_List *list, const void *data, const void *relative)
| Prepends a data pointer to a linked list before the specified member.
EINA_API Eina_List * | eina_list_prepend_relative_list (Eina_List *list, const void *data, Eina_List *relative)
| Prepends a list node to a linked list before the specified member.
EINA_API Eina_List * | eina_list_sorted_insert (Eina_List *list, Eina_Compare_Cb func, const void *data)
| Inserts a new node into a sorted list.
EINA_API Eina_List * | eina_list_remove (Eina_List *list, const void *data)
| Removes the first instance of the specified data from the given list.
EINA_API Eina_List * | eina_list_remove_list (Eina_List *list, Eina_List *remove_list)
| Removes the specified list node.
EINA_API Eina_List * | eina_list_promote_list (Eina_List *list, Eina_List *move_list)
| Moves the specified data to the head of the list.
EINA_API Eina_List * | eina_list_demote_list (Eina_List *list, Eina_List *move_list)
| Moves the specified data to the tail of the list.
EINA_API void * | eina_list_data_find (const Eina_List *list, const void *data)
| Finds a member of a list and returns it.
EINA_API Eina_List * | eina_list_data_find_list (const Eina_List *list, const void *data)
| Finds a member of a list and returns it as a list node.
EINA_API Eina_Bool | eina_list_move (Eina_List **to, Eina_List **from, void *data)
| Moves a data pointer from one list to another.
EINA_API Eina_Bool | eina_list_move_list (Eina_List **to, Eina_List **from, Eina_List *data)
| Moves a list node from one list to another.
EINA_API Eina_List * | eina_list_free (Eina_List *list)
| Frees an entire list and all the nodes, ignoring the data contained.
EINA_API void * | eina_list_nth (const Eina_List *list, unsigned int n)
| Gets the nth member's data pointer in a list, or `NULL` on error.
EINA_API Eina_List * | eina_list_nth_list (const Eina_List *list, unsigned int n)
| Gets the nth member's list node in a list.
EINA_API Eina_List * | eina_list_reverse (Eina_List *list)
| Reverses all the elements in the list.
EINA_API Eina_List * | eina_list_reverse_clone (const Eina_List *list)
| Clones (copies) all the elements in the list in reverse order.
EINA_API Eina_List * | eina_list_clone (const Eina_List *list)
| Clones (copies) all the elements in the list in exactly same order.
EINA_API Eina_List * | eina_list_sort (Eina_List *list, unsigned int limit, Eina_Compare_Cb func)
| Sorts a list according to the ordering func will return.
EINA_API Eina_List * | eina_list_shuffle (Eina_List *list, Eina_Random_Cb func)
| Shuffles list.
EINA_API Eina_List * | eina_list_merge (Eina_List *left, Eina_List *right)
| Merges two list.
EINA_API Eina_List * | eina_list_sorted_merge (Eina_List *left, Eina_List *right, Eina_Compare_Cb func)
| Merges two sorted list according to the ordering func will return.
EINA_API Eina_List * | eina_list_split_list (Eina_List *list, Eina_List *relative, Eina_List **right)
| Splits a list into 2 lists.
EINA_API Eina_List * | eina_list_search_sorted_near_list (const Eina_List *list, Eina_Compare_Cb func, const void *data, int *result_cmp)
| Returns node nearest to data from the sorted list.
EINA_API Eina_List * | eina_list_search_sorted_list (const Eina_List *list, Eina_Compare_Cb func, const void *data)
| Returns node if data is in the sorted list.
EINA_API void * | eina_list_search_sorted (const Eina_List *list, Eina_Compare_Cb func, const void *data)
| Returns node data if it is in the sorted list.
EINA_API Eina_List * | eina_list_search_unsorted_list (const Eina_List *list, Eina_Compare_Cb func, const void *data)
| Returns node if data is in the unsorted list.
EINA_API void * | eina_list_search_unsorted (const Eina_List *list, Eina_Compare_Cb func, const void *data)
| Returns node data if it is in the unsorted list.
static Eina_List * | eina_list_last (const Eina_List *list)
| Gets the last list node in the list.
static Eina_List * | eina_list_next (const Eina_List *list)
| Gets the next list node after the specified list node.
static Eina_List * | eina_list_prev (const Eina_List *list)
| Gets the list node prior to the specified list node.
static void * | eina_list_data_get (const Eina_List *list)
| Gets the list node data member.
static void * | eina_list_data_set (Eina_List *list, const void *data)
| Sets the list node data member.
static unsigned int | eina_list_count (const Eina_List *list)
| Gets the count of the number of items in a list.
static void * | eina_list_last_data_get (const Eina_List *list)
| Returns the last list node's data.
EINA_API Eina_Iterator * | eina_list_iterator_new (const Eina_List *list)
| Returns a new iterator associated with a list.
EINA_API Eina_Iterator * | eina_list_iterator_reversed_new (const Eina_List *list)
| Returns a new reversed iterator associated with a list.
EINA_API Eina_Accessor * | eina_list_accessor_new (const Eina_List *list)
| Returns a new accessor associated with a list.
EINA_API int | eina_list_data_idx (const Eina_List *list, void *data)
| Finds the member of the list and returns the index.

## Detailed Description

These functions provide double linked list management.

Eina_List is a doubly linked list. It can store data of any type in the form of void pointers. It has convenience functions to do all the common operations which means it should rarely if ever be necessary to directly access the struct's fields. Nevertheless it can be useful to understand the inner workings of the data structure being used.

Eina_List nodes keep references to the previous node, the next node, its data and to an accounting structure.

Eina_List_Accounting is used to improve the performance of some functions. It is private and should not be modified. It contains a reference to the end of the list and the number of elements in the list.

Note
  Every function that modifies the contents of the list returns a pointer to the head of the list and it is essential that this be pointer be used in any future references to the list.

Most functions have two versions that have the same effect but operate on different arguments, the plain functions operate over data(e.g..: eina_list_append_relative, eina_list_remove, eina_list_data_find), the list versions of these functions operate on Eina_List nodes.

Warning
  You must always use the pointer to the first element of the list as the list!
  You must never use a pointer to an element in the middle of the list as the list!

Here are some examples of Eina_List usage:

- Adding elements to Eina_List
- Sorting Eina_List elements
- Reordering Eina_List elements
- Eina_List and memory allocation

## Macro Definition Documentation

## ◆ EINA_LIST_FOREACH

#define EINA_LIST_FOREACH | ( |  | list,
|  |  | l,
|  |  | _data
| ) |  |

Value:
for (l = list, \
_data = eina_list_data_get(l), \
l ? (EINA_PREFETCH(((Eina_List *)l)->next), EINA_PREFETCH(_data)) : EINA_PREFETCH(l); \
\
l; \
\
l = eina_list_next(l), \
_data = eina_list_data_get(l), \
l ? (EINA_PREFETCH(((Eina_List *)l)->next), EINA_PREFETCH(_data)) : EINA_PREFETCH(l))
eina_list_data_get
static void * eina_list_data_get(const Eina_List *list)
Gets the list node data member.
eina_list_next
static Eina_List * eina_list_next(const Eina_List *list)
Gets the next list node after the specified list node.
EINA_PREFETCH
#define EINA_PREFETCH(arg)
Hints that the pointer arg needs to be pre-fetched into cache.
Definition: eina_types.h:468
_Eina_List
Type for a generic double linked list.
Definition: eina_list.h:318

Definition for the macro to iterate over a list.

Parameters

  [in] | list | The list to iterate over.
  [out] | l | A list that is used as an iterator and points to the current node.
  [out] | _data | Current item's data.

This macro iterates over `list` from the first element to the last. `data` is the data related to the current element. `l` is an Eina_List used as the list iterator.

The following diagram illustrates this macro iterating over a list of four elements("one", "two", "three" and "four"):

It can be used to free list data, as in the following example:

Eina_List *list;
Eina_List *l;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_FOREACH will be used to free those strings
EINA_LIST_FOREACH(list, l, data)
free(data);
eina_list_free(list);
eina_list_free
EINA_API Eina_List * eina_list_free(Eina_List *list)
Frees an entire list and all the nodes, ignoring the data contained.
Definition: eina_list.c:823
EINA_LIST_FOREACH
#define EINA_LIST_FOREACH(list, l, _data)
Definition for the macro to iterate over a list.
Definition: eina_list.h:1415

Note
  This is not the optimal way to release memory allocated to a list, since it iterates over the list twice. For an optimized algorithm, use EINA_LIST_FREE().

Warning
  `list` must be a pointer to the first element of the list.
  Be careful when deleting list nodes. If you remove the current node and continue iterating, the code will fail because the macro will not be able to get the next node. Notice that it's OK to remove any node if you stop the loop after that. For destructive operations such as this, consider using EINA_LIST_FOREACH_SAFE().

Examples
  diskselector_example_02.c, ecore_con_server_simple_example.c, ecore_con_url_cookies_example.c, ecore_con_url_headers_example.c, ecore_evas_basics_example.c, ecore_imf_example.c, edje-box2.c, eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, eina_inlist_02.c, eina_list_01.c, emotion_test_main.c, entry_example.c, evas-box.c, evas-buffer-simple.c, evas-events.c, evas-init-shutdown.c, gengrid_example.c, genlist_example_02.c, genlist_example_05.c, hoversel_example_01.c, list_example_03.c, slideshow_example.c, test_growing_balls.c, and transit_example_04.c.

## ◆ EINA_LIST_REVERSE_FOREACH

#define EINA_LIST_REVERSE_FOREACH | ( |  | list,
|  |  | l,
|  |  | _data
| ) |  |

Value:
for (l = eina_list_last(list), \
_data = eina_list_data_get(l), \
l ? (EINA_PREFETCH(((Eina_List *)l)->prev), EINA_PREFETCH(_data)) : EINA_PREFETCH(l); \
l; \
l = eina_list_prev(l), \
_data = eina_list_data_get(l), \
l ? (EINA_PREFETCH(((Eina_List *)l)->prev), EINA_PREFETCH(_data)) : EINA_PREFETCH(l))
eina_list_prev
static Eina_List * eina_list_prev(const Eina_List *list)
Gets the list node prior to the specified list node.
eina_list_last
static Eina_List * eina_list_last(const Eina_List *list)
Gets the last list node in the list.

Definition for the macro to iterate over a list in the reverse order.

Parameters

  [in] | list | The list to iterate over.
  [out] | l | A list that is used as an iterator and points to the current node.
  [out] | _data | Current item's data.

This macro works like EINA_LIST_FOREACH, but iterates from the last element of a list to the first. `data` is the data related to the current element, while `l` is an Eina_List that is used as the list iterator.

The following diagram illustrates this macro iterating over a list of four elements("one", "two", "three" and "four"):

It can be used to free list data, as in the following example:

Eina_List *list;
Eina_List *l;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_REVERSE_FOREACH will be used to free those strings
EINA_LIST_REVERSE_FOREACH(list, l, data)
free(data);
eina_list_free(list);
EINA_LIST_REVERSE_FOREACH
#define EINA_LIST_REVERSE_FOREACH(list, l, _data)
Definition for the macro to iterate over a list in the reverse order.
Definition: eina_list.h:1474

Note
  This is not the optimal way to release memory allocated to a list, since it iterates over the list twice. For an optimized algorithm, use EINA_LIST_FREE().

Warning
  `list` must be a pointer to the first element of the list.
  Be careful when deleting list nodes. If you remove the current node and continue iterating, the code will fail because the macro will not be able to get the next node. Notice that it's OK to remove any node if you stop the loop after that. For destructive operations such as this, consider using EINA_LIST_REVERSE_FOREACH_SAFE().

## ◆ EINA_LIST_FOREACH_SAFE

#define EINA_LIST_FOREACH_SAFE | ( |  | list,
|  |  | l,
|  |  | l_next,
|  |  | data
| ) |  |

Value:
for (l = list, \
l_next = eina_list_next(l), \
EINA_PREFETCH(l_next), \
data = eina_list_data_get(l); \
EINA_PREFETCH(data), \
l; \
l = l_next, \
l_next = eina_list_next(l), \
EINA_PREFETCH(l_next), \
data = eina_list_data_get(l), \
EINA_PREFETCH(data))

Definition for the macro to iterate over a list with support for node deletion.

Parameters

  [in] | list | The list to iterate over.
  [out] | l | A list that is used as an iterator and points to the current node.
  [out] | l_next | A list that is used as an iterator and points to the next node.
  [out] | data | Current item's data.

This macro iterates over `list` from the first element to the last. `data` is the data related to the current element. `l` is an Eina_List used as the list iterator.

Since this macro stores a pointer to the next list node in `l_next`, deleting the current node and continuing looping is safe.

The following diagram illustrates this macro iterating over a list of four elements ("one", "two", "three" and "four"):

This macro can be used to free list nodes, as in the following example:

Eina_List *list;
Eina_List *l;
Eina_List *l_next;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_FOREACH_SAFE will be used to free elements that match "key".
EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
if (strcmp(data, "key") == 0)
{
free(data);
list = eina_list_remove_list(list, l);
}
EINA_LIST_FOREACH_SAFE
#define EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
Definition for the macro to iterate over a list with support for node deletion.
Definition: eina_list.h:1526
eina_list_remove_list
EINA_API Eina_List * eina_list_remove_list(Eina_List *list, Eina_List *remove_list)
Removes the specified list node.
Definition: eina_list.c:786

Warning
  `list` must be a pointer to the first element of the list.

Examples
  eina_inlist_02.c.

## ◆ EINA_LIST_REVERSE_FOREACH_SAFE

#define EINA_LIST_REVERSE_FOREACH_SAFE | ( |  | list,
|  |  | l,
|  |  | l_prev,
|  |  | data
| ) |  |

Value:
for (l = eina_list_last(list), \
l_prev = eina_list_prev(l), \
EINA_PREFETCH(l_prev), \
data = eina_list_data_get(l); \
EINA_PREFETCH(data), \
l; \
l = l_prev, \
l_prev = eina_list_prev(l), \
EINA_PREFETCH(l_prev), \
data = eina_list_data_get(l), \
EINA_PREFETCH(data))

Definition for the macro to iterate over a list in the reverse order with support for deletion.

Parameters

  [in] | list | The list to iterate over.
  [out] | l | A list that is used as an iterator and points to the current node.
  [out] | l_prev | A list that is used as an iterator and points to the previous node.
  [out] | data | Current item's data.

This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the last element of a list to the first. `data` is the data related to the current element, while `l` is an Eina_List that is used as the list iterator.

Since this macro stores a pointer to the previous list node in `l_prev`, deleting the current node and continuing looping is safe.

The following diagram illustrates this macro iterating over a list of four elements ("one", "two", "three" and "four"):

This macro can be used to free list nodes, as in the following example:

Eina_List *list;
Eina_List *l;
Eina_List *l_prev;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that match "key".
EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
if (strcmp(data, "key") == 0)
{
free(data);
list = eina_list_remove_list(list, l);
}
EINA_LIST_REVERSE_FOREACH_SAFE
#define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
Definition for the macro to iterate over a list in the reverse order with support for deletion.
Definition: eina_list.h:1584

Warning
  `list` must be a pointer to the first element of the list.

## ◆ EINA_LIST_FREE

#define EINA_LIST_FREE | ( |  | list,
|  |  | data
| ) |  |

Value:
for (data = eina_list_data_get(list), \
list ? EINA_PREFETCH(((Eina_List *)list)->next) : EINA_PREFETCH(list); \
list; \
list = eina_list_remove_list(list, list), \
list ? EINA_PREFETCH(((Eina_List *)list)->next) : EINA_PREFETCH(list), \
data = eina_list_data_get(list))

Definition for the macro to remove each list node while having access to each node's data.

Parameters

  [in,out] | list | The list that will be cleared.
  [out] | data | Current node's data.

This macro will call eina_list_remove_list for each list node, and store the data contained in the current node in `data`.

The following diagram illustrates this macro iterating over a list of four elements ("one", "two", "three" and "four"):

If you do not need to release node data, it is easier to call eina_list_free().

Eina_List *list;
char *data;
// list is already filled,
// its elements are just duplicated strings,
EINA_LIST_FREE(list, data)
free(data);
EINA_LIST_FREE
#define EINA_LIST_FREE(list, data)
Definition for the macro to remove each list node while having access to each node's data.
Definition: eina_list.h:1629

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_free()

Examples
  ecore_imf_example.c, ecore_thread_example.c, edje-color-class.c, eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, efl_thread_6.c, eina_list_04.c, eina_tiler_01.c, emotion_test_main.c, genlist_example_02.c, and genlist_example_05.c.

## Function Documentation

## ◆ eina_list_append()

EINA_API Eina_List * eina_list_append | ( | Eina_List * | list,
|  | const void * | data
| ) |  |

Appends the given data to the given linked list.

Parameters

  [in,out] | list | The given list.
  [in] | data | The data to append.

Returns
  A list pointer, or `NULL` on error.

This function appends `data` to `list`. If `list` is `NULL`, a new list is returned. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following example code demonstrates how to ensure that the given data has been successfully appended.

Eina_List *list = NULL;
extern void *my_data;
list = eina_list_append(list, my_data);
eina_list_append
EINA_API Eina_List * eina_list_append(Eina_List *list, const void *data)
Appends the given data to the given linked list.
Definition: eina_list.c:584

Warning
  `list` must be a pointer to the first element of the list(or NULL).

References _Eina_List::accounting, _Eina_List::data, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by ecore_con_eet_client_connect_callback_add(), ecore_con_eet_client_disconnect_callback_add(), ecore_con_eet_server_connect_callback_add(), ecore_con_eet_server_disconnect_callback_add(), ecore_con_lookup(), ecore_con_socks4_remote_add(), ecore_con_socks5_remote_add(), ecore_con_ssl_server_cafile_add(), ecore_con_ssl_server_cert_add(), ecore_con_ssl_server_crl_add(), ecore_con_ssl_server_privkey_add(), ecore_con_url_additional_header_add(), ecore_con_url_cookies_clear(), ecore_con_url_cookies_file_add(), ecore_con_url_cookies_init(), ecore_con_url_cookies_session_clear(), ecore_con_url_new(), ecore_drm2_plane_assign(), ecore_drm2_plane_fb_set(), ecore_drm2_plane_release(), ecore_drm_device_find(), ecore_evas_aux_hint_add(), ecore_evas_aux_hints_allowed_get(), ecore_evas_ecore_evas_list_get(), ecore_evas_vnc_start(), ecore_fb_input_device_open(), ecore_file_app_list(), ecore_file_download_full(), ecore_file_ls(), ecore_fork_reset_callback_add(), ecore_imf_context_event_callback_add(), ecore_imf_context_input_panel_event_callback_add(), ecore_ipc_server_add(), ecore_ipc_server_connect(), ecore_main_fd_handler_prepare_callback_set(), ecore_thread_feedback_run(), ecore_thread_run(), ecore_wl2_offer_receive(), ecore_wl2_window_aux_hints_supported_get(), edje_available_modules_get(), edje_edit_color_class_add(), edje_edit_color_classes_list_get(), edje_edit_data_list_get(), edje_edit_externals_list_get(), edje_edit_fonts_list_get(), edje_edit_group_aliases_get(), edje_edit_group_data_list_get(), edje_edit_image_set_image_add(), edje_edit_image_set_images_list_get(), edje_edit_image_set_list_get(), edje_edit_images_list_get(), edje_edit_part_items_list_get(), edje_edit_part_states_list_get(), edje_edit_parts_list_get(), edje_edit_program_after_add(), edje_edit_program_after_insert_at(), edje_edit_program_target_add(), edje_edit_program_target_insert_at(), edje_edit_programs_list_get(), edje_edit_size_class_add(), edje_edit_size_classes_list_get(), edje_edit_sound_samples_list_get(), edje_edit_sound_tones_list_get(), edje_edit_state_add(), edje_edit_state_external_param_set(), edje_edit_state_tweens_list_get(), edje_edit_style_add(), edje_edit_style_tag_add(), edje_edit_style_tags_list_get(), edje_edit_styles_list_get(), edje_edit_text_class_add(), edje_edit_text_classes_list_get(), edje_edit_vectors_list_get(), edje_mmap_collection_list(), edje_mmap_color_class_used_list(), edje_mmap_group_exists(), edje_object_access_part_list_get(), edje_object_perspective_set(), edje_object_text_insert_filter_callback_add(), edje_object_text_markup_filter_callback_add(), eet_eina_stream_data_descriptor_class_set(), eet_node_hash_new(), eet_node_list_append(), eeze_disk_eject(), eeze_disk_mount(), eeze_disk_new(), eeze_disk_new_from_mount(), eeze_disk_unmount(), eeze_net_list(), eeze_udev_find_by_filter(), eeze_udev_find_by_subsystem_sysname(), eeze_udev_find_by_sysattr(), eeze_udev_find_by_type(), eeze_udev_syspath_get_parents(), eeze_udev_syspath_get_sysattr_list(), efreet_desktop_category_add(), efreet_desktop_command_local_get(), efreet_desktop_command_progress_get(), efreet_desktop_string_list_parse(), efreet_desktop_type_add(), efreet_icon_list_find(), efreet_menu_desktop_insert(), efreet_menu_kde_legacy_init(), efreet_mime_type_icon_get(), efreet_util_desktop_categories_list(), efreet_util_desktop_environments_list(), efreet_util_desktop_exec_glob_list(), eina_benchmark_run(), eina_debug_opcodes_register(), eina_file_flush(), eina_hash_list_append(), eina_hash_list_direct_append(), eina_hash_list_direct_prepend(), eina_hash_list_prepend(), eina_list_append_relative(), eina_list_append_relative_list(), eina_list_clone(), eina_list_move(), eina_list_move_list(), eina_list_sorted_insert(), eina_multi_iterator_internal_new(), eina_rectangle_pool_new(), eldbus_connection_event_callback_del(), eldbus_name_owner_changed_callback_del(), eldbus_object_event_callback_del(), eldbus_object_signal_handler_add(), eldbus_proxy_event_callback_del(), eldbus_proxy_signal_handler_add(), elm_color_class_editor_add(), elm_color_class_util_edje_file_list(), elm_config_profile_derived_add(), elm_drag_item_container_add(), elm_drop_item_container_add(), elm_layout_content_swallow_list_get(), elm_prefs_data_event_callback_del(), elm_quicklaunch_exe_path_get(), elm_radio_group_add(), elm_theme_copy(), elm_theme_extension_list_get(), elm_theme_list_get(), elm_theme_name_available_list_new(), elm_theme_overlay_list_get(), elm_theme_ref_set(), elm_transit_chain_transit_add(), elm_transit_object_add(), elua_state_include_path_add(), elua_util_require(), eolian_aux_class_callables_get(), eolian_aux_state_class_children_find(), ethumb_client_ethumb_setup(), ethumb_client_generate_cancel(), ethumb_client_thumb_exists(), evas_device_add_full(), evas_font_path_global_append(), evas_object_box_children_get(), evas_object_clipees_get(), evas_object_image_video_surface_set(), evas_object_smart_members_get(), evas_object_textblock_cursor_new(), evas_textblock_cursor_range_formats_get(), and evas_textblock_cursor_range_simple_geometry_get().

## ◆ eina_list_prepend()

EINA_API Eina_List * eina_list_prepend | ( | Eina_List * | list,
|  | const void * | data
| ) |  |

Prepends the given data to the given linked list.

Parameters

  [in,out] | list | The given list.
  [in] | data | The data to prepend.

Returns
  A list pointer, or `NULL` on error.

This function prepends `data` to `list`. If `list` is `NULL`, a new list is returned. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following example code demonstrates how to ensure that the given data has been successfully prepended.

Example:

Eina_List *list = NULL;
extern void *my_data;
list = eina_list_prepend(list, my_data);
eina_list_prepend
EINA_API Eina_List * eina_list_prepend(Eina_List *list, const void *data)
Prepends the given data to the given linked list.
Definition: eina_list.c:618

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::data, _Eina_List::next, and _Eina_List::prev.

Referenced by edje_edit_group_add(), eet_node_struct_child_new(), eeze_udev_find_similar_from_syspath(), efreet_icon_extension_add(), eina_hash_list_direct_prepend(), eina_hash_list_prepend(), eina_list_prepend_relative(), eina_list_prepend_relative_list(), eina_list_reverse_clone(), evas_font_path_global_prepend(), evas_gl_context_version_create(), evas_gl_pbuffer_surface_create(), evas_gl_surface_create(), evas_post_event_callback_push(), and evas_textblock_node_format_remove_pair().

## ◆ eina_list_append_relative()

EINA_API Eina_List * eina_list_append_relative | ( | Eina_List * | list,
|  | const void * | data,
|  | const void * | relative
| ) |  |

Inserts the given data into the given linked list after the specified data.

Parameters

  [in,out] | list | The given linked list.
  [in] | data | The data to insert.
  [in] | relative | The data to insert after.

Returns
  A list pointer, or `NULL` on error.

This function inserts `data` into `list` after `relative`. If `relative` is not in the list, `data` is appended to the list. If `list` is `NULL`, a new list is returned. If there are multiple instances of `relative` in the list, `data` is inserted after the first instance. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following example code demonstrates how to ensure that the given data has been successfully inserted.

Eina_List *list = NULL;
extern void *my_data;
extern void *relative_member;
list = eina_list_append(list, relative_member);
list = eina_list_append_relative(list, my_data, relative_member);
eina_list_append_relative
EINA_API Eina_List * eina_list_append_relative(Eina_List *list, const void *data, const void *relative)
Inserts the given data into the given linked list after the specified data.
Definition: eina_list.c:649

Warning
  `list` must be a pointer to the first element of the list.

References eina_list_append(), eina_list_append_relative_list(), and EINA_LIST_FOREACH.

Referenced by efreet_menu_desktop_insert(), and elm_object_focus_custom_chain_append().

## ◆ eina_list_append_relative_list()

EINA_API Eina_List * eina_list_append_relative_list | ( | Eina_List * | list,
|  | const void * | data,
|  | Eina_List * | relative
| ) |  |

Appends a list node to a linked list after the specified member.

Parameters

  [in,out] | list | The given linked list.
  [in] | data | The data to insert.
  [in] | relative | The list node to insert after.

Returns
  A list pointer, or `NULL` on error.

This function inserts `data` into `list` after the list node `relative`. If `list` or `relative` are `NULL`, `data` is just appended to `list` using eina_list_append(). If `list` is `NULL`, a new list is returned. If there are multiple instances of `relative` in the list, `data` is inserted after the first instance. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List::data, eina_list_append(), _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by eina_list_append_relative(), and eina_list_sorted_insert().

## ◆ eina_list_prepend_relative()

EINA_API Eina_List * eina_list_prepend_relative | ( | Eina_List * | list,
|  | const void * | data,
|  | const void * | relative
| ) |  |

Prepends a data pointer to a linked list before the specified member.

Parameters

  [in,out] | list | The given linked list.
  [in] | data | The data to insert.
  [in] | relative | The member that data will be inserted before.

Returns
  A list pointer, or `NULL` on error.

This function inserts `data` to `list` before `relative`. If `relative` is not in the list, `data` is prepended to the list with eina_list_prepend(). If `list` is `NULL`, a new list is returned. If there are multiple instances of `relative` in the list, `data` is inserted before the first instance. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following code example demonstrates how to ensure that the given data has been successfully inserted.

Eina_List *list = NULL;
extern void *my_data;
extern void *relative_member;
list = eina_list_append(list, relative_member);
list = eina_list_prepend_relative(list, my_data, relative_member);
eina_list_prepend_relative
EINA_API Eina_List * eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative)
Prepends a data pointer to a linked list before the specified member.
Definition: eina_list.c:704

Warning
  `list` must be a pointer to the first element of the list.

References EINA_LIST_FOREACH, eina_list_prepend(), and eina_list_prepend_relative_list().

Referenced by elm_object_focus_custom_chain_prepend().

## ◆ eina_list_prepend_relative_list()

EINA_API Eina_List * eina_list_prepend_relative_list | ( | Eina_List * | list,
|  | const void * | data,
|  | Eina_List * | relative
| ) |  |

Prepends a list node to a linked list before the specified member.

Parameters

  [in,out] | list | The given linked list.
  [in] | data | The data to insert.
  [in] | relative | The list node to insert before.

Returns
  A list pointer, or `NULL` on error.

This function inserts `data` to `list` before the list node `relative`. If `list` or `relative` are `NULL`, `data` is just prepended to `list` using eina_list_prepend(). If `list` is `NULL`, a new list is returned. If there are multiple instances of `relative` in the list, `data` is inserted before the first instance. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::data, eina_list_prepend(), _Eina_List::next, and _Eina_List::prev.

Referenced by edje_edit_program_after_insert_at(), edje_edit_program_target_insert_at(), eina_list_prepend_relative(), and eina_list_sorted_insert().

## ◆ eina_list_sorted_insert()

EINA_API Eina_List * eina_list_sorted_insert | ( | Eina_List * | list,
|  | Eina_Compare_Cb | func,
|  | const void * | data
| ) |  |

Inserts a new node into a sorted list.

Parameters

  [in,out] | list | The given linked list, must be sorted.
  [in] | func | The function called for the sort.
  [in] | data | The data to be inserted in sorted order.

Returns
  A list pointer, or `NULL` on error.

This function inserts values into a linked list assuming it was sorted and the result will be sorted. If `list` is `NULL`, a new list is returned. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

Note
  O(log2(n)) comparisons (calls to `func`) average/worst case performance as it uses eina_list_search_sorted_near_list() and thus is bounded to that. As said in eina_list_search_sorted_near_list(), lists do not have O(1) access time, so walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).

Warning
  `list` must be a pointer to the first element of the list.

References eina_list_append(), eina_list_append_relative_list(), eina_list_prepend_relative_list(), and eina_list_search_sorted_near_list().

## ◆ eina_list_remove()

EINA_API Eina_List * eina_list_remove | ( | Eina_List * | list,
|  | const void * | data
| ) |  |

Removes the first instance of the specified data from the given list.

Parameters

  [in,out] | list | The given list.
  [in] | data | The specified data.

Returns
  A list pointer, or `NULL` on error.

This function removes the first instance of `data` from `list`. If `data` is not in the given list or is `NULL`, nothing is done and the specified `list` returned. If `list` is `NULL`, `NULL` is returned, otherwise a new list pointer that should be used in place of the one passed to this function is returned.

Warning
  `list` must be a pointer to the first element of the list.

References eina_list_data_find_list(), and eina_list_remove_list().

Referenced by ecore_con_socks4_remote_del(), ecore_con_socks5_remote_del(), ecore_con_socks_remote_del(), ecore_con_url_free(), ecore_drm2_plane_assign(), ecore_drm_device_free(), ecore_evas_aux_hint_del(), ecore_fb_input_device_close(), ecore_imf_context_input_panel_event_callback_clear(), ecore_ipc_client_del(), ecore_ipc_server_del(), ecore_thread_feedback_run(), ecore_thread_run(), edje_edit_color_class_del(), edje_edit_size_class_del(), edje_edit_string_list_free(), edje_edit_style_del(), edje_edit_style_tag_del(), edje_edit_text_class_del(), edje_file_collection_list_free(), edje_object_perspective_set(), eeze_disk_free(), efreet_desktop_category_del(), efreet_menu_desktop_remove(), eina_hash_list_remove(), eina_quadtree_del(), elm_radio_group_add(), elm_transit_chain_transit_add(), elm_transit_chain_transit_del(), ethumb_client_thumb_exists_cancel(), evas_font_path_global_clear(), evas_gl_context_destroy(), evas_gl_surface_destroy(), evas_object_image_video_surface_set(), and evas_textblock_cursor_free().

## ◆ eina_list_remove_list()

EINA_API Eina_List * eina_list_remove_list | ( | Eina_List * | list,
|  | Eina_List * | remove_list
| ) |  |

Removes the specified list node.

Parameters

  [in,out] | list | The given linked list.
  [in] | remove_list | The list node which is to be removed.

Returns
  A list pointer, or `NULL` on error.

This function removes the list node `remove_list` from `list` and frees the list node structure `remove_list`. If `list` is `NULL`, this function returns `NULL`. If `remove_list` is `NULL`, it returns `list`; otherwise, a new list pointer that should be used in place of the one passed to this function.

The following code gives an example. (Notice we use EINA_LIST_FOREACH rather than EINA_LIST_FOREACH_SAFE because we stop the loop after removing the current node.)

extern Eina_List *list;
Eina_List *l;
extern void *my_data;
void *data
EINA_LIST_FOREACH(list, l, data)
{
if (data == my_data)
{
list = eina_list_remove_list(list, l);
break;
}
}

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by ecore_con_eet_client_connect_callback_del(), ecore_con_eet_client_disconnect_callback_del(), ecore_con_eet_server_connect_callback_del(), ecore_con_eet_server_disconnect_callback_del(), ecore_drm2_fb_flip_complete(), ecore_fork_reset(), ecore_fork_reset_callback_del(), ecore_imf_context_event_callback_del(), ecore_imf_context_input_panel_event_callback_del(), ecore_thread_cancel(), edje_edit_group_del(), edje_edit_image_set_image_del(), edje_edit_program_after_del(), edje_edit_program_afters_clear(), edje_edit_program_del(), edje_edit_program_target_del(), edje_edit_program_targets_clear(), edje_object_text_insert_filter_callback_del(), edje_object_text_insert_filter_callback_del_full(), edje_object_text_markup_filter_callback_del(), edje_object_text_markup_filter_callback_del_full(), efreet_mime_type_icon_get(), eina_debug_timer_del(), eina_file_common_map_free(), eina_list_move(), eina_list_move_list(), eina_list_remove(), elm_config_profile_derived_del(), elm_spinner_special_value_del(), ethumb_client_generate_cancel(), and evas_textblock_node_format_remove_pair().

## ◆ eina_list_promote_list()

EINA_API Eina_List * eina_list_promote_list | ( | Eina_List * | list,
|  | Eina_List * | move_list
| ) |  |

Moves the specified data to the head of the list.

Parameters

  [in,out] | list | The given linked list.
  [in] | move_list | The list node to move.

Returns
  A new list handle to replace the old one, or `NULL` on error.

This function moves `move_list` to the front of `list`. If list is `NULL`, `NULL` is returned. If `move_list` is `NULL`, `list` is returned. Otherwise, a new list pointer that should be used in place of the one passed to this function is returned.

Example:

extern Eina_List *list;
Eina_List *l;
extern void *my_data;
void *data;
EINA_LIST_FOREACH(list, l, data)
{
if (data == my_data)
{
list = eina_list_promote_list(list, l);
break;
}
}
eina_list_promote_list
EINA_API Eina_List * eina_list_promote_list(Eina_List *list, Eina_List *move_list)
Moves the specified data to the head of the list.
Definition: eina_list.c:845

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by efreet_icon_extension_add().

## ◆ eina_list_demote_list()

EINA_API Eina_List * eina_list_demote_list | ( | Eina_List * | list,
|  | Eina_List * | move_list
| ) |  |

Moves the specified data to the tail of the list.

Parameters

  [in,out] | list | The given linked list.
  [in] | move_list | The list node to move.

Returns
  A new list handle to replace the old one, or `NULL` on error.

This function move `move_list` to the end of `list`. If list is `NULL`, `NULL` is returned. If `move_list` is `NULL`, `list` is returned. Otherwise, a new list pointer that should be used in place of the one passed to this function is returned.

Example:

extern Eina_List *list;
Eina_List *l;
extern void *my_data;
void *data;
EINA_LIST_FOREACH(list, l, data)
{
if (data == my_data)
{
list = eina_list_demote_list(list, l);
break;
}
}
eina_list_demote_list
EINA_API Eina_List * eina_list_demote_list(Eina_List *list, Eina_List *move_list)
Moves the specified data to the tail of the list.
Definition: eina_list.c:889

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

## ◆ eina_list_data_find()

EINA_API void * eina_list_data_find | ( | const Eina_List * | list,
|  | const void * | data
| ) |  |

Finds a member of a list and returns it.

Parameters

  [in] | list | The linked list to search.
  [in] | data | The data member to find in the list.

Returns
  The data member pointer if found, or `NULL` otherwise.

This function searches in `list` from beginning to end for the first member whose data pointer is `data`. If it is found, `data` will be returned, otherwise `NULL` will be returned.

Example:

extern Eina_List *list;
extern void *my_data;
if (eina_list_data_find(list, my_data) == my_data)
{
printf("Found member %p\n", my_data);
}
eina_list_data_find
EINA_API void * eina_list_data_find(const Eina_List *list, const void *data)
Finds a member of a list and returns it.
Definition: eina_list.c:928

Warning
  `list` must be a pointer to the first element of the list.

References eina_list_data_find_list().

Referenced by ecore_evas_focus_device_get(), and ecore_main_fd_handler_prepare_callback_set().

## ◆ eina_list_data_find_list()

EINA_API Eina_List * eina_list_data_find_list | ( | const Eina_List * | list,
|  | const void * | data
| ) |  |

Finds a member of a list and returns it as a list node.

Parameters

  [in] | list | The list to search for data.
  [in] | data | The data pointer to find in the list.

Returns
  A list node containing the data member on success, `NULL` otherwise.

This function searches `list` from beginning to end for the first member whose data pointer is `data`. If it is found, the list node containing the specified member is returned, otherwise `NULL` is returned.

Warning
  `list` must be a pointer to the first element of the list.

References EINA_LIST_FOREACH.

Referenced by efreet_icon_extension_add(), eina_debug_timer_del(), eina_list_data_find(), eina_list_move(), eina_list_remove(), and elm_transit_object_add().

## ◆ eina_list_move()

EINA_API Eina_Bool eina_list_move | ( | Eina_List ** | to,
|  | Eina_List ** | from,
|  | void * | data
| ) |  |

Moves a data pointer from one list to another.

Parameters

  [in,out] | to | The list to move the data to.
  [in,out] | from | The list to move from.
  [in] | data | The data member to move.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

This function is a shortcut for doing the following: to = eina_list_append(to, data); from = eina_list_remove(from, data);

Warning
  `list` must be a pointer to the first element of the list.

References EINA_FALSE, eina_list_append(), eina_list_data_find_list(), eina_list_remove_list(), EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

## ◆ eina_list_move_list()

EINA_API Eina_Bool eina_list_move_list | ( | Eina_List ** | to,
|  | Eina_List ** | from,
|  | Eina_List * | data
| ) |  |

Moves a list node from one list to another.

Parameters

  [in,out] | to | The list to move the data to.
  [in,out] | from | The list to move from.
  [in] | data | The list node containing the data to move.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

This function is a shortcut for doing the following: to = eina_list_append(to, data->data); from = eina_list_remove_list(from, data);

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::data, EINA_FALSE, eina_list_append(), eina_list_remove_list(), EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

## ◆ eina_list_free()

EINA_API Eina_List * eina_list_free | ( | Eina_List * | list | ) |

Frees an entire list and all the nodes, ignoring the data contained.

Parameters

  [in,out] | list | The list to free.

Returns
  A `NULL` pointer.

This function frees all the nodes of `list`. It does not free the data of the nodes. To free them, use EINA_LIST_FREE.

References _Eina_List::next.

Referenced by ecore_audio_shutdown(), ecore_evas_engines_free(), ecore_ipc_server_del(), edje_file_color_class_used_free(), edje_mmap_color_class_used_list(), edje_mmap_group_exists(), eet_eina_stream_data_descriptor_class_set(), efreet_desktop_command_progress_get(), efreet_icon_list_find(), elm_store_free(), elm_theme_extension_mmap_add(), elm_theme_extension_mmap_del(), elm_theme_overlay_mmap_add(), elm_theme_overlay_mmap_del(), elua_state_free(), evas_event_feed_hold(), evas_object_clipees_get(), and evas_textblock_node_format_remove_pair().

## ◆ eina_list_nth()

EINA_API void * eina_list_nth | ( | const Eina_List * | list,
|  | unsigned int | n
| ) |  |

Gets the nth member's data pointer in a list, or `NULL` on error.

Parameters

  [in] | list | The list to get the specified member number from.
  [in] | n | The number of the element (0 being the first).

Returns
  The data pointer stored in the specified element.

This function returns the data pointer of element number `n`, in the `list`. The first element in the array is element number 0. If the element number `n` does not exist, `NULL` is returned. Otherwise, the data of the found element is returned.

Note
  Worst case is O(n).

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::data, and eina_list_nth_list().

Referenced by edje_edit_image_set_image_border_get(), edje_edit_image_set_image_border_scale_get(), edje_edit_image_set_image_border_scale_set(), edje_edit_image_set_image_border_set(), edje_edit_image_set_image_del(), efreet_desktop_free(), efreet_desktop_get(), efreet_desktop_save(), efreet_desktop_type_alias(), efreet_menu_desktop_insert(), evas_touch_point_list_nth_id_get(), and evas_touch_point_list_nth_state_get().

## ◆ eina_list_nth_list()

EINA_API Eina_List * eina_list_nth_list | ( | const Eina_List * | list,
|  | unsigned int | n
| ) |  |

Gets the nth member's list node in a list.

Parameters

  [in] | list | The list to get the specified member number from.
  [in] | n | The number of the element (0 being the first).

Returns
  The list node stored in the numbered element, or `NULL` on error.

This function returns the list node of element number `n`, in `list`. The first element in the array is element number 0. If the element number `n` does not exist or `list` is `NULL` or `n` is greater than the count of elements in `list` minus 1, `NULL` is returned. Otherwise the list node stored in the numbered element is returned.

Note
  Worst case is O(n).

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by edje_edit_image_set_image_del(), edje_edit_program_after_insert_at(), edje_edit_program_target_insert_at(), eina_list_nth(), and eina_list_sort().

## ◆ eina_list_reverse()

EINA_API Eina_List * eina_list_reverse | ( | Eina_List * | list | ) |

Reverses all the elements in the list.

Parameters

  [in,out] | list | The list to reverse.

Returns
  The list head after it has been reversed, or `NULL` on error.

This function reverses the order of all elements in `list`, so the last member is now first, and so on. If `list` is `NULL`, this function returns `NULL`.

Note
  in-place: this will change the given list, so you should now point to the new list head that is returned by this function.

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_reverse_clone()
  eina_list_iterator_reversed_new()

References _Eina_List::accounting, _Eina_List::data, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

## ◆ eina_list_reverse_clone()

EINA_API Eina_List * eina_list_reverse_clone | ( | const Eina_List * | list | ) |

Clones (copies) all the elements in the list in reverse order.

Parameters

  [in] | list | The list to reverse.

Returns
  The new list that has been reversed, or `NULL` on error.

This function reverses the order of all elements in `list`, so the last member is now first, and so on. If `list` is `NULL`, this function returns `NULL`. This returns a copy of the given list.

Note
  copy: this will copy the list and you should then eina_list_free() when it is not required anymore.

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_reverse()
  eina_list_clone()

References EINA_LIST_FOREACH, and eina_list_prepend().

## ◆ eina_list_clone()

EINA_API Eina_List * eina_list_clone | ( | const Eina_List * | list | ) |

Clones (copies) all the elements in the list in exactly same order.

Parameters

  [in] | list | The list to clone.

Returns
  The new list that has been cloned, or `NULL` on error.

This function clone in order of all elements in `list`. If `list` is `NULL`, this function returns `NULL`. This returns a copy of the given list.

Note
  copy: this will copy the list and you should then eina_list_free() when it is not required anymore.

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_reverse_clone()

References eina_list_append(), and EINA_LIST_FOREACH.

Referenced by ecore_drm_shutdown(), ecore_evas_engines_get(), elm_object_focus_custom_chain_append(), and elm_object_focus_custom_chain_prepend().

## ◆ eina_list_sort()

EINA_API Eina_List * eina_list_sort | ( | Eina_List * | list,
|  | unsigned int | limit,
|  | Eina_Compare_Cb | func
| ) |  |

Sorts a list according to the ordering func will return.

Parameters

  [in] | list | The list handle to sort.
  [in] | limit | The maximum number of list elements to sort.
  [in] | func | A function pointer that can handle comparing the list data nodes.

Returns
  The new head of list.

This function sorts `list`. If `limit` is 0 or greater than the number of elements in `list`, all the elements are sorted. `func` is used to compare two elements of `list`. If `func` is `NULL`, this function returns `list`.

Note
  in-place: this will change the given list, so you should now point to the new list head that is returned by this function.
  Worst case is O(n * log2(n)) comparisons (calls to func()). That means that for 1,000,000 list sort will do 20,000,000 comparisons.

Example:

int
sort_cb(const void *d1, const void *d2)
{
const char *txt = d1;
const char *txt2 = d2;
if(!txt) return(1);
if(!txt2) return(-1);
return(strcmp(txt, txt2));
}
extern Eina_List *list;
list = eina_list_sort(list, eina_list_count(list), sort_cb);
eina_list_sort
EINA_API Eina_List * eina_list_sort(Eina_List *list, unsigned int limit, Eina_Compare_Cb func)
Sorts a list according to the ordering func will return.
Definition: eina_list.c:1112

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::count, eina_list_nth_list(), EINA_SAFETY_ON_NULL_RETURN_VAL, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by ecore_file_ls(), eina_rectangle_pool_request(), elm_theme_color_class_list(), elm_theme_group_base_list(), and elm_theme_name_available_list_new().

## ◆ eina_list_shuffle()

EINA_API Eina_List * eina_list_shuffle | ( | Eina_List * | list,
|  | Eina_Random_Cb | func
| ) |  |

Shuffles list.

Parameters

  [in] | list | The list handle to shuffle.
  [in] | func | A function pointer that can return an int between 2 inclusive values

Returns
  The new head of list.

This function shuffles `list`. `func` is used to generate random list indexes within the range of unshuffled list items. If `func` is `NULL`, rand is used.

Note
  in-place: This will change the given list, so you should now point to the new list head that is returned by this function.

Since
  1.8

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

## ◆ eina_list_merge()

EINA_API Eina_List * eina_list_merge | ( | Eina_List * | left,
|  | Eina_List * | right
| ) |  |

Merges two list.

Parameters

  [in] | left | Head list to merge.
  [in] | right | Tail list to merge.

Returns
  A new merged list.

This function puts right at the end of left and returns the head.

Both left and right do not exist anymore after the merge.

Note
  Merge cost is O(n), being n the size of the smallest list. This is due the need to fix accounting of that segment, making count and last access O(1).

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by eina_file_flush(), and evas_textblock_cursor_range_simple_geometry_get().

## ◆ eina_list_sorted_merge()

EINA_API Eina_List * eina_list_sorted_merge | ( | Eina_List * | left,
|  | Eina_List * | right,
|  | Eina_Compare_Cb | func
| ) |  |

Merges two sorted list according to the ordering func will return.

Parameters

  [in] | left | First list to merge.
  [in] | right | Second list to merge.
  [in] | func | A function pointer that can handle comparing the list data nodes.

Returns
  A new sorted list.

This function compares the head of `left` and `right`, and choose the smallest one to be head of the returned list. It will continue this process for all entry of both list.

Both left and right lists are not valid anymore after the merge and should not be used. If `func` is `NULL`, it will return `NULL`.

Example:

int
sort_cb(void *d1, void *d2)
{
const char *txt = NULL;
const char *txt2 = NULL;
if(!d1) return(1);
if(!d2) return(-1);
return(strcmp((const char*)d1, (const char*)d2));
}
extern Eina_List *sorted1;
extern Eina_List *sorted2;
list = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
eina_list_sorted_merge
EINA_API Eina_List * eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func)
Merges two sorted list according to the ordering func will return.
Definition: eina_list.c:1362

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List::data, EINA_SAFETY_ON_NULL_RETURN_VAL, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

## ◆ eina_list_split_list()

EINA_API Eina_List * eina_list_split_list | ( | Eina_List * | list,
|  | Eina_List * | relative,
|  | Eina_List ** | right
| ) |  |

Splits a list into 2 lists.

Parameters

  [in] | list | List to split.
  [in] | relative | The list will be split after `relative`.
  [out] | right | The head of the new right list.

Returns
  The new left list

This function splits `list` into two lists ( left and right ) after the node `relative`. `Relative` will become the last node of the left list. If `list` or `right` are `NULL` list is returns. If `relative` is NULL right is set to `list` and `NULL` is returns. If `relative` is the last node of `list` list is returns and `right` is set to `NULL`.

list does not exist anymore after the split.

Warning
  `list` must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

## ◆ eina_list_search_sorted_near_list()

EINA_API Eina_List * eina_list_search_sorted_near_list | ( | const Eina_List * | list,
|  | Eina_Compare_Cb | func,
|  | const void * | data,
|  | int * | result_cmp
| ) |  |

Returns node nearest to data from the sorted list.

Parameters

  [in] | list | The list to search for data, must be sorted.
  [in] | func | A function pointer that can handle comparing the list data nodes.
  [in] | data | reference value to search.
  [out] | result_cmp | If provided returns the result of func(node->data, data) node being the last (returned) node. If node was found (exact match), then it is 0. If returned node is smaller than requested data, it is less than 0 and if it's bigger it's greater than 0. It is the last value returned by func().

Returns
  The nearest node, `NULL` if not found.

This function searches for a node containing `data` as its data in `list`, if such a node exists it will be returned and `result_cmp` will be `0`. If the data of no node in `list` is equal to `data`, the node with the nearest value to that will be returned and `result_cmp` will be the return value of `func` with `data` and the returned node's data as arguments.

This function is useful for inserting an element in the list only in case it isn't already present in the list, the naive way of doing this would be:

void *ptr = eina_list_data_find(list, "my data");
if (!ptr)
eina_list_sorted_insert(list, "my data");
eina_list_sorted_insert
EINA_API Eina_List * eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data)
Inserts a new node into a sorted list.
Definition: eina_list.c:757

However this has the downside of walking through the list twice, once to check if the data is already present and another to insert the element in the correct position. This can be done more efficiently:

int cmp_result;
l = eina_list_search_sorted_near_list(list, cmp_func, "my data",
&cmp_result);
if (cmp_result > 0)
list = eina_list_prepend_relative_list(list, "my data", l);
else if (cmp_result < 0)
list = eina_list_append_relative_list(list, "my data", l);
eina_list_search_sorted_near_list
EINA_API Eina_List * eina_list_search_sorted_near_list(const Eina_List *list, Eina_Compare_Cb func, const void *data, int *result_cmp)
Returns node nearest to data from the sorted list.
Definition: eina_list.c:1439
eina_list_append_relative_list
EINA_API Eina_List * eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative)
Appends a list node to a linked list after the specified member.
Definition: eina_list.c:670
eina_list_prepend_relative_list
EINA_API Eina_List * eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative)
Prepends a list node to a linked list before the specified member.
Definition: eina_list.c:724

If cmp_result is 0 the element is already in the list and we need not insert it, if cmp_result is greater than zero "my @a data" needs to come after l (the nearest node present), if less than zero before.

Note
  O(log2(n)) average/worst case performance, for 1,000,000 elements it will do a maximum of 20 comparisons. This is much faster than the 1,000,000 comparisons made naively walking the list from head to tail, so depending on the number of searches and insertions, it may be worth to eina_list_sort() the list and do the searches later. As lists do not have O(1) access time, walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_search_sorted_list()
  eina_list_sort()
  eina_list_sorted_merge()

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List::data, _Eina_List_Accounting::last, and _Eina_List::next.

Referenced by eina_list_search_sorted_list(), and eina_list_sorted_insert().

## ◆ eina_list_search_sorted_list()

EINA_API Eina_List * eina_list_search_sorted_list | ( | const Eina_List * | list,
|  | Eina_Compare_Cb | func,
|  | const void * | data
| ) |  |

Returns node if data is in the sorted list.

Parameters

  [in] | list | The list to search for data, must be sorted.
  [in] | func | A function pointer that can handle comparing the list data nodes.
  [in] | data | reference value to search.

Returns
  The node if func(node->data, data) == 0, `NULL` if not found.

This can be used to check if some value is inside the list and get the container node in this case. It should be used when list is known to be sorted as it will do binary search for results.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
  O(log2(n)) average/worst case performance, for 1,000,000 elements it will do a maximum of 20 comparisons. This is much faster than the 1,000,000 comparisons made by eina_list_search_unsorted_list(), so depending on the number of searches and insertions, it may be worth to eina_list_sort() the list and do the searches later. As said in eina_list_search_sorted_near_list(), lists do not have O(1) access time, so walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_search_sorted()
  eina_list_sort()
  eina_list_sorted_merge()
  eina_list_search_unsorted_list()
  eina_list_search_sorted_near_list()

References eina_list_search_sorted_near_list().

Referenced by eina_list_search_sorted().

## ◆ eina_list_search_sorted()

EINA_API void * eina_list_search_sorted | ( | const Eina_List * | list,
|  | Eina_Compare_Cb | func,
|  | const void * | data
| ) |  |

Returns node data if it is in the sorted list.

Parameters

  [in] | list | The list to search for data, must be sorted.
  [in] | func | A function pointer that can handle comparing the list data nodes.
  [in] | data | reference value to search.

Returns
  The node value (`node->data`) if func(node->data, data) == 0, `NULL` if not found.

This can be used to check if some value is inside the list and get the existing instance in this case. It should be used when list is known to be sorted as it will do binary search for results.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
  O(log2(n)) average/worst case performance, for 1,000,000 elements it will do a maximum of 20 comparisons. This is much faster than the 1,000,000 comparisons made by eina_list_search_unsorted(), so depending on the number of searches and insertions, it may be worth to eina_list_sort() the list and do the searches later. As said in eina_list_search_sorted_near_list(), lists do not have O(1) access time, so walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_search_sorted_list()
  eina_list_sort()
  eina_list_sorted_merge()
  eina_list_search_unsorted_list()

References eina_list_search_sorted_list().

## ◆ eina_list_search_unsorted_list()

EINA_API Eina_List * eina_list_search_unsorted_list | ( | const Eina_List * | list,
|  | Eina_Compare_Cb | func,
|  | const void * | data
| ) |  |

Returns node if data is in the unsorted list.

Parameters

  [in] | list | The list to search for data, may be unsorted.
  [in] | func | A function pointer that can handle comparing the list data nodes.
  [in] | data | reference value to search.

Returns
  The node if func(node->data, data) == 0, `NULL` if not found.

This can be used to check if some value is inside the list and get the container node in this case.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
  this is expensive and may walk the whole list, it's order-N, that is for 1,000,000 elements list it may walk and compare 1,000,000 nodes.

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_search_sorted_list()
  eina_list_search_unsorted()

References EINA_LIST_FOREACH.

Referenced by eina_list_search_unsorted().

## ◆ eina_list_search_unsorted()

EINA_API void * eina_list_search_unsorted | ( | const Eina_List * | list,
|  | Eina_Compare_Cb | func,
|  | const void * | data
| ) |  |

Returns node data if it is in the unsorted list.

Parameters

  [in] | list | The list to search for data, may be unsorted.
  [in] | func | A function pointer that can handle comparing the list data nodes.
  [in] | data | reference value to search.

Returns
  The node value (`node->data`) if func(node->data, data) == 0, `NULL` if not found.

This can be used to check if some value is inside the list and get the existing instance in this case.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
  this is expensive and may walk the whole list, it's order-N, that is, for 1,000,000 elements list it may walk and compare 1,000,000 nodes.

Warning
  `list` must be a pointer to the first element of the list.

See also
  eina_list_search_sorted()
  eina_list_search_unsorted_list()

References eina_list_search_unsorted_list().

Referenced by efreet_desktop_category_add(), efreet_desktop_category_del(), efreet_menu_desktop_remove(), elm_drag_item_container_add(), and elm_drop_item_container_add().

## ◆ eina_list_last()

static Eina_List * eina_list_last | ( | const Eina_List * | list | ) |
| inlinestatic

Gets the last list node in the list.

Parameters

  [in] | list | The list to get the last list node from.

Returns
  The last list node in the list.

This function returns the last list node in the list `list`. If `list` is `NULL` or empty, `NULL` is returned.

This is a order-1 operation (it takes the same short time regardless of the length of the list).

Warning
  `list` must be a pointer to the first element of the list.

## ◆ eina_list_next()

static Eina_List * eina_list_next | ( | const Eina_List * | list | ) |
| inlinestatic

Gets the next list node after the specified list node.

Parameters

  [in] | list | The list node to get the next list node from

Returns
  The next list node on success, `NULL` otherwise.

This function returns the next list node after the current one in `list`. It is equivalent to list->next. If `list` is `NULL` or if no next list node exists, it returns `NULL`.

Warning
  `list` must be a pointer to the first element of the list.

## ◆ eina_list_prev()

static Eina_List * eina_list_prev | ( | const Eina_List * | list | ) |
| inlinestatic

Gets the list node prior to the specified list node.

Parameters

  [in] | list | The list node to get the previous list node from.

Returns
  The previous list node on success, `NULL` otherwise.

This function returns the previous list node before the current one in `list`. It is equivalent to list->prev. If `list` is `NULL` or if no previous list node exists, it returns `NULL`.

Warning
  `list` must be a pointer to the first element of the list.

## ◆ eina_list_data_get()

static void * eina_list_data_get | ( | const Eina_List * | list | ) |
| inlinestatic

Gets the list node data member.

Parameters

  [in] | list | The list node to get the data member of.

Returns
  The data member from the list node.

This function returns the data member of the specified list node `list`. It is equivalent to list->data. If `list` is `NULL`, this function returns `NULL`.

Warning
  `list` must be a pointer to the first element of the list.

## ◆ eina_list_data_set()

static void * eina_list_data_set | ( | Eina_List * | list,
|  | const void * | data
| ) |  |
| inlinestatic

Sets the list node data member.

Parameters

  [in,out] | list | The list node to set the data member of.
  [in] | data | The data to be set.

Returns
  The previous data value.

This function sets the data member `data` of the specified list node `list`. It returns the previous data of the node. If `list` is `NULL`, this function returns `NULL`.

Warning
  `list` must be a pointer to the first element of the list.

## ◆ eina_list_count()

static unsigned int eina_list_count | ( | const Eina_List * | list | ) |
| inlinestatic

Gets the count of the number of items in a list.

Parameters

  [in] | list | The list whose count to return.

Returns
  The number of members in the list.

This function returns the quantity of members that `list` contains. If the list is `NULL`, `0` is returned.

NB: This is an order-1 operation and takes the same time regardless of the length of the list.

Warning
  `list` must be a pointer to the first element of the list.

## ◆ eina_list_last_data_get()

static void * eina_list_last_data_get | ( | const Eina_List * | list | ) |
| inlinestatic

Returns the last list node's data.

Parameters

  [in] | list | The list.

Returns
  The node's data, or `NULL` on being passed a `NULL` pointer

This function is a shortcut for typing eina_list_data_get(eina_list_last())

Since
  1.8

## ◆ eina_list_iterator_new()

EINA_API Eina_Iterator * eina_list_iterator_new | ( | const Eina_List * | list | ) |

Returns a new iterator associated with a list.

Parameters

  [in] | list | The list.

Returns
  A new iterator, or `NULL` on memory allocation failure.

This function returns a newly allocated iterator associated with `list`. If `list` is `NULL` or the count member of `list` is less than or equal to 0, this function still returns a valid iterator that will always return false on eina_iterator_next(), thus keeping API sane.

Warning
  `list` must be a pointer to the first element of the list.
  if the list structure changes then the iterator becomes invalid! That is, if you add or remove nodes this iterator behavior is undefined and your program may crash!

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

Referenced by ecore_win32_monitors_get().

## ◆ eina_list_iterator_reversed_new()

EINA_API Eina_Iterator * eina_list_iterator_reversed_new | ( | const Eina_List * | list | ) |

Returns a new reversed iterator associated with a list.

Parameters

  [in] | list | The list.

Returns
  A new iterator, or `NULL` on memory allocation failure.

This function returns a newly allocated iterator associated with `list`. If `list` is `NULL` or the count member of `list` is less than or equal to 0, this function still returns a valid iterator that will always return false on eina_iterator_next(), thus keeping API sane.

Unlike eina_list_iterator_new(), this will walk the list backwards.

Warning
  `list` must be a pointer to the first element of the list.
  if the list structure changes then the iterator becomes invalid! That is, if you add or remove nodes this iterator behavior is undefined and your program may crash!

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

## ◆ eina_list_accessor_new()

EINA_API Eina_Accessor * eina_list_accessor_new | ( | const Eina_List * | list | ) |

Returns a new accessor associated with a list.

Parameters

  [in] | list | The list.

Returns
  A new accessor, or `NULL` on error.

This function returns a newly allocated accessor associated with `list`. If `list` is `NULL` or the count member of `list` is less or equal than 0, this function returns `NULL`. If the memory can not be allocated, `NULL` is returned; otherwise, a valid accessor is returned.

Warning
  `list` must be a pointer to the first element of the list.

References EINA_MAGIC_SET, EINA_SAFETY_ON_NULL_RETURN_VAL, FUNC_ACCESSOR_CLONE, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, and FUNC_ACCESSOR_GET_CONTAINER.

## ◆ eina_list_data_idx()

EINA_API int eina_list_data_idx | ( | const Eina_List * | list,
|  | void * | data
| ) |  |

Finds the member of the list and returns the index.

Parameters

  [in] | list | The list.
  [in] | data | The data member.

Returns
  The index of data member if found, `-1` otherwise.

This function searches in `list` from beginning to end for the first member whose data pointer is `data`. If it is found, the index of the data will be returned, otherwise `-1` will be returned.

Warning
  `list` must be a pointer to the first element of the list.

Since
  1.14

References EINA_LIST_FOREACH.