Eina: Improvements to eina_list's documentation.
SVN revision: 61088
This commit is contained in:
parent
0705400fbf
commit
6b3b2c15b5
|
@ -27,6 +27,8 @@ main(int argc, char **argv)
|
|||
l = eina_list_data_find_list(list, "aerilon");
|
||||
eina_list_data_set(l, "aquarius");
|
||||
|
||||
printf("size: %d\n", eina_list_count(list));
|
||||
|
||||
r_list = eina_list_reverse_clone(list);
|
||||
|
||||
itr = eina_list_iterator_new(r_list);
|
||||
|
|
|
@ -21,8 +21,11 @@ main(int argc, char **argv)
|
|||
list = eina_list_append(list, eina_stringshare_add("Six"));
|
||||
list = eina_list_append(list, eina_stringshare_add("Sharon"));
|
||||
|
||||
EINA_LIST_FOREACH(list, l, list_data)
|
||||
printf("%s\n", (const char*)list_data);
|
||||
for(l = list; l; l = eina_list_next(l))
|
||||
printf("%s\n", (char*)l->data);
|
||||
|
||||
for(l = eina_list_last(list); l; l = eina_list_prev(l))
|
||||
printf("%s\n", (char*)eina_list_data_get(l));
|
||||
|
||||
EINA_LIST_FREE(list, list_data)
|
||||
eina_stringshare_del(list_data);
|
||||
|
|
|
@ -19,26 +19,6 @@
|
|||
#ifndef EINA_LIST_INLINE_H_
|
||||
#define EINA_LIST_INLINE_H_
|
||||
|
||||
/**
|
||||
* @addtogroup Eina_List_Group List
|
||||
*
|
||||
* @brief These functions provide list management.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Get the last list node in the list.
|
||||
*
|
||||
* @param list The list to get the last list node from.
|
||||
* @return The last list node in the list.
|
||||
*
|
||||
* This function returns the last list node in the list @p list. If
|
||||
* @p list is @c NULL or empty, @c NULL is returned.
|
||||
*
|
||||
* This is a order-1 operation (it takes the same short time
|
||||
* regardless of the length of the list).
|
||||
*/
|
||||
static inline Eina_List *
|
||||
eina_list_last(const Eina_List *list)
|
||||
{
|
||||
|
@ -46,16 +26,6 @@ eina_list_last(const Eina_List *list)
|
|||
return list->accounting->last;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get the next list node after the specified list node.
|
||||
*
|
||||
* @param list The list node to get the next list node from
|
||||
* @return The next list node on success, @c NULL otherwise.
|
||||
*
|
||||
* This function returns the next list node after the current one in
|
||||
* @p list. It is equivalent to list->next. If @p list is @c NULL or
|
||||
* if no next list node exists, it returns @c NULL.
|
||||
*/
|
||||
static inline Eina_List *
|
||||
eina_list_next(const Eina_List *list)
|
||||
{
|
||||
|
@ -63,17 +33,6 @@ eina_list_next(const Eina_List *list)
|
|||
return list->next;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get the previous list node before the specified list node.
|
||||
*
|
||||
* @param list The list node to get the previous list node from.
|
||||
* @return The previous list node o success, @c NULL otherwise.
|
||||
* if no previous list node exists
|
||||
*
|
||||
* This function returns the previous list node before the current one
|
||||
* in @p list. It is equivalent to list->prev. If @p list is @c NULL or
|
||||
* if no previous list node exists, it returns @c NULL.
|
||||
*/
|
||||
static inline Eina_List *
|
||||
eina_list_prev(const Eina_List *list)
|
||||
{
|
||||
|
@ -81,16 +40,6 @@ eina_list_prev(const Eina_List *list)
|
|||
return list->prev;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get the list node data member.
|
||||
*
|
||||
* @param list The list node to get the data member of.
|
||||
* @return The data member from the list node.
|
||||
*
|
||||
* This function returns the data member of the specified list node @p
|
||||
* list. It is equivalent to list->data. If @p list is @c NULL, this
|
||||
* function returns @c NULL.
|
||||
*/
|
||||
static inline void *
|
||||
eina_list_data_get(const Eina_List *list)
|
||||
{
|
||||
|
@ -98,17 +47,6 @@ eina_list_data_get(const Eina_List *list)
|
|||
return list->data;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Set the list node data member.
|
||||
*
|
||||
* @param list The list node to get the data member of.
|
||||
* @param data The data member to the list node.
|
||||
* @return The previous data value.
|
||||
*
|
||||
* This function set the data member @p data of the specified list node
|
||||
* @p list. It returns the previous data of the node. If @p list is
|
||||
* @c NULL, this function returns @c NULL.
|
||||
*/
|
||||
static inline void *
|
||||
eina_list_data_set(Eina_List *list, const void *data)
|
||||
{
|
||||
|
@ -119,18 +57,6 @@ eina_list_data_set(Eina_List *list, const void *data)
|
|||
return tmp;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get the count of the number of items in a list.
|
||||
*
|
||||
* @param list The list whose count to return.
|
||||
* @return The number of members in the list.
|
||||
*
|
||||
* This function returns how many members @p list contains. If the
|
||||
* list is @c NULL, 0 is returned.
|
||||
*
|
||||
* NB: This is an order-1 operation and takes the same time regardless
|
||||
* of the length of the list.
|
||||
*/
|
||||
static inline unsigned int
|
||||
eina_list_count(const Eina_List *list)
|
||||
{
|
||||
|
@ -138,8 +64,4 @@ eina_list_count(const Eina_List *list)
|
|||
return list->accounting->count;
|
||||
}
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
#endif /* EINA_LIST_INLINE_H_ */
|
||||
|
|
|
@ -168,7 +168,11 @@
|
|||
* To replace an element in the list it is not necessary to remove it and then
|
||||
* add with the new value, it is possible to just change the value of a node:
|
||||
* @until aquarius
|
||||
*
|
||||
*
|
||||
* We will now take a peek to see if the list still has the right number of
|
||||
* elements:
|
||||
* @until printf
|
||||
*
|
||||
* Now that the list is in alphabetical order let's create a copy of it in
|
||||
* reverse order and print every element to see if worked as expected:
|
||||
* @until iterator_free
|
||||
|
@ -202,7 +206,10 @@
|
|||
* @skip #include
|
||||
* @until Sharon
|
||||
*
|
||||
* The most common way of iterating over a list:
|
||||
* This time we are going to iterate over our list in a different way:
|
||||
* @until printf
|
||||
*
|
||||
* And now we are going to iterate over the list backwards:
|
||||
* @until printf
|
||||
*
|
||||
* And now we need to free up the memory allocated during creation of the list:
|
||||
|
@ -257,6 +264,11 @@
|
|||
* @ref eina_list_data_find), the @a list versions of these functions operate
|
||||
* on @ref Eina_List nodes.
|
||||
*
|
||||
* @warning You must @b always use the pointer to the first element of the list
|
||||
* as the list!
|
||||
* @warning You must @b never use a pointer to an element in the middle of the
|
||||
* list as the list!
|
||||
*
|
||||
* Here are some examples of @ref Eina_List usage:
|
||||
* @li @ref list_01_example_page
|
||||
* @li @ref list_02_example_page
|
||||
|
@ -351,6 +363,8 @@ struct _Eina_List_Accounting
|
|||
* exit(-1);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list(or NULL).
|
||||
*/
|
||||
EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -382,6 +396,8 @@ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) E
|
|||
* exit(-1);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -423,6 +439,8 @@ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data)
|
|||
* exit(-1);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -443,6 +461,8 @@ EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void
|
|||
* 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 @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
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;
|
||||
|
||||
|
@ -484,6 +504,8 @@ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const
|
|||
* exit(-1);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -504,6 +526,8 @@ EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const voi
|
|||
* 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 @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
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;
|
||||
|
||||
|
@ -528,6 +552,8 @@ EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, cons
|
|||
* 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 @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
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;
|
||||
|
||||
|
@ -545,6 +571,8 @@ EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare
|
|||
* @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.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -581,6 +609,8 @@ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) E
|
|||
* }
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -613,6 +643,8 @@ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *rem
|
|||
* }
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -645,6 +677,8 @@ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *mo
|
|||
* }
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *move_list);
|
||||
|
||||
|
@ -670,6 +704,8 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov
|
|||
* printf("Found member %p\n", my_data);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -684,6 +720,8 @@ EAPI void *eina_list_data_find(const Eina_List *list, const void
|
|||
* 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.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
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;
|
||||
|
||||
|
@ -699,6 +737,8 @@ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const
|
|||
* This function is a shortcut for doing the following:
|
||||
* to = eina_list_append(to, data);
|
||||
* from = eina_list_remove(from, data);
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data);
|
||||
|
||||
|
@ -713,6 +753,8 @@ EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void
|
|||
* This function is a shortcut for doing the following:
|
||||
* to = eina_list_append(to, data->data);
|
||||
* from = eina_list_remove_list(from, data);
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data);
|
||||
|
||||
|
@ -740,6 +782,10 @@ EAPI Eina_List *eina_list_free(Eina_List *list);
|
|||
* 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.
|
||||
*
|
||||
* @note Worst case is O(n).
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -757,6 +803,10 @@ EAPI void *eina_list_nth(const Eina_List *list, unsigned int n)
|
|||
* 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.
|
||||
*
|
||||
* @note Worst case is O(n).
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -774,6 +824,8 @@ EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned in
|
|||
* @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.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_reverse_clone()
|
||||
* @see eina_list_iterator_reversed_new()
|
||||
*/
|
||||
|
@ -793,6 +845,8 @@ EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_R
|
|||
* @note @b copy: this will copy the list and you should then
|
||||
* eina_list_free() when it is not required anymore.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_reverse()
|
||||
* @see eina_list_clone()
|
||||
*/
|
||||
|
@ -812,6 +866,8 @@ EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_W
|
|||
* @note @b copy: this will copy the list and you should then
|
||||
* eina_list_free() when it is not required anymore.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_reverse_clone()
|
||||
*/
|
||||
EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT;
|
||||
|
@ -857,6 +913,8 @@ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUS
|
|||
*
|
||||
* list = eina_list_sort(list, eina_list_count(list), sort_cb);
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int size, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -875,6 +933,8 @@ EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int size, Ei
|
|||
* @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).
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -913,6 +973,8 @@ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EI
|
|||
*
|
||||
* list = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
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;
|
||||
|
||||
|
@ -932,6 +994,7 @@ EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *ri
|
|||
*
|
||||
* list does not exist anymore after the split.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -948,6 +1011,12 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela
|
|||
* 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 function searches for a node containing @p data as it's data in @p list,
|
||||
* if such a node exists it will be returned and @p result_cmp will be @p 0. If
|
||||
* the data of no node in @p list is equal to @p data, the node with the nearest
|
||||
* value to that will be returned and @p result_cmp will be the return value of
|
||||
* @p func with @p 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:
|
||||
|
@ -983,6 +1052,8 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela
|
|||
* the correct node can be costly, consider worst case to be almost
|
||||
* O(n) pointer dereference (list walk).
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_search_sorted_list()
|
||||
* @see eina_list_sort()
|
||||
* @see eina_list_sorted_merge()
|
||||
|
@ -1015,6 +1086,8 @@ EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *li
|
|||
* time, so walking to the correct node can be costly, consider worst
|
||||
* case to be almost O(n) pointer dereference (list walk).
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_search_sorted()
|
||||
* @see eina_list_sort()
|
||||
* @see eina_list_sorted_merge()
|
||||
|
@ -1050,6 +1123,8 @@ EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, E
|
|||
* time, so walking to the correct node can be costly, consider worst
|
||||
* case to be almost O(n) pointer dereference (list walk).
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_search_sorted_list()
|
||||
* @see eina_list_sort()
|
||||
* @see eina_list_sorted_merge()
|
||||
|
@ -1076,6 +1151,8 @@ EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_C
|
|||
* that is for 1,000,000 elements list it may walk and compare
|
||||
* 1,000,000 nodes.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_search_sorted_list()
|
||||
* @see eina_list_search_unsorted()
|
||||
*/
|
||||
|
@ -1101,19 +1178,101 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list,
|
|||
* that is for 1,000,000 elements list it may walk and compare
|
||||
* 1,000,000 nodes.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @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);
|
||||
|
||||
/**
|
||||
* @brief Get the last list node in the list.
|
||||
*
|
||||
* @param list The list to get the last list node from.
|
||||
* @return The last list node in the list.
|
||||
*
|
||||
* This function returns the last list node in the list @p list. If
|
||||
* @p list is @c NULL or empty, @c NULL is returned.
|
||||
*
|
||||
* This is a order-1 operation (it takes the same short time
|
||||
* regardless of the length of the list).
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Get the next list node after the specified list node.
|
||||
*
|
||||
* @param list The list node to get the next list node from
|
||||
* @return The next list node on success, @c NULL otherwise.
|
||||
*
|
||||
* This function returns the next list node after the current one in
|
||||
* @p list. It is equivalent to list->next. If @p list is @c NULL or
|
||||
* if no next list node exists, it returns @c NULL.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Get the previous list node before the specified list node.
|
||||
*
|
||||
* @param list The list node to get the previous list node from.
|
||||
* @return The previous list node o success, @c NULL otherwise.
|
||||
* if no previous list node exists
|
||||
*
|
||||
* This function returns the previous list node before the current one
|
||||
* in @p list. It is equivalent to list->prev. If @p list is @c NULL or
|
||||
* if no previous list node exists, it returns @c NULL.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Get the list node data member.
|
||||
*
|
||||
* @param list The list node to get the data member of.
|
||||
* @return The data member from the list node.
|
||||
*
|
||||
* This function returns the data member of the specified list node @p
|
||||
* list. It is equivalent to list->data. If @p list is @c NULL, this
|
||||
* function returns @c NULL.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Set the list node data member.
|
||||
*
|
||||
* @param list The list node to get the data member of.
|
||||
* @param data The data member to the list node.
|
||||
* @return The previous data value.
|
||||
*
|
||||
* This function set the data member @p data of the specified list node
|
||||
* @p list. It returns the previous data of the node. If @p list is
|
||||
* @c NULL, this function returns @c NULL.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
static inline void *eina_list_data_set(Eina_List *list, const void *data) EINA_PURE;
|
||||
|
||||
/**
|
||||
* @brief Get the count of the number of items in a list.
|
||||
*
|
||||
* @param list The list whose count to return.
|
||||
* @return The number of members in the list.
|
||||
*
|
||||
* This function returns how many members @p list contains. If the
|
||||
* list is @c NULL, 0 is returned.
|
||||
*
|
||||
* NB: This is an order-1 operation and takes the same time regardless
|
||||
* of the length of the list.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
|
||||
|
||||
|
||||
|
@ -1133,6 +1292,8 @@ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
|
|||
* #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
|
||||
* returned.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @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!
|
||||
|
@ -1158,6 +1319,8 @@ EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MA
|
|||
* #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
|
||||
* returned.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @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!
|
||||
|
@ -1176,6 +1339,8 @@ EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list
|
|||
* 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.
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -1211,6 +1376,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
|||
* a list, since it iterates over the list twice.
|
||||
* For an optimized algorithm, use EINA_LIST_FREE().
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @warning 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
|
||||
|
@ -1259,6 +1426,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
|||
* a list, since it iterates over the list twice.
|
||||
* For an optimized algorithm, use EINA_LIST_FREE().
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @warning 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
|
||||
|
@ -1308,6 +1477,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
|||
* list = eina_list_remove_list(list, l);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
#define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \
|
||||
for (l = list, \
|
||||
|
@ -1354,6 +1525,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
|||
* list = eina_list_remove_list(list, l);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*/
|
||||
#define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \
|
||||
for (l = eina_list_last(list), \
|
||||
|
@ -1387,6 +1560,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
|||
* free(data);
|
||||
* @endcode
|
||||
*
|
||||
* @warning @p list must be a pointer to the first element of the list.
|
||||
*
|
||||
* @see eina_list_free()
|
||||
*/
|
||||
#define EINA_LIST_FREE(list, data) \
|
||||
|
|
Loading…
Reference in New Issue