#include "eina_magic.h"
/**
+ * @addtogroup Eina_List_Group List
+ *
+ * @brief These functions provide double linked list management.
+ *
+ * For more information, you can look at the @ref tutorial_list_page.
+ *
+ * @{
+ */
+
+/**
* @addtogroup Eina_Data_Types_Group Data Types
*
* @{
EINA_MAGIC
};
+
+/**
+ * @brief Append the given data to the given linked list.
+ *
+ * @param list The given list.
+ * @param data The data to append.
+ * @return A list pointer.
+ *
+ * This function appends @p data to @p list. If @p list is @c 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.
+ *
+ * @code
+ * Eina_List *list = NULL;
+ * extern void *my_data;
+ *
+ * list = eina_list_append(list, my_data);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
+ * @endcode
+ */
EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Prepends the given data to the given linked list.
+ *
+ * @param list The given list.
+ * @param data The data to prepend.
+ * @return A list pointer.
+ *
+ * This function prepends @p data to @p list. If @p list is @c 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:
+ * @code
+ * Eina_List *list = NULL;
+ * extern void *my_data;
+ *
+ * list = eina_list_prepend(list, my_data);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
+ * @endcode
+ */
EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Insert the given data into the given linked list after the specified data.
+ *
+ * @param list The given linked list.
+ * @param data The data to insert.
+ * @param relative The data to insert after.
+ * @return A list pointer.
+ *
+ * This function inserts @p data to @p list after @p relative. If
+ * @p relative is not in the list, @p data is appended to the end of
+ * the list. If @p list is @c NULL, a new list is returned. If there
+ * are multiple instances of @p relative in the list, @p 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.
+ *
+ * @code
+ * Eina_List *list = NULL;
+ * extern void *my_data;
+ * extern void *relative_member;
+ *
+ * list = eina_list_append(list, relative_member);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
+ * list = eina_list_append_relative(list, my_data, relative_member);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
+ * @endcode
+ */
EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Append a list node to a linked list after the specified member
+ *
+ * @param list The given linked list.
+ * @param data The data to insert.
+ * @param relative The list node to insert after.
+ * @return A list pointer.
+ *
+ * This function inserts @p data to @p list after the list node
+ * @p relative. If @p list or @p relative are @c NULL, @p data is just
+ * appended to @p list using eina_list_append(). If @p list is
+ * @c NULL, a new list is returned. If there are multiple instances
+ * of @p relative in the list, @p 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.
+ */
EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Prepend a data pointer to a linked list before the specified member
+ *
+ * @param list The given linked list.
+ * @param data The data to insert.
+ * @param relative The data to insert before.
+ * @return A list pointer.
+ *
+ * This function inserts @p data to @p list before @p relative. If
+ * @p relative is not in the list, @p data is prepended to the list
+ * with eina_list_prepend(). If @p list is @c NULL, a new list is
+ * returned. If there are multiple instances of @p relative in the
+ * list, @p 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.
+ *
+ * @code
+ * Eina_List *list = NULL;
+ * extern void *my_data;
+ * extern void *relative_member;
+ *
+ * list = eina_list_append(list, relative_member);
+ * if (eina_error_get_error())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
+ * list = eina_list_prepend_relative(list, my_data, relative_member);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
+ * @endcode
+ */
EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Prepend a list node to a linked list before the specified member
+ *
+ * @param list The given linked list.
+ * @param data The data to insert.
+ * @param relative The list node to insert before.
+ * @return A list pointer.
+ *
+ * This function inserts @p data to @p list before the list node
+ * @p relative. If @p list or @p relative are @c NULL, @p data is just
+ * prepended to @p list using eina_list_prepend(). If @p list is
+ * @c NULL, a new list is returned. If there are multiple instances
+ * of @p relative in the list, @p 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.
+ */
EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Insert a new node into a sorted list.
+ *
+ * @param list The given linked list, @b must be sorted.
+ * @param func The function called for the sort.
+ * @param data The data to insert sorted.
+ * @return A list pointer.
+ *
+ * This function inserts values into a linked list assuming it was
+ * sorted and the result will be sorted. If @p list is @c NULLL, 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. See eina_error_get().
+ *
+ * @note O(log2(n)) comparisons (calls to @p 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).
+ */
EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Remove the first instance of the specified data from the given list.
+ *
+ * @param list The given list.
+ * @param data The specified data.
+ * @return A list pointer.
+ *
+ * This function removes the first instance of @p data from
+ * @p list. If the specified data is not in the given list (tihis
+ * include the case where @p data is @c NULL), nothing is done. If
+ * @p list is @c NULL, @c NULL is returned, otherwise a new list
+ * pointer that should be used in place of the one passed to this
+ * function.
+ */
EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Remove the specified data.
+ *
+ * @param list The given linked list.
+ * @param remove_list The list node which is to be removed.
+ * @return A list pointer.
+ *
+ * This function removes the list node @p remove_list from @p list and
+ * frees the list node structure @p remove_list. If @p list is
+ * @c NULL, this function returns @c NULL. If @p remove_list is
+ * @c NULL, it returns @p 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
+ * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after
+ * removing the current node).
+ *
+ * @code
+ * 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;
+ * }
+ * }
+ * @endcode
+ */
EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Move the specified data to the head of the list.
+ *
+ * @param list The list handle to move the data.
+ * @param move_list The list node to move.
+ * @return A new list handle to replace the old one
+ *
+ * This function move @p move_list to the front of @p list. If list is
+ * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
+ * @p list is returned. Otherwise, a new list pointer that should be
+ * used in place of the one passed to this function.
+ *
+ * Example:
+ * @code
+ * 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;
+ * }
+ * }
+ * @endcode
+ */
EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Move the specified data to the tail of the list.
+ *
+ * @param list The list handle to move the data.
+ * @param move_list The list node to move.
+ * @return A new list handle to replace the old one
+ *
+ * This function move @p move_list to the back of @p list. If list is
+ * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
+ * @p list is returned. Otherwise, a new list pointer that should be
+ * used in place of the one passed to this function.
+ *
+ * Example:
+ * @code
+ * 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;
+ * }
+ * }
+ * @endcode
+ */
EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *move_list);
+
+/**
+ * @brief Find a member of a list and return the member.
+ *
+ * @param list The list to search for a data.
+ * @param data The data pointer to find in the list.
+ * @return The found member data pointer if found, @c NULL otherwise.
+ *
+ * This function searches in @p list from beginning to end for the
+ * first member whose data pointer is @p data. If it is found, @p data
+ * will be returned, otherwise NULL will be returned.
+ *
+ * Example:
+ * @code
+ * 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);
+ * }
+ * @endcode
+ */
EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Find a member of a list and return the list node containing that member.
+ *
+ * @param list The list to search for data.
+ * @param data The data pointer to find in the list.
+ * @return The found members list node on success, @c NULL otherwise.
+ *
+ * This function searches in @p list from beginning to end for the
+ * first member whose data pointer is @p data. If it is found, the
+ * list node containing the specified member is returned, otherwise
+ * @c NULL is returned.
+ */
EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Move a data pointer from one list to another
+ *
+ * @param to The list to move the data to
+ * @param from The list to move from
+ * @param data The data to move
+ * @return #EINA_TRUE on success, else #EINA_FALSE
+ *
+ * This function is a shortcut for doing the following:
+ * to = eina_list_append(to, data);
+ * from = eina_list_remove(from, data);
+ */
EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data);
+
+/**
+ * @brief Move a list node from one list to another
+ *
+ * @param to The list to move the data to
+ * @param from The list to move from
+ * @param data The list node containing the data to move
+ * @return #EINA_TRUE on success, else #EINA_FALSE
+ *
+ * This function is a shortcut for doing the following:
+ * to = eina_list_append(to, data->data);
+ * from = eina_list_remove_list(from, data);
+ */
EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data);
+
+/**
+ * @brief Free an entire list and all the nodes, ignoring the data contained.
+
+ * @param list The list to free
+ * @return A NULL pointer
+ *
+ * This function frees all the nodes of @p list. It does not free the
+ * data of the nodes. To free them, use #EINA_LIST_FREE.
+ */
EAPI Eina_List *eina_list_free(Eina_List *list);
+
+/**
+ * @brief Get the nth member's data pointer in a list.
+ *
+ * @param list The list to get the specified member number from.
+ * @param n The number of the element (0 being the first).
+ * @return The data pointer stored in the specified element.
+ *
+ * This function returns the data pointer of element number @p n, in
+ * the @p list. The first element in the array is element number 0. If
+ * the element number @p n does not exist, @c NULL is
+ * returned. Otherwise, the data of the found element is returned.
+ */
EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Get the nth member's list node in a list.
+ *
+ * @param list The list to get the specfied member number from.
+ * @param n The number of the element (0 being the first).
+ * @return The list node stored in the numbered element.
+ *
+ * This function returns the list node of element number @p n, in
+ * @ list. The first element in the array is element number 0. If the
+ * element number @p n does not exist or @p list is @c NULL or @p n is
+ * greater than the count of elements in @p list minus 1, @c NULL is
+ * returned. Otherwise the list node stored in the numbered element is
+ * returned.
+ */
EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Reverse all the elements in the list.
+ *
+ * @param list The list to reverse.
+ * @return The list head after it has been reversed.
+ *
+ * This function reverses the order of all elements in @p list, so the
+ * last member is now first, and so on. If @p list is @c NULL, this
+ * functon returns @c NULL.
+ *
+ * @note @b in-place: this will change the given list, so you should
+ * now point to the new list head that is returned by this function.
+ *
+ * @see eina_list_reverse_clone()
+ * @see eina_list_iterator_reversed_new()
+ */
EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Clone (copy) all the elements in the list in reverse order.
+ *
+ * @param list The list to reverse.
+ * @return The new list that has been reversed.
+ *
+ * This function reverses the order of all elements in @p list, so the
+ * last member is now first, and so on. If @p list is @c NULL, this
+ * functon returns @c NULL. This returns a copy of the given list.
+ *
+ * @note @b copy: this will copy the list and you should then
+ * eina_list_free() when it is not required anymore.
+ *
+ * @see eina_list_reverse()
+ * @see eina_list_clone()
+ */
EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Clone (copy) all the elements in the list in exact order.
+ *
+ * @param list The list to clone.
+ * @return The new list that has been cloned.
+ *
+ * This function clone in order of all elements in @p list. If @p list
+ * is @c NULL, this functon returns @c NULL. This returns a copy of
+ * the given list.
+ *
+ * @note @b copy: this will copy the list and you should then
+ * eina_list_free() when it is not required anymore.
+ *
+ * @see eina_list_reverse_clone()
+ */
EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Sort a list according to the ordering func will return.
+ *
+ * @param list The list handle to sort.
+ * @param size The length of the list to sort.
+ * @param func A function pointer that can handle comparing the list data
+ * nodes.
+ * @return the new head of list.
+ *
+ * This function sorts @p list. @p size if the number of the first
+ * element to sort. If @p size is 0 or greater than the number of
+ * elements in @p list, all the elements are sorted. @p func is used to
+ * compare two elements of @p list. If @p list or @p func are @c NULL,
+ * this function returns @c NULL.
+ *
+ * @note @b in-place: this will change the given list, so you should
+ * now point to the new list head that is returned by this function.
+ *
+ * @note worst case is O(n * log2(n)) comparisons (calls to func()),
+ * O(n) comparisons average case. That means that for 1,000,000 list
+ * elements, sort will usually do 1,000,000 comparisons, but may do up
+ * to 20,000,000.
+ *
+ * Example:
+ * @code
+ * int
+ * sort_cb(const void *d1, const void *d2)
+ * {
+ * const char *txt = NULL;
+ * const char *txt2 = NULL;
+ *
+ * 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);
+ * @endcode
+ */
EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int size, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Merge two list.
+ *
+ * @param left Head list to merge.
+ * @param right Tail list to merge.
+ * @return A new merged list.
+ *
+ * This function put right at the end of left and return the head.
+ *
+ * Both left and right does not exist anymore after the merge.
+ *
+ * @note merge cost is O(n), being @b 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).
+ */
EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Merge two sorted list according to the ordering func will return.
+ *
+ * @param left First list to merge.
+ * @param right Second list to merge.
+ * @param func A function pointer that can handle comparing the list data
+ * nodes.
+ * @return A new sorted list.
+ *
+ * This function compare the head of @p left and @p 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 does not exist anymore after the merge.
+ * If @p func is NULL, it will return NULL.
+ *
+ * Example:
+ * @code
+ * 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);
+ * @endcode
+ */
EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Split a list into 2 lists.
+ *
+ * @param list List to split.
+ * @param relative The list will be split after @p relative.
+ * @param right The head of the new right list.
+ * @return The new left list
+ *
+ * This function split @p list into two lists ( left and right ) after the node @p relative. @p Relative
+ * will become the last node of the left list. If @p list or @p right are NULL list is returns.
+ * If @p relative is NULL right is set to @p list and NULL is returns.
+ * If @p relative is the last node of @p list list is returns and @p right is set to NULL.
+ *
+ * list does not exist anymore after the split.
+ *
+ */
EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Returns node nearest to data is in the sorted list.
+ *
+ * @param list The list to search for data, @b must be sorted.
+ * @param func A function pointer that can handle comparing the list data nodes.
+ * @param data reference value to search.
+ * @param 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().
+ * @return the nearest node, NULL if not found.
+ *
+ * This can be used to check if some value is inside the list and get
+ * the nearest 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, otherwise you want to insert it
+ * sorted. In this case you get the result of this function and either
+ * append or prepend the value.
+ *
+ * @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).
+ *
+ * @see eina_list_search_sorted_list()
+ * @see eina_list_sort()
+ * @see eina_list_sorted_merge()
+ */
EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *list, Eina_Compare_Cb func, const void *data, int *result_cmp);
+
+/**
+ * @brief Returns node if data is in the sorted list.
+ *
+ * @param list The list to search for data, @b must be sorted.
+ * @param func A function pointer that can handle comparing the list data nodes.
+ * @param data reference value to search.
+ * @return 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).
+ *
+ * @see eina_list_search_sorted()
+ * @see eina_list_sort()
+ * @see eina_list_sorted_merge()
+ * @see eina_list_search_unsorted_list()
+ * @see eina_list_search_sorted_near_list()
+ */
EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data);
+
+/**
+ * @brief Returns node data if it is in the sorted list.
+ *
+ * @param list The list to search for data, @b must be sorted.
+ * @param func A function pointer that can handle comparing the list data nodes.
+ * @param data reference value to search.
+ * @return the node value (@c 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).
+ *
+ * @see eina_list_search_sorted_list()
+ * @see eina_list_sort()
+ * @see eina_list_sorted_merge()
+ * @see eina_list_search_unsorted_list()
+ */
EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
+
+/**
+ * @brief Returns node if data is in the unsorted list.
+ *
+ * @param list The list to search for data, may be unsorted.
+ * @param func A function pointer that can handle comparing the list data nodes.
+ * @param data reference value to search.
+ * @return 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.
+ *
+ * @see eina_list_search_sorted_list()
+ * @see eina_list_search_unsorted()
+ */
EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data);
+
+/**
+ * @brief Returns node data if it is in the unsorted list.
+ *
+ * @param list The list to search for data, may be unsorted.
+ * @param func A function pointer that can handle comparing the list data nodes.
+ * @param data reference value to search.
+ * @return the node value (@c 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.
+ *
+ * @see eina_list_search_sorted()
+ * @see eina_list_search_unsorted_list()
+ */
EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
+
+/**
+ * @brief Returned a new iterator associated to a list.
+ *
+ * @param list The list.
+ * @return A new iterator.
+ *
+ * This function returns a newly allocated iterator associated to @p
+ * list. If @p list is @c NULL or the count member of @p list is less
+ * or equal than 0, this function still returns a valid iterator that
+ * will always return false on eina_iterator_next(), thus keeping API
+ * sane.
+ *
+ * If the memory can not be allocated, NULL is returned and
+ * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
+ *
+ * @warning 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!
+ */
EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Returned a new reversed iterator associated to a list.
+ *
+ * @param list The list.
+ * @return A new iterator.
+ *
+ * This function returns a newly allocated iterator associated to @p
+ * list. If @p list is @c NULL or the count member of @p list is less
+ * or equal than 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.
+ *
+ * If the memory can not be allocated, NULL is returned and
+ * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
+ *
+ * @warning 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!
+ */
EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Returned a new accessor associated to a list.
+ *
+ * @param list The list.
+ * @return A new accessor.
+ *
+ * This function returns a newly allocated accessor associated to
+ * @p list. If @p list is @c NULL or the count member of @p list is
+ * less or equal than 0, this function returns NULL. If the memory can
+ * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
+ * set. Otherwise, a valid accessor is returned.
+ */
EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @}
*/
+/**
+ * @}
+ */
+
#endif /* EINA_LIST_H_ */
* API *
*============================================================================*/
-/**
- * @addtogroup Eina_List_Group List
- *
- * @brief These functions provide double linked list management.
- *
- * For more information, you can look at the @ref tutorial_list_page.
- *
- * @{
- */
-
-/**
- * @brief Append the given data to the given linked list.
- *
- * @param list The given list.
- * @param data The data to append.
- * @return A list pointer.
- *
- * This function appends @p data to @p list. If @p list is @c 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.
- *
- * @code
- * Eina_List *list = NULL;
- * extern void *my_data;
- *
- * list = eina_list_append(list, my_data);
- * if (eina_error_get())
- * {
- * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
- * exit(-1);
- * }
- * @endcode
- */
EAPI Eina_List *
eina_list_append(Eina_List *list, const void *data)
{
return list;
}
-/**
- * @brief Prepends the given data to the given linked list.
- *
- * @param list The given list.
- * @param data The data to prepend.
- * @return A list pointer.
- *
- * This function prepends @p data to @p list. If @p list is @c 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:
- * @code
- * Eina_List *list = NULL;
- * extern void *my_data;
- *
- * list = eina_list_prepend(list, my_data);
- * if (eina_error_get())
- * {
- * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
- * exit(-1);
- * }
- * @endcode
- */
EAPI Eina_List *
eina_list_prepend(Eina_List *list, const void *data)
{
return new_l;
}
-/**
- * @brief Insert the given data into the given linked list after the specified data.
- *
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The data to insert after.
- * @return A list pointer.
- *
- * This function inserts @p data to @p list after @p relative. If
- * @p relative is not in the list, @p data is appended to the end of
- * the list. If @p list is @c NULL, a new list is returned. If there
- * are multiple instances of @p relative in the list, @p 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.
- *
- * @code
- * Eina_List *list = NULL;
- * extern void *my_data;
- * extern void *relative_member;
- *
- * list = eina_list_append(list, relative_member);
- * if (eina_error_get())
- * {
- * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
- * exit(-1);
- * }
- * list = eina_list_append_relative(list, my_data, relative_member);
- * if (eina_error_get())
- * {
- * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
- * exit(-1);
- * }
- * @endcode
- */
EAPI Eina_List *
eina_list_append_relative(Eina_List *list,
const void *data,
return eina_list_append(list, data);
}
-/**
- * @brief Append a list node to a linked list after the specified member
- *
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The list node to insert after.
- * @return A list pointer.
- *
- * This function inserts @p data to @p list after the list node
- * @p relative. If @p list or @p relative are @c NULL, @p data is just
- * appended to @p list using eina_list_append(). If @p list is
- * @c NULL, a new list is returned. If there are multiple instances
- * of @p relative in the list, @p 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.
- */
EAPI Eina_List *
eina_list_append_relative_list(Eina_List *list,
const void *data,
return list;
}
-/**
- * @brief Prepend a data pointer to a linked list before the specified member
- *
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The data to insert before.
- * @return A list pointer.
- *
- * This function inserts @p data to @p list before @p relative. If
- * @p relative is not in the list, @p data is prepended to the list
- * with eina_list_prepend(). If @p list is @c NULL, a new list is
- * returned. If there are multiple instances of @p relative in the
- * list, @p 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.
- *
- * @code
- * Eina_List *list = NULL;
- * extern void *my_data;
- * extern void *relative_member;
- *
- * list = eina_list_append(list, relative_member);
- * if (eina_error_get_error())
- * {
- * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
- * exit(-1);
- * }
- * list = eina_list_prepend_relative(list, my_data, relative_member);
- * if (eina_error_get())
- * {
- * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
- * exit(-1);
- * }
- * @endcode
- */
EAPI Eina_List *
eina_list_prepend_relative(Eina_List *list,
const void *data,
return eina_list_prepend(list, data);
}
-/**
- * @brief Prepend a list node to a linked list before the specified member
- *
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The list node to insert before.
- * @return A list pointer.
- *
- * This function inserts @p data to @p list before the list node
- * @p relative. If @p list or @p relative are @c NULL, @p data is just
- * prepended to @p list using eina_list_prepend(). If @p list is
- * @c NULL, a new list is returned. If there are multiple instances
- * of @p relative in the list, @p 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.
- */
EAPI Eina_List *
eina_list_prepend_relative_list(Eina_List *list,
const void *data,
return new_l;
}
-/**
- * @brief Insert a new node into a sorted list.
- *
- * @param list The given linked list, @b must be sorted.
- * @param func The function called for the sort.
- * @param data The data to insert sorted.
- * @return A list pointer.
- *
- * This function inserts values into a linked list assuming it was
- * sorted and the result will be sorted. If @p list is @c NULLL, 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. See eina_error_get().
- *
- * @note O(log2(n)) comparisons (calls to @p 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).
- */
EAPI Eina_List *
eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data)
{
return eina_list_prepend_relative_list(list, data, lnear);
}
-/**
- * @brief Remove the first instance of the specified data from the given list.
- *
- * @param list The given list.
- * @param data The specified data.
- * @return A list pointer.
- *
- * This function removes the first instance of @p data from
- * @p list. If the specified data is not in the given list (tihis
- * include the case where @p data is @c NULL), nothing is done. If
- * @p list is @c NULL, @c NULL is returned, otherwise a new list
- * pointer that should be used in place of the one passed to this
- * function.
- */
EAPI Eina_List *
eina_list_remove(Eina_List *list, const void *data)
{
return eina_list_remove_list(list, l);
}
-/**
- * @brief Remove the specified data.
- *
- * @param list The given linked list.
- * @param remove_list The list node which is to be removed.
- * @return A list pointer.
- *
- * This function removes the list node @p remove_list from @p list and
- * frees the list node structure @p remove_list. If @p list is
- * @c NULL, this function returns @c NULL. If @p remove_list is
- * @c NULL, it returns @p 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
- * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after
- * removing the current node).
- *
- * @code
- * 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;
- * }
- * }
- * @endcode
- */
EAPI Eina_List *
eina_list_remove_list(Eina_List *list, Eina_List *remove_list)
{
return return_l;
}
-/**
- * @brief Free an entire list and all the nodes, ignoring the data contained.
-
- * @param list The list to free
- * @return A NULL pointer
- *
- * This function frees all the nodes of @p list. It does not free the
- * data of the nodes. To free them, use #EINA_LIST_FREE.
- */
EAPI Eina_List *
eina_list_free(Eina_List *list)
{
return NULL;
}
-/**
- * @brief Move the specified data to the head of the list.
- *
- * @param list The list handle to move the data.
- * @param move_list The list node to move.
- * @return A new list handle to replace the old one
- *
- * This function move @p move_list to the front of @p list. If list is
- * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
- * @p list is returned. Otherwise, a new list pointer that should be
- * used in place of the one passed to this function.
- *
- * Example:
- * @code
- * 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;
- * }
- * }
- * @endcode
- */
EAPI Eina_List *
eina_list_promote_list(Eina_List *list, Eina_List *move_list)
{
return move_list;
}
-/**
- * @brief Move the specified data to the tail of the list.
- *
- * @param list The list handle to move the data.
- * @param move_list The list node to move.
- * @return A new list handle to replace the old one
- *
- * This function move @p move_list to the back of @p list. If list is
- * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
- * @p list is returned. Otherwise, a new list pointer that should be
- * used in place of the one passed to this function.
- *
- * Example:
- * @code
- * 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;
- * }
- * }
- * @endcode
- */
EAPI Eina_List *
eina_list_demote_list(Eina_List *list, Eina_List *move_list)
{
return list;
}
-/**
- * @brief Find a member of a list and return the member.
- *
- * @param list The list to search for a data.
- * @param data The data pointer to find in the list.
- * @return The found member data pointer if found, @c NULL otherwise.
- *
- * This function searches in @p list from beginning to end for the
- * first member whose data pointer is @p data. If it is found, @p data
- * will be returned, otherwise NULL will be returned.
- *
- * Example:
- * @code
- * 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);
- * }
- * @endcode
- */
EAPI void *
eina_list_data_find(const Eina_List *list, const void *data)
{
return NULL;
}
-/**
- * @brief Move a data pointer from one list to another
- *
- * @param to The list to move the data to
- * @param from The list to move from
- * @param data The data to move
- * @return #EINA_TRUE on success, else #EINA_FALSE
- *
- * This function is a shortcut for doing the following:
- * to = eina_list_append(to, data);
- * from = eina_list_remove(from, data);
- */
EAPI Eina_Bool
eina_list_move(Eina_List **to, Eina_List **from, void *data)
{
return EINA_TRUE;
}
-/**
- * @brief Move a list node from one list to another
- *
- * @param to The list to move the data to
- * @param from The list to move from
- * @param data The list node containing the data to move
- * @return #EINA_TRUE on success, else #EINA_FALSE
- *
- * This function is a shortcut for doing the following:
- * to = eina_list_append(to, data->data);
- * from = eina_list_remove_list(from, data);
- */
EAPI Eina_Bool
eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data)
{
return EINA_TRUE;
}
-/**
- * @brief Find a member of a list and return the list node containing that member.
- *
- * @param list The list to search for data.
- * @param data The data pointer to find in the list.
- * @return The found members list node on success, @c NULL otherwise.
- *
- * This function searches in @p list from beginning to end for the
- * first member whose data pointer is @p data. If it is found, the
- * list node containing the specified member is returned, otherwise
- * @c NULL is returned.
- */
EAPI Eina_List *
eina_list_data_find_list(const Eina_List *list, const void *data)
{
return NULL;
}
-/**
- * @brief Get the nth member's data pointer in a list.
- *
- * @param list The list to get the specified member number from.
- * @param n The number of the element (0 being the first).
- * @return The data pointer stored in the specified element.
- *
- * This function returns the data pointer of element number @p n, in
- * the @p list. The first element in the array is element number 0. If
- * the element number @p n does not exist, @c NULL is
- * returned. Otherwise, the data of the found element is returned.
- */
EAPI void *
eina_list_nth(const Eina_List *list, unsigned int n)
{
return l ? l->data : NULL;
}
-/**
- * @brief Get the nth member's list node in a list.
- *
- * @param list The list to get the specfied member number from.
- * @param n The number of the element (0 being the first).
- * @return The list node stored in the numbered element.
- *
- * This function returns the list node of element number @p n, in
- * @ list. The first element in the array is element number 0. If the
- * element number @p n does not exist or @p list is @c NULL or @p n is
- * greater than the count of elements in @p list minus 1, @c NULL is
- * returned. Otherwise the list node stored in the numbered element is
- * returned.
- */
EAPI Eina_List *
eina_list_nth_list(const Eina_List *list, unsigned int n)
{
abort();
}
-/**
- * @brief Reverse all the elements in the list.
- *
- * @param list The list to reverse.
- * @return The list head after it has been reversed.
- *
- * This function reverses the order of all elements in @p list, so the
- * last member is now first, and so on. If @p list is @c NULL, this
- * functon returns @c NULL.
- *
- * @note @b in-place: this will change the given list, so you should
- * now point to the new list head that is returned by this function.
- *
- * @see eina_list_reverse_clone()
- * @see eina_list_iterator_reversed_new()
- */
EAPI Eina_List *
eina_list_reverse(Eina_List *list)
{
return list;
}
-/**
- * @brief Clone (copy) all the elements in the list in reverse order.
- *
- * @param list The list to reverse.
- * @return The new list that has been reversed.
- *
- * This function reverses the order of all elements in @p list, so the
- * last member is now first, and so on. If @p list is @c NULL, this
- * functon returns @c NULL. This returns a copy of the given list.
- *
- * @note @b copy: this will copy the list and you should then
- * eina_list_free() when it is not required anymore.
- *
- * @see eina_list_reverse()
- * @see eina_list_clone()
- */
EAPI Eina_List *
eina_list_reverse_clone(const Eina_List *list)
{
return lclone;
}
-/**
- * @brief Clone (copy) all the elements in the list in exact order.
- *
- * @param list The list to clone.
- * @return The new list that has been cloned.
- *
- * This function clone in order of all elements in @p list. If @p list
- * is @c NULL, this functon returns @c NULL. This returns a copy of
- * the given list.
- *
- * @note @b copy: this will copy the list and you should then
- * eina_list_free() when it is not required anymore.
- *
- * @see eina_list_reverse_clone()
- */
EAPI Eina_List *
eina_list_clone(const Eina_List *list)
{
return lclone;
}
-/**
- * @brief Sort a list according to the ordering func will return.
- *
- * @param list The list handle to sort.
- * @param size The length of the list to sort.
- * @param func A function pointer that can handle comparing the list data
- * nodes.
- * @return the new head of list.
- *
- * This function sorts @p list. @p size if the number of the first
- * element to sort. If @p size is 0 or greater than the number of
- * elements in @p list, all the elements are sorted. @p func is used to
- * compare two elements of @p list. If @p list or @p func are @c NULL,
- * this function returns @c NULL.
- *
- * @note @b in-place: this will change the given list, so you should
- * now point to the new list head that is returned by this function.
- *
- * @note worst case is O(n * log2(n)) comparisons (calls to func()),
- * O(n) comparisons average case. That means that for 1,000,000 list
- * elements, sort will usually do 1,000,000 comparisons, but may do up
- * to 20,000,000.
- *
- * Example:
- * @code
- * int
- * sort_cb(const void *d1, const void *d2)
- * {
- * const char *txt = NULL;
- * const char *txt2 = NULL;
- *
- * 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);
- * @endcode
- */
EAPI Eina_List *
eina_list_sort(Eina_List *list, unsigned int size, Eina_Compare_Cb func)
{
return list;
}
-/**
- * @brief Merge two list.
- *
- * @param left Head list to merge.
- * @param right Tail list to merge.
- * @return A new merged list.
- *
- * This function put right at the end of left and return the head.
- *
- * Both left and right does not exist anymore after the merge.
- *
- * @note merge cost is O(n), being @b 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).
- */
EAPI Eina_List *
eina_list_merge(Eina_List *left, Eina_List *right)
{
}
-/**
- * @brief Split a list into 2 lists.
- *
- * @param list List to split.
- * @param relative The list will be split after @p relative.
- * @param right The head of the new right list.
- * @return The new left list
- *
- * This function split @p list into two lists ( left and right ) after the node @p relative. @p Relative
- * will become the last node of the left list. If @p list or @p right are NULL list is returns.
- * If @p relative is NULL right is set to @p list and NULL is returns.
- * If @p relative is the last node of @p list list is returns and @p right is set to NULL.
- *
- * list does not exist anymore after the split.
- *
- */
EAPI Eina_List *
eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right)
{
return list;
}
-/**
- * @brief Merge two sorted list according to the ordering func will return.
- *
- * @param left First list to merge.
- * @param right Second list to merge.
- * @param func A function pointer that can handle comparing the list data
- * nodes.
- * @return A new sorted list.
- *
- * This function compare the head of @p left and @p 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 does not exist anymore after the merge.
- * If @p func is NULL, it will return NULL.
- *
- * Example:
- * @code
- * 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);
- * @endcode
- */
EAPI Eina_List *
eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func)
{
return ret;
}
-/**
- * @brief Returns node nearest to data is in the sorted list.
- *
- * @param list The list to search for data, @b must be sorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @param 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().
- * @return the nearest node, NULL if not found.
- *
- * This can be used to check if some value is inside the list and get
- * the nearest 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, otherwise you want to insert it
- * sorted. In this case you get the result of this function and either
- * append or prepend the value.
- *
- * @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).
- *
- * @see eina_list_search_sorted_list()
- * @see eina_list_sort()
- * @see eina_list_sorted_merge()
- */
EAPI Eina_List *
eina_list_search_sorted_near_list(const Eina_List *list,
Eina_Compare_Cb func,
return (Eina_List *)ct;
}
-/**
- * @brief Returns node if data is in the sorted list.
- *
- * @param list The list to search for data, @b must be sorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return 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).
- *
- * @see eina_list_search_sorted()
- * @see eina_list_sort()
- * @see eina_list_sorted_merge()
- * @see eina_list_search_unsorted_list()
- * @see eina_list_search_sorted_near_list()
- */
EAPI Eina_List *
eina_list_search_sorted_list(const Eina_List *list,
Eina_Compare_Cb func,
}
-/**
- * @brief Returns node data if it is in the sorted list.
- *
- * @param list The list to search for data, @b must be sorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return the node value (@c 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).
- *
- * @see eina_list_search_sorted_list()
- * @see eina_list_sort()
- * @see eina_list_sorted_merge()
- * @see eina_list_search_unsorted_list()
- */
EAPI void *
eina_list_search_sorted(const Eina_List *list,
Eina_Compare_Cb func,
return eina_list_data_get(eina_list_search_sorted_list(list, func, data));
}
-/**
- * @brief Returns node if data is in the unsorted list.
- *
- * @param list The list to search for data, may be unsorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return 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.
- *
- * @see eina_list_search_sorted_list()
- * @see eina_list_search_unsorted()
- */
EAPI Eina_List *
eina_list_search_unsorted_list(const Eina_List *list,
Eina_Compare_Cb func,
return NULL;
}
-/**
- * @brief Returns node data if it is in the unsorted list.
- *
- * @param list The list to search for data, may be unsorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return the node value (@c 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.
- *
- * @see eina_list_search_sorted()
- * @see eina_list_search_unsorted_list()
- */
EAPI void *
eina_list_search_unsorted(const Eina_List *list,
Eina_Compare_Cb func,
}
-/**
- * @brief Returned a new iterator associated to a list.
- *
- * @param list The list.
- * @return A new iterator.
- *
- * This function returns a newly allocated iterator associated to @p
- * list. If @p list is @c NULL or the count member of @p list is less
- * or equal than 0, this function still returns a valid iterator that
- * will always return false on eina_iterator_next(), thus keeping API
- * sane.
- *
- * If the memory can not be allocated, NULL is returned and
- * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
- * returned.
- *
- * @warning 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!
- */
EAPI Eina_Iterator *
eina_list_iterator_new(const Eina_List *list)
{
return &it->iterator;
}
-/**
- * @brief Returned a new reversed iterator associated to a list.
- *
- * @param list The list.
- * @return A new iterator.
- *
- * This function returns a newly allocated iterator associated to @p
- * list. If @p list is @c NULL or the count member of @p list is less
- * or equal than 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.
- *
- * If the memory can not be allocated, NULL is returned and
- * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
- * returned.
- *
- * @warning 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!
- */
EAPI Eina_Iterator *
eina_list_iterator_reversed_new(const Eina_List *list)
{
return &it->iterator;
}
-/**
- * @brief Returned a new accessor associated to a list.
- *
- * @param list The list.
- * @return A new accessor.
- *
- * This function returns a newly allocated accessor associated to
- * @p list. If @p list is @c NULL or the count member of @p list is
- * less or equal than 0, this function returns NULL. If the memory can
- * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
- * set. Otherwise, a valid accessor is returned.
- */
EAPI Eina_Accessor *
eina_list_accessor_new(const Eina_List *list)
{
return &ac->accessor;
}
-
-/**
- * @}
- */
projects / framework / uifw / eina.git / commitdiff