gi_list.h File Reference

Doubly-linked list interface with several minor extensions. More...

Go to the source code of this file.

Classes
struct	gi_list_link
struct	gi_list
Defines
#define	GI_LIST_LINK(gilist)   ((gilist)->bol)
#define	GI_LIST_CMP(cmpfn)   ((GiListCompareFn)(cmpfn))
#define	GI_LIST_FOREACH(foreachfn)   ((GiListForeachFn)(foreachfn))
#define	GI_LIST_FOREACH_EX(foreachfn)   ((GiListForeachExFn)(foreachfn))
#define	gi_listl_nth_data(link, n)   gi_listl_data(gi_listl_nth(link,n))
#define	gi_list_nth_data(list, n)   gi_listl_data(gi_list_nth(list,n))
Typedefs
typedef gi_list_link	GiListLink
typedef gi_list	GiList
typedef int(*	GiListCompareFn )(const void *a, const void *b)
typedef void(*	GiListForeachFn )(const void *data, const void *udata)
typedef int(*	GiListForeachExFn )(const void *data, const void *udata)
Functions
EXTERN_C_BEGIN LIBGIFT_EXPORT GiList *	gi_list_new (void)
LIBGIFT_EXPORT void	gi_list_destroy (GiList **listref)
LIBGIFT_EXPORT GiListLink *	gi_list_append (GiList **listref, const void *data)
LIBGIFT_EXPORT GiListLink *	gi_list_prepend (GiList **listref, const void *data)
LIBGIFT_EXPORT GiListLink *	gi_list_insert (GiList **listref, GiListLink *pos, const void *data)
LIBGIFT_EXPORT GiListLink *	gi_list_insort (GiList **listref, GiListCompareFn cmpfn, const void *data)
LIBGIFT_EXPORT bool	gi_list_remove (GiList **listref, const void *data)
LIBGIFT_EXPORT void	gi_list_removel (GiList **listref, GiListLink *link)
LIBGIFT_EXPORT unsigned int	gi_list_length (GiList *list)
LIBGIFT_EXPORT GiListLink *	gi_listl_nth (GiListLink *link, int n)
LIBGIFT_EXPORT GiListLink *	gi_list_nth (GiList *list, int n)
LIBGIFT_EXPORT void *	gi_listl_data (GiListLink *link)
LIBGIFT_EXPORT GiListLink *	gi_list_find (GiList *list, GiListCompareFn cmpfn, const void *udata)
LIBGIFT_EXPORT void	gi_list_foreach (GiList *list, GiListForeachFn foreachfn, const void *udata)
LIBGIFT_EXPORT void	gi_list_foreachex (GiList **listref, GiListForeachExFn foreachfn, const void *udata)
LIBGIFT_EXPORT void	gi_list_sort (GiList **listref, GiListCompareFn cmpfn)

---

Detailed Description

Doubly-linked list interface with several minor extensions.

This interface provides extended features such as the ability to efficiently count the number of elements in the list, matched performance for prepend and append, and operations specific to link chains.

---

Define Documentation

#define GI_LIST_LINK (  gilist   )     ((gilist)->bol)

Access the beginning list link given a GiList*.

---

Typedef Documentation

typedef struct gi_list GiList

Main list container. This object makes it possible to optimized several commonly expensive linked list operations that are used widely throughout giFT.

typedef int(* GiListCompareFn)(const void *a, const void *b)

Compare two link data elements, using similar semantics to strcmp/memcmp. Parameters: a  b  Returns: An integer less than, equal to, or greater than zero if `a' is found to be less than, equal to, or greater than `b', respectively.

typedef void(* GiListForeachFn)(const void *data, const void *udata)

Iterator function. Called once for each link chain traversed from gi_list_foreach. Parameters: data  Link chain's user data. udata  Iterator user data.

typedef struct gi_list_link GiListLink

Individual link chain that makes up the doubly linked list.

---

Function Documentation

LIBGIFT_EXPORT GiListLink* gi_list_append (  GiList **  listref, const void *  data )

Append a new list link to the end of the list described by `listref'. Parameters: listref  Address of the GiList* which acts as the head of the list. If the current list head is NULL, an empty list will be constructed and stored at this parameter's value. data  Arbitrary user data to associated with the new link chain. Returns: On success, a pointer to the newly created link chain; on error NULL is returned and the size of the list will be unaffected.

LIBGIFT_EXPORT void gi_list_destroy (  GiList **  listref  )

Destroy the list described by `listref' and all associated link chains. The storage pointed to by `listref' will be set to NULL upon successful destruction.

LIBGIFT_EXPORT GiListLink* gi_list_find (  GiList *  list, GiListCompareFn  cmpfn, const void *  udata )

Search for a link chain according to `cmpfn'. The list will not be presumed sorted, and so iteration will continue until `cmpfn' results in 0. Returns: On success, the link pointer found will be returned; otherwise, NULL.

LIBGIFT_EXPORT void gi_list_foreach (  GiList *  list, GiListForeachFn  foreachfn, const void *  udata )

Iterate through each link chain at the beginning of `list'. For each link chain encountered, `foreachfn' will be called with the chain's user data as well as the `udata' parameter to this function.

LIBGIFT_EXPORT void gi_list_foreachex (  GiList **  listref, GiListForeachExFn  foreachfn, const void *  udata )

Extended iterator. See ::gi_dataset_foreachex.

LIBGIFT_EXPORT GiListLink* gi_list_insert (  GiList **  listref, GiListLink *  pos, const void *  data )

Insert a new list link immediately before the link described by `pos'. The behaviour is undefined if `pos' does not currently exist as a member of the list described by `listref'. Parameters: listref  List semantics as documented in gi_list_append. pos  Specifies the position which follows where the new link should be inserted. If the head of the list is used, the behaviour is identical to gi_list_prepend; if NULL, the behaviour is identical to gi_list_append. udata  Arbitrary user data.

LIBGIFT_EXPORT GiListLink* gi_list_insort (  GiList **  listref, GiListCompareFn  cmpfn, const void *  data )

Insert a new list link in sorted order according to `cmpfn'. Parameters: listref  List semantics as documented in gi_list_append. cmpfn  Comparison function which determines sorted order. The new list link will be inserted at the first position (beginning from GiList::bol) which compares less than or equal to the data to be inserted. data  Arbitrary user data to be inserted. Will also be passed to the comparison function for convenience.

LIBGIFT_EXPORT unsigned int gi_list_length (  GiList *  list  )

Access the number of link chains that currently exist in the list described by `list'. This operation does not require iteration.

EXTERN_C_BEGIN LIBGIFT_EXPORT GiList* gi_list_new (  void   )

Construct an empty list object.

LIBGIFT_EXPORT GiListLink* gi_list_nth (  GiList *  list, int  n )

Similar to gi_listl_nth, but will more efficiently apply bounds checking. Negative values for `n' are not allowed with this interface as iteration always begins from the start of the list.

LIBGIFT_EXPORT GiListLink* gi_list_prepend (  GiList **  listref, const void *  data )

Prepend a new list link using identical semantics as gi_list_append.

LIBGIFT_EXPORT bool gi_list_remove (  GiList **  listref, const void *  data )

Search for the supplied data using gi_list_find, and remove the resulting GiListLink. Returns: If the data element was not located in the list, false is returned; otherwise, true.

LIBGIFT_EXPORT void gi_list_removel (  GiList **  listref, GiListLink *  link )

Remove the list link described by `link'. No iteration or searching will be required to perform this operation. The link will be destroyed and future usage of the handle is undefined.

LIBGIFT_EXPORT void gi_list_sort (  GiList **  listref, GiListCompareFn  cmpfn )

Sort the list in-place according to `cmpfn'.

LIBGIFT_EXPORT void* gi_listl_data (  GiListLink *  link  )

Access the user data element associated with `link'.

LIBGIFT_EXPORT GiListLink* gi_listl_nth (  GiListLink *  link, int  n )

Access the nth link in the chain beginning from `link'. This operation will iterate up to `n' times. Parameters: link  Begin search from this position. n  Specifies direction and distance to travel from `link'. If negative, the traversal runs backwards. Specifying distances that exceed the current boundaries for the list are safe, but will not produce a link result. Returns: If found, the link chain is returned; otherwise, NULL.

---