Ubuntu Manpage: lyst - library for manipulating generalized doubly linked lists

NAME

       lyst - library for manipulating generalized doubly linked lists

SYNOPSIS

           #include "lyst.h"

           typedef int  (*LystCompareFn)(void *s1, void *s2);
           typedef void (*LystCallback)(LystElt elt, void *userdata);

           [see description for available functions]

DESCRIPTION

       The "lyst" library uses two types of objects, Lyst objects and LystElt objects.  A Lyst knows how many
       elements it contains, its first and last elements, the memory manager used to create/destroy the Lyst and
       its elements, and how the elements are sorted.  A LystElt knows its content (normally a pointer to an
       item in memory), what Lyst it belongs to, and the LystElts before and after it in that Lyst.

       Lyst lyst_create(void)
           Create  and  return  a  new Lyst object without any elements in it.  All operations performed on this
           Lyst will use the  allocation/deallocation  functions  of  the  default  memory  manager  "std"  (see
           memmgr(3)).  Returns NULL on any failure.

       Lyst lyst_create_using(unsigned memmgrId)
           Create  and  return  a  new Lyst object without any elements in it.  All operations performed on this
           Lyst will use the allocation/deallocation functions of the specified memory manager (see  memmgr(3)).
           Returns NULL on any failure.

       void lyst_clear(Lyst list)
           Clear  a  Lyst,  i.e. free all elements of list, calling the Lyst's deletion function if defined, but
           without destroying the Lyst itself.

       void lyst_destroy(Lyst list)
           Destroy a Lyst.  Will free all elements of list, calling the Lyst's deletion function if defined.

       void lyst_compare_set(Lyst list, LystCompareFn compareFn)
       LystCompareFn lyst_compare_get(Lyst list)
           Set/get comparison function for specified Lyst.   Comparison  functions  are  called  with  two  Lyst
           element data pointers, and must return a negative integer if first is less than second, 0 if both are
           equal,  and  a  positive  integer  if  first  is  greater  than  second  (i.e., same return values as
           strcmp(3)).  The comparison function is used by the lyst_insert(),  lyst_search(),  lyst_sort(),  and
           lyst_sorted() functions.

       void lyst_direction_set(Lyst list, LystSortDirection direction)
           Set  sort  direction  (either LIST_SORT_ASCENDING or LIST_SORT_DESCENDING) for specified Lyst.  If no
           comparison function is set, then this controls whether new elements are added to the end or beginning
           (respectively) of the Lyst when lyst_insert() is called.

       void lyst_delete_set(Lyst list, LystCallback deleteFn, void *userdata)
           Set user deletion function for specified Lyst.  This function is  automatically  called  whenever  an
           element  of the Lyst is deleted, to perform any user-required processing.  When automatically called,
           the deletion function is passed two arguments: the element being deleted  and  the  userdata  pointer
           specified in the lyst_delete_set() call.

       void lyst_insert_set(Lyst list, LystCallback insertFn, void *userdata)
           Set  user  insertion  function  for specified Lyst.  This function is automatically called whenever a
           Lyst element is inserted into the Lyst, to perform any user-required processing.  When  automatically
           called,  the  insertion function is passed two arguments: the element being inserted and the userdata
           pointer specified in the lyst_insert_set() call.

       unsigned long lyst_length(Lyst list)
           Return the number of elements in the Lyst.

       LystElt lyst_insert(Lyst list, void *data)
           Create a new element whose content is the pointer value data and insert it into the Lyst.   Uses  the
           Lyst's  comparison  function to select insertion point, if defined; otherwise adds the new element at
           the beginning or end of the Lyst, depending on the Lyst sort direction setting.  Returns a pointer to
           the newly created element, or NULL on any failure.

       LystElt lyst_insert_first(Lyst list, void *data)
       LystElt lyst_insert_last(Lyst list, void *data)
           Create a new element and insert it at the beginning/end of the Lyst.  If  these  functions  are  used
           when  inserting elements into a Lyst with a defined comparison function, then the Lyst may get out of
           order and future calls to lyst_insert() can put new elements in unpredictable locations.   Returns  a
           pointer to the newly created element, or NULL on any failure.

       LystElt lyst_insert_before(LystElt element, void *data)
       LystElt lyst_insert_after(LystElt element, void *data)
           Create  a  new element and insert it before/after the specified element.  If these functions are used
           when inserting elements into a Lyst with a defined comparison function, then the Lyst may get out  of
           order  and  future  calls  to lyst_insert can put new elements in unpredictable locations.  Returns a
           pointer to the newly created element, or NULL on any failure.

       void lyst_delete(LystElt element)
           Delete the specified element from its Lyst and deallocate its memory.  Calls the user delete function
           if defined.

       LystElt lyst_first(Lyst list)
       LystElt lyst_last(Lyst list)
           Return a pointer to the first/last element of a Lyst.

       LystElt lyst_next(LystElt element)
       LystElt lyst_prev(LystElt element)
           Return a pointer to the element following/preceding the specified element.

       LystElt lyst_search(LystElt element, void *searchValue)
           Find the first matching element in a Lyst starting with the specified element.  Returns  NULL  if  no
           matches are found.  Uses the Lyst's comparison function if defined, otherwise searches from the given
           element to the end of the Lyst.

       Lyst lyst_lyst(LystElt element)
           Return the Lyst to which the specified element belongs.

       void* lyst_data(LystElt element)
       void* lyst_data_set(LystElt element, void *data)
           Get/set  the  pointer  value  content  of  the  specified  Lyst element.  The set routine returns the
           element's previous content, and the delete function is not called.  If the  lyst_data_set()  function
           is  used  on  an  element  of a Lyst with a defined comparison function, then the Lyst may get out of
           order and future calls to lyst_insert() can put new elements in unpredictable locations.

       void lyst_sort(Lyst list)
           Sort the Lyst based on the current comparison function and sort direction.  A stable  insertion  sort
           is used that is very fast when the elements are already in order.

       int lyst_sorted(Lyst list)
           Determine  whether  or  not  the  Lyst  is  sorted  based on the current comparison function and sort
           direction.

       void lyst_apply(Lyst list, LystCallback applyFn, void *userdata)
           Apply the function applyFn automatically to each element in the  Lyst.   When  automatically  called,
           applyFn  is passed two arguments: a pointer to an element, and the userdata argument specified in the
           call to lyst_apply().  applyFn should not delete or reorder the elements in the Lyst.

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO