doc: document alpm_list

Signed-off-by: Allan McRae <allan@archlinux.org>
This commit is contained in:
morganamilo 2020-12-07 22:19:47 +00:00 committed by Allan McRae
parent 50d2171ef0
commit 7b06b5407b
2 changed files with 294 additions and 255 deletions

View file

@ -32,23 +32,8 @@
#define SYMEXPORT __attribute__((visibility("default"))) #define SYMEXPORT __attribute__((visibility("default")))
#define SYMHIDDEN __attribute__((visibility("internal"))) #define SYMHIDDEN __attribute__((visibility("internal")))
/**
* @addtogroup alpm_list List Functions
* @brief Functions to manipulate alpm_list_t lists.
*
* These functions are designed to create, destroy, and modify lists of
* type alpm_list_t. This is an internal list type used by libalpm that is
* publicly exposed for use by frontends if desired.
*
* @{ */
/* Allocation */ /* Allocation */
/**
* @brief Free a list, but not the contained data.
*
* @param list the list to free
*/
void SYMEXPORT alpm_list_free(alpm_list_t *list) void SYMEXPORT alpm_list_free(alpm_list_t *list)
{ {
alpm_list_t *it = list; alpm_list_t *it = list;
@ -60,12 +45,6 @@ void SYMEXPORT alpm_list_free(alpm_list_t *list)
} }
} }
/**
* @brief Free the internal data of a list structure.
*
* @param list the list to free
* @param fn a free function for the internal data
*/
void SYMEXPORT alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn) void SYMEXPORT alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn)
{ {
alpm_list_t *it = list; alpm_list_t *it = list;
@ -83,28 +62,12 @@ void SYMEXPORT alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn)
/* Mutators */ /* Mutators */
/**
* @brief Add a new item to the end of the list.
*
* @param list the list to add to
* @param data the new item to be added to the list
*
* @return the resultant list
*/
alpm_list_t SYMEXPORT *alpm_list_add(alpm_list_t *list, void *data) alpm_list_t SYMEXPORT *alpm_list_add(alpm_list_t *list, void *data)
{ {
alpm_list_append(&list, data); alpm_list_append(&list, data);
return list; return list;
} }
/**
* @brief Add a new item to the end of the list.
*
* @param list the list to add to
* @param data the new item to be added to the list
*
* @return the newly added item
*/
alpm_list_t SYMEXPORT *alpm_list_append(alpm_list_t **list, void *data) alpm_list_t SYMEXPORT *alpm_list_append(alpm_list_t **list, void *data)
{ {
alpm_list_t *ptr; alpm_list_t *ptr;
@ -131,14 +94,6 @@ alpm_list_t SYMEXPORT *alpm_list_append(alpm_list_t **list, void *data)
return ptr; return ptr;
} }
/**
* @brief Duplicate and append a string to a list.
*
* @param list the list to append to
* @param data the string to duplicate and append
*
* @return the newly added item
*/
alpm_list_t SYMEXPORT *alpm_list_append_strdup(alpm_list_t **list, const char *data) alpm_list_t SYMEXPORT *alpm_list_append_strdup(alpm_list_t **list, const char *data)
{ {
alpm_list_t *ret; alpm_list_t *ret;
@ -151,15 +106,6 @@ alpm_list_t SYMEXPORT *alpm_list_append_strdup(alpm_list_t **list, const char *d
} }
} }
/**
* @brief Add items to a list in sorted order.
*
* @param list the list to add to
* @param data the new item to be added to the list
* @param fn the comparison function to use to determine order
*
* @return the resultant list
*/
alpm_list_t SYMEXPORT *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cmp fn) alpm_list_t SYMEXPORT *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cmp fn)
{ {
if(!fn || !list) { if(!fn || !list) {
@ -202,17 +148,6 @@ alpm_list_t SYMEXPORT *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_
} }
} }
/**
* @brief Join two lists.
* The two lists must be independent. Do not free the original lists after
* calling this function, as this is not a copy operation. The list pointers
* passed in should be considered invalid after calling this function.
*
* @param first the first list
* @param second the second list
*
* @return the resultant joined list
*/
alpm_list_t SYMEXPORT *alpm_list_join(alpm_list_t *first, alpm_list_t *second) alpm_list_t SYMEXPORT *alpm_list_join(alpm_list_t *first, alpm_list_t *second)
{ {
alpm_list_t *tmp; alpm_list_t *tmp;
@ -235,15 +170,6 @@ alpm_list_t SYMEXPORT *alpm_list_join(alpm_list_t *first, alpm_list_t *second)
return first; return first;
} }
/**
* @brief Merge the two sorted sublists into one sorted list.
*
* @param left the first list
* @param right the second list
* @param fn comparison function for determining merge order
*
* @return the resultant list
*/
alpm_list_t SYMEXPORT *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right, alpm_list_t SYMEXPORT *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right,
alpm_list_fn_cmp fn) alpm_list_fn_cmp fn)
{ {
@ -305,15 +231,6 @@ alpm_list_t SYMEXPORT *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right,
return newlist; return newlist;
} }
/**
* @brief Sort a list of size `n` using mergesort algorithm.
*
* @param list the list to sort
* @param n the size of the list
* @param fn the comparison function for determining order
*
* @return the resultant list
*/
alpm_list_t SYMEXPORT *alpm_list_msort(alpm_list_t *list, size_t n, alpm_list_t SYMEXPORT *alpm_list_msort(alpm_list_t *list, size_t n,
alpm_list_fn_cmp fn) alpm_list_fn_cmp fn)
{ {
@ -339,15 +256,6 @@ alpm_list_t SYMEXPORT *alpm_list_msort(alpm_list_t *list, size_t n,
return list; return list;
} }
/**
* @brief Remove an item from the list.
* item is not freed; this is the responsibility of the caller.
*
* @param haystack the list to remove the item from
* @param item the item to remove from the list
*
* @return the resultant list
*/
alpm_list_t SYMEXPORT *alpm_list_remove_item(alpm_list_t *haystack, alpm_list_t SYMEXPORT *alpm_list_remove_item(alpm_list_t *haystack,
alpm_list_t *item) alpm_list_t *item)
{ {
@ -385,17 +293,6 @@ alpm_list_t SYMEXPORT *alpm_list_remove_item(alpm_list_t *haystack,
return haystack; return haystack;
} }
/**
* @brief Remove an item from the list.
*
* @param haystack the list to remove the item from
* @param needle the data member of the item we're removing
* @param fn the comparison function for searching
* @param data output parameter containing data of the removed item
*
* @return the resultant list
*/
alpm_list_t SYMEXPORT *alpm_list_remove(alpm_list_t *haystack, alpm_list_t SYMEXPORT *alpm_list_remove(alpm_list_t *haystack,
const void *needle, alpm_list_fn_cmp fn, void **data) const void *needle, alpm_list_fn_cmp fn, void **data)
{ {
@ -430,15 +327,6 @@ alpm_list_t SYMEXPORT *alpm_list_remove(alpm_list_t *haystack,
return haystack; return haystack;
} }
/**
* @brief Remove a string from a list.
*
* @param haystack the list to remove the item from
* @param needle the data member of the item we're removing
* @param data output parameter containing data of the removed item
*
* @return the resultant list
*/
alpm_list_t SYMEXPORT *alpm_list_remove_str(alpm_list_t *haystack, alpm_list_t SYMEXPORT *alpm_list_remove_str(alpm_list_t *haystack,
const char *needle, char **data) const char *needle, char **data)
{ {
@ -446,15 +334,6 @@ alpm_list_t SYMEXPORT *alpm_list_remove_str(alpm_list_t *haystack,
(alpm_list_fn_cmp)strcmp, (void **)data); (alpm_list_fn_cmp)strcmp, (void **)data);
} }
/**
* @brief Create a new list without any duplicates.
*
* This does NOT copy data members.
*
* @param list the list to copy
*
* @return a new list containing non-duplicate items
*/
alpm_list_t SYMEXPORT *alpm_list_remove_dupes(const alpm_list_t *list) alpm_list_t SYMEXPORT *alpm_list_remove_dupes(const alpm_list_t *list)
{ {
const alpm_list_t *lp = list; const alpm_list_t *lp = list;
@ -471,13 +350,6 @@ alpm_list_t SYMEXPORT *alpm_list_remove_dupes(const alpm_list_t *list)
return newlist; return newlist;
} }
/**
* @brief Copy a string list, including data.
*
* @param list the list to copy
*
* @return a copy of the original list
*/
alpm_list_t SYMEXPORT *alpm_list_strdup(const alpm_list_t *list) alpm_list_t SYMEXPORT *alpm_list_strdup(const alpm_list_t *list)
{ {
const alpm_list_t *lp = list; const alpm_list_t *lp = list;
@ -492,13 +364,6 @@ alpm_list_t SYMEXPORT *alpm_list_strdup(const alpm_list_t *list)
return newlist; return newlist;
} }
/**
* @brief Copy a list, without copying data.
*
* @param list the list to copy
*
* @return a copy of the original list
*/
alpm_list_t SYMEXPORT *alpm_list_copy(const alpm_list_t *list) alpm_list_t SYMEXPORT *alpm_list_copy(const alpm_list_t *list)
{ {
const alpm_list_t *lp = list; const alpm_list_t *lp = list;
@ -513,16 +378,6 @@ alpm_list_t SYMEXPORT *alpm_list_copy(const alpm_list_t *list)
return newlist; return newlist;
} }
/**
* @brief Copy a list and copy the data.
* Note that the data elements to be copied should not contain pointers
* and should also be of constant size.
*
* @param list the list to copy
* @param size the size of each data element
*
* @return a copy of the original list, data copied as well
*/
alpm_list_t SYMEXPORT *alpm_list_copy_data(const alpm_list_t *list, alpm_list_t SYMEXPORT *alpm_list_copy_data(const alpm_list_t *list,
size_t size) size_t size)
{ {
@ -546,13 +401,6 @@ alpm_list_t SYMEXPORT *alpm_list_copy_data(const alpm_list_t *list,
return newlist; return newlist;
} }
/**
* @brief Create a new list in reverse order.
*
* @param list the list to copy
*
* @return a new list in reverse order
*/
alpm_list_t SYMEXPORT *alpm_list_reverse(alpm_list_t *list) alpm_list_t SYMEXPORT *alpm_list_reverse(alpm_list_t *list)
{ {
const alpm_list_t *lp; const alpm_list_t *lp;
@ -580,14 +428,6 @@ alpm_list_t SYMEXPORT *alpm_list_reverse(alpm_list_t *list)
/* Accessors */ /* Accessors */
/**
* @brief Return nth element from list (starting from 0).
*
* @param list the list
* @param n the index of the item to find (n < alpm_list_count(list) IS needed)
*
* @return an alpm_list_t node for index `n`
*/
alpm_list_t SYMEXPORT *alpm_list_nth(const alpm_list_t *list, size_t n) alpm_list_t SYMEXPORT *alpm_list_nth(const alpm_list_t *list, size_t n)
{ {
const alpm_list_t *i = list; const alpm_list_t *i = list;
@ -597,13 +437,6 @@ alpm_list_t SYMEXPORT *alpm_list_nth(const alpm_list_t *list, size_t n)
return (alpm_list_t *)i; return (alpm_list_t *)i;
} }
/**
* @brief Get the next element of a list.
*
* @param node the list node
*
* @return the next element, or NULL when no more elements exist
*/
inline alpm_list_t SYMEXPORT *alpm_list_next(const alpm_list_t *node) inline alpm_list_t SYMEXPORT *alpm_list_next(const alpm_list_t *node)
{ {
if(node) { if(node) {
@ -613,13 +446,6 @@ inline alpm_list_t SYMEXPORT *alpm_list_next(const alpm_list_t *node)
} }
} }
/**
* @brief Get the previous element of a list.
*
* @param list the list head
*
* @return the previous element, or NULL when no previous element exist
*/
inline alpm_list_t SYMEXPORT *alpm_list_previous(const alpm_list_t *list) inline alpm_list_t SYMEXPORT *alpm_list_previous(const alpm_list_t *list)
{ {
if(list && list->prev->next) { if(list && list->prev->next) {
@ -629,13 +455,6 @@ inline alpm_list_t SYMEXPORT *alpm_list_previous(const alpm_list_t *list)
} }
} }
/**
* @brief Get the last item in the list.
*
* @param list the list
*
* @return the last element in the list
*/
alpm_list_t SYMEXPORT *alpm_list_last(const alpm_list_t *list) alpm_list_t SYMEXPORT *alpm_list_last(const alpm_list_t *list)
{ {
if(list) { if(list) {
@ -647,13 +466,6 @@ alpm_list_t SYMEXPORT *alpm_list_last(const alpm_list_t *list)
/* Misc */ /* Misc */
/**
* @brief Get the number of items in a list.
*
* @param list the list
*
* @return the number of list items
*/
size_t SYMEXPORT alpm_list_count(const alpm_list_t *list) size_t SYMEXPORT alpm_list_count(const alpm_list_t *list)
{ {
size_t i = 0; size_t i = 0;
@ -665,15 +477,6 @@ size_t SYMEXPORT alpm_list_count(const alpm_list_t *list)
return i; return i;
} }
/**
* @brief Find an item in a list.
*
* @param needle the item to search
* @param haystack the list
* @param fn the comparison function for searching (!= NULL)
*
* @return `needle` if found, NULL otherwise
*/
void SYMEXPORT *alpm_list_find(const alpm_list_t *haystack, const void *needle, void SYMEXPORT *alpm_list_find(const alpm_list_t *haystack, const void *needle,
alpm_list_fn_cmp fn) alpm_list_fn_cmp fn)
{ {
@ -693,30 +496,12 @@ static int ptr_cmp(const void *p, const void *q)
return (p != q); return (p != q);
} }
/**
* @brief Find an item in a list.
*
* Search for the item whose data matches that of the `needle`.
*
* @param needle the data to search for (== comparison)
* @param haystack the list
*
* @return `needle` if found, NULL otherwise
*/
void SYMEXPORT *alpm_list_find_ptr(const alpm_list_t *haystack, void SYMEXPORT *alpm_list_find_ptr(const alpm_list_t *haystack,
const void *needle) const void *needle)
{ {
return alpm_list_find(haystack, needle, ptr_cmp); return alpm_list_find(haystack, needle, ptr_cmp);
} }
/**
* @brief Find a string in a list.
*
* @param needle the string to search for
* @param haystack the list
*
* @return `needle` if found, NULL otherwise
*/
char SYMEXPORT *alpm_list_find_str(const alpm_list_t *haystack, char SYMEXPORT *alpm_list_find_str(const alpm_list_t *haystack,
const char *needle) const char *needle)
{ {
@ -724,20 +509,6 @@ char SYMEXPORT *alpm_list_find_str(const alpm_list_t *haystack,
(alpm_list_fn_cmp)strcmp); (alpm_list_fn_cmp)strcmp);
} }
/**
* @brief Find the differences between list `left` and list `right`
*
* The two lists must be sorted. Items only in list `left` are added to the
* `onlyleft` list. Items only in list `right` are added to the `onlyright`
* list.
*
* @param left the first list
* @param right the second list
* @param fn the comparison function
* @param onlyleft pointer to the first result list
* @param onlyright pointer to the second result list
*
*/
void SYMEXPORT alpm_list_diff_sorted(const alpm_list_t *left, void SYMEXPORT alpm_list_diff_sorted(const alpm_list_t *left,
const alpm_list_t *right, alpm_list_fn_cmp fn, const alpm_list_t *right, alpm_list_fn_cmp fn,
alpm_list_t **onlyleft, alpm_list_t **onlyright) alpm_list_t **onlyleft, alpm_list_t **onlyright)
@ -782,15 +553,6 @@ void SYMEXPORT alpm_list_diff_sorted(const alpm_list_t *left,
} }
/**
* @brief Find the items in list `lhs` that are not present in list `rhs`.
*
* @param lhs the first list
* @param rhs the second list
* @param fn the comparison function
*
* @return a list containing all items in `lhs` not present in `rhs`
*/
alpm_list_t SYMEXPORT *alpm_list_diff(const alpm_list_t *lhs, alpm_list_t SYMEXPORT *alpm_list_diff(const alpm_list_t *lhs,
const alpm_list_t *rhs, alpm_list_fn_cmp fn) const alpm_list_t *rhs, alpm_list_fn_cmp fn)
{ {
@ -809,17 +571,6 @@ alpm_list_t SYMEXPORT *alpm_list_diff(const alpm_list_t *lhs,
return ret; return ret;
} }
/**
* @brief Copy a list and data into a standard C array of fixed length.
* Note that the data elements are shallow copied so any contained pointers
* will point to the original data.
*
* @param list the list to copy
* @param n the size of the list
* @param size the size of each data element
*
* @return an array version of the original list, data copied as well
*/
void SYMEXPORT *alpm_list_to_array(const alpm_list_t *list, size_t n, void SYMEXPORT *alpm_list_to_array(const alpm_list_t *list, size_t n,
size_t size) size_t size)
{ {
@ -840,5 +591,3 @@ void SYMEXPORT *alpm_list_to_array(const alpm_list_t *list, size_t n,
} }
return array; return array;
} }
/** @} */

View file

@ -17,6 +17,14 @@
* You should have received a copy of the GNU General Public License * You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>. * along with this program. If not, see <http://www.gnu.org/licenses/>.
*/ */
/**
* @file alpm_list.h
* @author Pacman Development Team
* @brief A doubly linked list for use with libalpm
*/
#ifndef ALPM_LIST_H #ifndef ALPM_LIST_H
#define ALPM_LIST_H #define ALPM_LIST_H
@ -31,12 +39,20 @@ extern "C" {
#endif #endif
/** /**
* @brief Linked list type used by libalpm. * @addtogroup alpm_list List Functions
* @brief Functions to manipulate alpm_list_t lists.
*
* These functions are designed to create, destroy, and modify lists of
* type alpm_list_t. This is an internal list type used by libalpm that is
* publicly exposed for use by frontends if desired.
* *
* It is exposed so front ends can use it to prevent the need to reimplement * It is exposed so front ends can use it to prevent the need to reimplement
* lists of their own; however, it is not required that the front end uses * lists of their own; however, it is not required that the front end uses
* it. * it.
* @{
*/ */
/** A doubly linked list */
typedef struct __alpm_list_t { typedef struct __alpm_list_t {
/** data held by the list node */ /** data held by the list node */
void *data; void *data;
@ -46,48 +62,322 @@ typedef struct __alpm_list_t {
struct __alpm_list_t *next; struct __alpm_list_t *next;
} alpm_list_t; } alpm_list_t;
/** Frees a list and its contents */
#define FREELIST(p) do { alpm_list_free_inner(p, free); alpm_list_free(p); p = NULL; } while(0) #define FREELIST(p) do { alpm_list_free_inner(p, free); alpm_list_free(p); p = NULL; } while(0)
typedef void (*alpm_list_fn_free)(void *); /* item deallocation callback */ /** item deallocation callback.
typedef int (*alpm_list_fn_cmp)(const void *, const void *); /* item comparison callback */ * @param the item to free
*/
typedef void (*alpm_list_fn_free)(void * item);
/** item comparison callback */
typedef int (*alpm_list_fn_cmp)(const void *, const void *);
/* allocation */ /* allocation */
/** Free a list, but not the contained data.
*
* @param list the list to free
*/
void alpm_list_free(alpm_list_t *list); void alpm_list_free(alpm_list_t *list);
/** Free the internal data of a list structure but not the list itself.
*
* @param list the list to free
* @param fn a free function for the internal data
*/
void alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn); void alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn);
/* item mutators */ /* item mutators */
/** Add a new item to the end of the list.
*
* @param list the list to add to
* @param data the new item to be added to the list
*
* @return the resultant list
*/
alpm_list_t *alpm_list_add(alpm_list_t *list, void *data); alpm_list_t *alpm_list_add(alpm_list_t *list, void *data);
/**
* @brief Add a new item to the end of the list.
*
* @param list the list to add to
* @param data the new item to be added to the list
*
* @return the newly added item
*/
alpm_list_t *alpm_list_append(alpm_list_t **list, void *data); alpm_list_t *alpm_list_append(alpm_list_t **list, void *data);
/**
* @brief Duplicate and append a string to a list.
*
* @param list the list to append to
* @param data the string to duplicate and append
*
* @return the newly added item
*/
alpm_list_t *alpm_list_append_strdup(alpm_list_t **list, const char *data); alpm_list_t *alpm_list_append_strdup(alpm_list_t **list, const char *data);
/**
* @brief Add items to a list in sorted order.
*
* @param list the list to add to
* @param data the new item to be added to the list
* @param fn the comparison function to use to determine order
*
* @return the resultant list
*/
alpm_list_t *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cmp fn); alpm_list_t *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cmp fn);
/**
* @brief Join two lists.
* The two lists must be independent. Do not free the original lists after
* calling this function, as this is not a copy operation. The list pointers
* passed in should be considered invalid after calling this function.
*
* @param first the first list
* @param second the second list
*
* @return the resultant joined list
*/
alpm_list_t *alpm_list_join(alpm_list_t *first, alpm_list_t *second); alpm_list_t *alpm_list_join(alpm_list_t *first, alpm_list_t *second);
/**
* @brief Merge the two sorted sublists into one sorted list.
*
* @param left the first list
* @param right the second list
* @param fn comparison function for determining merge order
*
* @return the resultant list
*/
alpm_list_t *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right, alpm_list_fn_cmp fn); alpm_list_t *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right, alpm_list_fn_cmp fn);
/**
* @brief Sort a list of size `n` using mergesort algorithm.
*
* @param list the list to sort
* @param n the size of the list
* @param fn the comparison function for determining order
*
* @return the resultant list
*/
alpm_list_t *alpm_list_msort(alpm_list_t *list, size_t n, alpm_list_fn_cmp fn); alpm_list_t *alpm_list_msort(alpm_list_t *list, size_t n, alpm_list_fn_cmp fn);
/**
* @brief Remove an item from the list.
* item is not freed; this is the responsibility of the caller.
*
* @param haystack the list to remove the item from
* @param item the item to remove from the list
*
* @return the resultant list
*/
alpm_list_t *alpm_list_remove_item(alpm_list_t *haystack, alpm_list_t *item); alpm_list_t *alpm_list_remove_item(alpm_list_t *haystack, alpm_list_t *item);
/**
* @brief Remove an item from the list.
*
* @param haystack the list to remove the item from
* @param needle the data member of the item we're removing
* @param fn the comparison function for searching
* @param data output parameter containing data of the removed item
*
* @return the resultant list
*/
alpm_list_t *alpm_list_remove(alpm_list_t *haystack, const void *needle, alpm_list_fn_cmp fn, void **data); alpm_list_t *alpm_list_remove(alpm_list_t *haystack, const void *needle, alpm_list_fn_cmp fn, void **data);
/**
* @brief Remove a string from a list.
*
* @param haystack the list to remove the item from
* @param needle the data member of the item we're removing
* @param data output parameter containing data of the removed item
*
* @return the resultant list
*/
alpm_list_t *alpm_list_remove_str(alpm_list_t *haystack, const char *needle, char **data); alpm_list_t *alpm_list_remove_str(alpm_list_t *haystack, const char *needle, char **data);
/**
* @brief Create a new list without any duplicates.
*
* This does NOT copy data members.
*
* @param list the list to copy
*
* @return a new list containing non-duplicate items
*/
alpm_list_t *alpm_list_remove_dupes(const alpm_list_t *list); alpm_list_t *alpm_list_remove_dupes(const alpm_list_t *list);
/**
* @brief Copy a string list, including data.
*
* @param list the list to copy
*
* @return a copy of the original list
*/
alpm_list_t *alpm_list_strdup(const alpm_list_t *list); alpm_list_t *alpm_list_strdup(const alpm_list_t *list);
/**
* @brief Copy a list, without copying data.
*
* @param list the list to copy
*
* @return a copy of the original list
*/
alpm_list_t *alpm_list_copy(const alpm_list_t *list); alpm_list_t *alpm_list_copy(const alpm_list_t *list);
/**
* @brief Copy a list and copy the data.
* Note that the data elements to be copied should not contain pointers
* and should also be of constant size.
*
* @param list the list to copy
* @param size the size of each data element
*
* @return a copy of the original list, data copied as well
*/
alpm_list_t *alpm_list_copy_data(const alpm_list_t *list, size_t size); alpm_list_t *alpm_list_copy_data(const alpm_list_t *list, size_t size);
/**
* @brief Create a new list in reverse order.
*
* @param list the list to copy
*
* @return a new list in reverse order
*/
alpm_list_t *alpm_list_reverse(alpm_list_t *list); alpm_list_t *alpm_list_reverse(alpm_list_t *list);
/* item accessors */ /* item accessors */
/**
* @brief Return nth element from list (starting from 0).
*
* @param list the list
* @param n the index of the item to find (n < alpm_list_count(list) IS needed)
*
* @return an alpm_list_t node for index `n`
*/
alpm_list_t *alpm_list_nth(const alpm_list_t *list, size_t n); alpm_list_t *alpm_list_nth(const alpm_list_t *list, size_t n);
/**
* @brief Get the next element of a list.
*
* @param list the list node
*
* @return the next element, or NULL when no more elements exist
*/
alpm_list_t *alpm_list_next(const alpm_list_t *list); alpm_list_t *alpm_list_next(const alpm_list_t *list);
/**
* @brief Get the previous element of a list.
*
* @param list the list head
*
* @return the previous element, or NULL when no previous element exist
*/
alpm_list_t *alpm_list_previous(const alpm_list_t *list); alpm_list_t *alpm_list_previous(const alpm_list_t *list);
/**
* @brief Get the last item in the list.
*
* @param list the list
*
* @return the last element in the list
*/
alpm_list_t *alpm_list_last(const alpm_list_t *list); alpm_list_t *alpm_list_last(const alpm_list_t *list);
/* misc */ /* misc */
/**
* @brief Get the number of items in a list.
*
* @param list the list
*
* @return the number of list items
*/
size_t alpm_list_count(const alpm_list_t *list); size_t alpm_list_count(const alpm_list_t *list);
/**
* @brief Find an item in a list.
*
* @param needle the item to search
* @param haystack the list
* @param fn the comparison function for searching (!= NULL)
*
* @return `needle` if found, NULL otherwise
*/
void *alpm_list_find(const alpm_list_t *haystack, const void *needle, alpm_list_fn_cmp fn); void *alpm_list_find(const alpm_list_t *haystack, const void *needle, alpm_list_fn_cmp fn);
/**
* @brief Find an item in a list.
*
* Search for the item whose data matches that of the `needle`.
*
* @param needle the data to search for (== comparison)
* @param haystack the list
*
* @return `needle` if found, NULL otherwise
*/
void *alpm_list_find_ptr(const alpm_list_t *haystack, const void *needle); void *alpm_list_find_ptr(const alpm_list_t *haystack, const void *needle);
/**
* @brief Find a string in a list.
*
* @param needle the string to search for
* @param haystack the list
*
* @return `needle` if found, NULL otherwise
*/
char *alpm_list_find_str(const alpm_list_t *haystack, const char *needle); char *alpm_list_find_str(const alpm_list_t *haystack, const char *needle);
alpm_list_t *alpm_list_diff(const alpm_list_t *lhs, const alpm_list_t *rhs, alpm_list_fn_cmp fn);
/**
* @brief Find the differences between list `left` and list `right`
*
* The two lists must be sorted. Items only in list `left` are added to the
* `onlyleft` list. Items only in list `right` are added to the `onlyright`
* list.
*
* @param left the first list
* @param right the second list
* @param fn the comparison function
* @param onlyleft pointer to the first result list
* @param onlyright pointer to the second result list
*
*/
void alpm_list_diff_sorted(const alpm_list_t *left, const alpm_list_t *right, void alpm_list_diff_sorted(const alpm_list_t *left, const alpm_list_t *right,
alpm_list_fn_cmp fn, alpm_list_t **onlyleft, alpm_list_t **onlyright); alpm_list_fn_cmp fn, alpm_list_t **onlyleft, alpm_list_t **onlyright);
/**
* @brief Find the items in list `lhs` that are not present in list `rhs`.
*
* @param lhs the first list
* @param rhs the second list
* @param fn the comparison function
*
* @return a list containing all items in `lhs` not present in `rhs`
*/
alpm_list_t *alpm_list_diff(const alpm_list_t *lhs, const alpm_list_t *rhs, alpm_list_fn_cmp fn);
/**
* @brief Copy a list and data into a standard C array of fixed length.
* Note that the data elements are shallow copied so any contained pointers
* will point to the original data.
*
* @param list the list to copy
* @param n the size of the list
* @param size the size of each data element
*
* @return an array version of the original list, data copied as well
*/
void *alpm_list_to_array(const alpm_list_t *list, size_t n, size_t size); void *alpm_list_to_array(const alpm_list_t *list, size_t n, size_t size);
/* End of alpm_list */
/** @} */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif