list: lists interfaces

## list

list - lists interfaces

this module implement the list support used in various place in the library.

Author(s): Gary Pennington <Gary.Pennington@uk.sun.com>

## Synopsis

    typedef struct _xmlLink xmlLink;
    typedef xmlLink * xmlLinkPtr;
    typedef struct _xmlList xmlList;
    typedef xmlList * xmlListPtr;
    int	xmlListInsert			(xmlListPtr l,
    					 void * data);
    int	xmlListEmpty			(xmlListPtr l);
    void	xmlListSort			(xmlListPtr l);
    typedef void xmlListDeallocator		(xmlLinkPtr lk);
    void	xmlListMerge			(xmlListPtr l1,
    					 xmlListPtr l2);
    xmlListPtr	xmlListCreate		(xmlListDeallocator deallocator,
    					 xmlListDataCompare compare);
    xmlListPtr	xmlListDup		(const xmlListPtr old);
    int	xmlListRemoveLast		(xmlListPtr l,
    					 void * data);
    void	xmlListWalk			(xmlListPtr l,
    					 xmlListWalker walker,
    					 const void * user);
    int	xmlListRemoveAll		(xmlListPtr l,
    					 void * data);
    int	xmlListCopy			(xmlListPtr cur,
    					 const xmlListPtr old);
    void	xmlListPopFront			(xmlListPtr l);
    void *	xmlListSearch			(xmlListPtr l,
    					 void * data);
    typedef int xmlListWalker			(const void * data,
    					 const void * user);
    int	xmlListRemoveFirst		(xmlListPtr l,
    					 void * data);
    void	xmlListReverseWalk		(xmlListPtr l,
    					 xmlListWalker walker,
    					 const void * user);
    void *	xmlLinkGetData			(xmlLinkPtr lk);
    void	xmlListClear			(xmlListPtr l);
    int	xmlListAppend			(xmlListPtr l,
    					 void * data);
    void	xmlListReverse			(xmlListPtr l);
    typedef int xmlListDataCompare		(const void * data0,
    					 const void * data1);
    int	xmlListSize			(xmlListPtr l);
    int	xmlListPushFront		(xmlListPtr l,
    					 void * data);
    xmlLinkPtr	xmlListEnd		(xmlListPtr l);
    void	xmlListPopBack			(xmlListPtr l);
    void *	xmlListReverseSearch		(xmlListPtr l,
    					 void * data);
    int	xmlListPushBack			(xmlListPtr l,
    					 void * data);
    xmlLinkPtr	xmlListFront		(xmlListPtr l);
    void	xmlListDelete			(xmlListPtr l);

## Description

## Details

### Structure xmlLink

    struct _xmlLink {
    The content of this structure is not made public by the API.
    } xmlLink;

### Typedef xmlLinkPtr

    xmlLink * xmlLinkPtr;

### Structure xmlList

    struct _xmlList {
    The content of this structure is not made public by the API.
    } xmlList;

### Typedef xmlListPtr

    xmlList * xmlListPtr;

### Function type xmlListDataCompare

    int	xmlListDataCompare		(const void * data0,
    					 const void * data1)

Callback function used to compare 2 data.

`data0`: | the first data
`data1`: | the second data
`Returns`: | 0 is equality, -1 or 1 otherwise depending on the ordering.

### Function type xmlListDeallocator

    void	xmlListDeallocator		(xmlLinkPtr lk)

Callback function used to free data from a list.

`lk`: | the data to deallocate

### Function type xmlListWalker

    int	xmlListWalker			(const void * data,
    					 const void * user)

Callback function used when walking a list with xmlListWalk().

`data`: | the data found in the list
`user`: | extra user provided data to the walker
`Returns`: | 0 to stop walking the list, 1 otherwise.

### xmlLinkGetData ()

    void *	xmlLinkGetData			(xmlLinkPtr lk)

See Returns.

`lk`: | a link
`Returns`: | a pointer to the data referenced from this link

### xmlListAppend ()

    int	xmlListAppend			(xmlListPtr l,
    					 void * data)

Insert data in the ordered list at the end for this value

`l`: | a list
`data`: | the data
`Returns`: | 0 in case of success, 1 in case of failure

### xmlListClear ()

    void	xmlListClear			(xmlListPtr l)

Remove the all data in the list

`l`: | a list

### xmlListCopy ()

    int	xmlListCopy			(xmlListPtr cur,
    					 const xmlListPtr old)

Move all the element from the old list in the new list

`cur`: | the new list
`old`: | the old list
`Returns`: | 0 in case of success 1 in case of error

### xmlListCreate ()

    xmlListPtr	xmlListCreate		(xmlListDeallocator deallocator,
    					 xmlListDataCompare compare)

Create a new list

`deallocator`: | an optional deallocator function
`compare`: | an optional comparison function
`Returns`: | the new list or NULL in case of error

### xmlListDelete ()

    void	xmlListDelete			(xmlListPtr l)

Deletes the list and its associated data

`l`: | a list

### xmlListDup ()

    xmlListPtr	xmlListDup		(const xmlListPtr old)

Duplicate the list

`old`: | the list
`Returns`: | a new copy of the list or NULL in case of error

### xmlListEmpty ()

    int	xmlListEmpty			(xmlListPtr l)

Is the list empty ?

`l`: | a list
`Returns`: | 1 if the list is empty, 0 if not empty and -1 in case of error

### xmlListEnd ()

    xmlLinkPtr	xmlListEnd		(xmlListPtr l)

Get the last element in the list

`l`: | a list
`Returns`: | the last element in the list, or NULL

### xmlListFront ()

    xmlLinkPtr	xmlListFront		(xmlListPtr l)

Get the first element in the list

`l`: | a list
`Returns`: | the first element in the list, or NULL

### xmlListInsert ()

    int	xmlListInsert			(xmlListPtr l,
    					 void * data)

Insert data in the ordered list at the beginning for this value

`l`: | a list
`data`: | the data
`Returns`: | 0 in case of success, 1 in case of failure

### xmlListMerge ()

    void	xmlListMerge			(xmlListPtr l1,
    					 xmlListPtr l2)

include all the elements of the second list in the first one and clear the second list

`l1`: | the original list
`l2`: | the new list

### xmlListPopBack ()

    void	xmlListPopBack			(xmlListPtr l)

Removes the last element in the list

`l`: | a list

### xmlListPopFront ()

    void	xmlListPopFront			(xmlListPtr l)

Removes the first element in the list

`l`: | a list

### xmlListPushBack ()

    int	xmlListPushBack			(xmlListPtr l,
    					 void * data)

add the new data at the end of the list

`l`: | a list
`data`: | new data
`Returns`: | 1 if successful, 0 otherwise

### xmlListPushFront ()

    int	xmlListPushFront		(xmlListPtr l,
    					 void * data)

add the new data at the beginning of the list

`l`: | a list
`data`: | new data
`Returns`: | 1 if successful, 0 otherwise

### xmlListRemoveAll ()

    int	xmlListRemoveAll		(xmlListPtr l,
    					 void * data)

Remove the all instance associated to data in the list

`l`: | a list
`data`: | list data
`Returns`: | the number of deallocation, or 0 if not found

### xmlListRemoveFirst ()

    int	xmlListRemoveFirst		(xmlListPtr l,
    					 void * data)

Remove the first instance associated to data in the list

`l`: | a list
`data`: | list data
`Returns`: | 1 if a deallocation occurred, or 0 if not found

### xmlListRemoveLast ()

    int	xmlListRemoveLast		(xmlListPtr l,
    					 void * data)

Remove the last instance associated to data in the list

`l`: | a list
`data`: | list data
`Returns`: | 1 if a deallocation occurred, or 0 if not found

### xmlListReverse ()

    void	xmlListReverse			(xmlListPtr l)

Reverse the order of the elements in the list

`l`: | a list

### xmlListReverseSearch ()

    void *	xmlListReverseSearch		(xmlListPtr l,
    					 void * data)

Search the list in reverse order for an existing value of @data

`l`: | a list
`data`: | a search value
`Returns`: | the value associated to @data or NULL in case of error

### xmlListReverseWalk ()

    void	xmlListReverseWalk		(xmlListPtr l,
    					 xmlListWalker walker,
    					 const void * user)

Walk all the element of the list in reverse order and apply the walker function to it

`l`: | a list
`walker`: | a processing function
`user`: | a user parameter passed to the walker function

### xmlListSearch ()

    void *	xmlListSearch			(xmlListPtr l,
    					 void * data)

Search the list for an existing value of @data

`l`: | a list
`data`: | a search value
`Returns`: | the value associated to @data or NULL in case of error

### xmlListSize ()

    int	xmlListSize			(xmlListPtr l)

Get the number of elements in the list

`l`: | a list
`Returns`: | the number of elements in the list or -1 in case of error

### xmlListSort ()

    void	xmlListSort			(xmlListPtr l)

Sort all the elements in the list

`l`: | a list

### xmlListWalk ()

    void	xmlListWalk			(xmlListPtr l,
    					 xmlListWalker walker,
    					 const void * user)

Walk all the element of the first from first to last and apply the walker function to it

`l`: | a list
`walker`: | a processing function
`user`: | a user parameter passed to the walker function