1 /*****************************************************************************
2 * xlist.h : a simple doubly linked list in C (header file)
3 *****************************************************************************
4 * Copyright (C) 2003-2004 Commonwealth Scientific and Industrial Research
5 * Organisation (CSIRO) Australia
6 * Copyright (C) 2000-2004 the VideoLAN team
10 * Authors: Conrad Parker <Conrad.Parker@csiro.au>
11 * Andre Pang <Andre.Pang@csiro.au>
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, write to the Free Software
25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
26 *****************************************************************************/
33 * A doubly linked list
35 typedef struct _XList XList;
44 * Signature of a cloning function.
46 typedef void * (*XCloneFunc) (void * data);
49 * Signature of a freeing function.
51 typedef void * (*XFreeFunc) (void * data);
56 XList * xlist_new (void);
59 * Clone a list using the default clone function
60 * \param list the list to clone
61 * \returns a newly cloned list
63 XList * xlist_clone (XList * list);
66 * Clone a list using a custom clone function
67 * \param list the list to clone
68 * \param clone the function to use to clone a list item
69 * \returns a newly cloned list
71 XList * xlist_clone_with (XList * list, XCloneFunc clone);
74 * Return the tail element of a list
75 * \param list the list
76 * \returns the tail element
78 XList * xlist_tail (XList * list);
81 * Prepend a new node to a list containing given data
82 * \param list the list
83 * \param data the data element of the newly created node
84 * \returns the new list head
86 XList * xlist_prepend (XList * list, void * data);
89 * Append a new node to a list containing given data
90 * \param list the list
91 * \param data the data element of the newly created node
92 * \returns the head of the list
94 XList * xlist_append (XList * list, void * data);
97 * Add a new node containing given data before a given node
98 * \param list the list
99 * \param data the data element of the newly created node
100 * \param node the node before which to add the newly created node
101 * \returns the head of the list (which may have changed)
103 XList * xlist_add_before (XList * list, void * data, XList * node);
106 * Add a new node containing given data after a given node
107 * \param list the list
108 * \param data the data element of the newly created node
109 * \param node the node after which to add the newly created node
110 * \returns the head of the list
112 XList * xlist_add_after (XList * list, void * data, XList * node);
115 * Find the first node containing given data in a list
116 * \param list the list
117 * \param data the data element to find
118 * \returns the first node containing given data, or NULL if it is not found
120 XList * xlist_find (XList * list, void * data);
123 * Remove a node from a list
124 * \param list the list
125 * \param node the node to remove
126 * \returns the head of the list (which may have changed)
128 XList * xlist_remove (XList * list, XList * node);
131 * Query the number of items in a list
132 * \param list the list
133 * \returns the number of nodes in the list
135 int xlist_length (XList * list);
138 * Query if a list is empty, ie. contains no items
139 * \param list the list
140 * \returns 1 if the list is empty, 0 otherwise
142 int xlist_is_empty (XList * list);
145 * Query if the list is singleton, ie. contains exactly one item
146 * \param list the list
147 * \returns 1 if the list is singleton, 0 otherwise
149 int xlist_is_singleton (XList * list);
152 * Free a list, using a given function to free each data element
153 * \param list the list
154 * \param free_func a function to free each data element
155 * \returns NULL on success
157 XList * xlist_free_with (XList * list, XFreeFunc free_func);
160 * Free a list, using anx_free() to free each data element
161 * \param list the list
162 * \returns NULL on success
164 XList * xlist_free (XList * list);
166 #endif /* __XLIST__ */