PageRenderTime 17ms CodeModel.GetById 10ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/src/common/list.h

https://code.google.com/
C++ Header | 283 lines | 32 code | 47 blank | 204 comment | 0 complexity | 8db052d25f104930b45b6298e60bca44 MD5 | raw file
  1/*****************************************************************************
  2 *  $Id$
  3 *****************************************************************************
  4 *  $LSDId: list.h,v 1.14 2002/12/11 19:00:36 dun Exp $
  5 *****************************************************************************
  6 *  Copyright (C) 2001-2002 The Regents of the University of California.
  7 *  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
  8 *  Written by Chris Dunlap <cdunlap@llnl.gov>.
  9 *  
 10 *  This file is from LSD-Tools, the LLNL Software Development Toolbox.
 11 *
 12 *  LSD-Tools is free software; you can redistribute it and/or modify it under
 13 *  the terms of the GNU General Public License as published by the Free
 14 *  Software Foundation; either version 2 of the License, or (at your option)
 15 *  any later version.
 16 *
 17 *  LSD-Tools is distributed in the hope that it will be useful, but WITHOUT
 18 *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 19 *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 20 *  more details.
 21 *
 22 *  You should have received a copy of the GNU General Public License along
 23 *  with LSD-Tools; if not, write to the Free Software Foundation, Inc.,
 24 *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
 25 *****************************************************************************/
 26
 27
 28#ifndef LSD_LIST_H
 29#define LSD_LIST_H
 30
 31
 32/***********
 33 *  Notes  *
 34 ***********/
 35/*
 36 *  If NDEBUG is not defined, internal debug code will be enabled.  This is
 37 *  intended for development use only and production code should define NDEBUG.
 38 *
 39 *  If WITH_LSD_FATAL_ERROR_FUNC is defined, the linker will expect to
 40 *  find an external lsd_fatal_error(file,line,mesg) function.  By default,
 41 *  lsd_fatal_error(file,line,mesg) is a macro definition that outputs an
 42 *  error message to stderr.  This macro may be redefined to invoke another
 43 *  routine instead.
 44 *
 45 *  If WITH_LSD_NOMEM_ERROR_FUNC is defined, the linker will expect to
 46 *  find an external lsd_nomem_error(file,line,mesg) function.  By default,
 47 *  lsd_nomem_error(file,line,mesg) is a macro definition that returns NULL.
 48 *  This macro may be redefined to invoke another routine instead.
 49 *
 50 *  If WITH_PTHREADS is defined, these routines will be thread-safe.
 51 */
 52
 53
 54/****************
 55 *  Data Types  *
 56 ****************/
 57
 58typedef struct list * List;
 59/*
 60 *  List opaque data type.
 61 */
 62
 63typedef struct listIterator * ListIterator;
 64/*
 65 *  List Iterator opaque data type.
 66 */
 67
 68typedef void (*ListDelF) (void *x);
 69/*
 70 *  Function prototype to deallocate data stored in a list.
 71 *    This function is responsible for freeing all memory associated
 72 *    with an item, including all subordinate items (if applicable).
 73 */
 74
 75typedef int (*ListCmpF) (void *x, void *y);
 76/*
 77 *  Function prototype for comparing two items in a list.
 78 *  Returns less-than-zero if (x<y), zero if (x==y), and
 79 *    greather-than-zero if (x>y).
 80 */
 81
 82typedef int (*ListFindF) (void *x, void *key);
 83/*
 84 *  Function prototype for matching items in a list.
 85 *  Returns non-zero if (x==key); o/w returns zero.
 86 */
 87
 88typedef int (*ListForF) (void *x, void *arg);
 89/*
 90 *  Function prototype for operating on each item in a list.
 91 *  Returns less-than-zero on error.
 92 */
 93
 94
 95/*******************************
 96 *  General-Purpose Functions  *
 97 *******************************/
 98
 99List list_create (ListDelF f);
100/*
101 *  Creates and returns a new empty list, or lsd_nomem_error() on failure.
102 *  The deletion function [f] is used to deallocate memory used by items
103 *    in the list; if this is NULL, memory associated with these items
104 *    will not be freed when the list is destroyed.
105 *  Note: Abandoning a list without calling list_destroy() will result
106 *    in a memory leak.
107 */
108
109void list_destroy (List l);
110/*
111 *  Destroys list [l], freeing memory used for list iterators and the
112 *    list itself; if a deletion function was specified when the list
113 *    was created, it will be called for each item in the list.
114 */
115
116int list_is_empty (List l);
117/*
118 *  Returns non-zero if list [l] is empty; o/w returns zero.
119 */
120
121int list_count (List l);
122/*
123 *  Returns the number of items in list [l].
124 */
125
126
127/***************************
128 *  List Access Functions  *
129 ***************************/
130
131void * list_append (List l, void *x);
132/*
133 *  Inserts data [x] at the end of list [l].
134 *  Returns the data's ptr, or lsd_nomem_error() if insertion failed.
135 */
136
137void * list_prepend (List l, void *x);
138/*
139 *  Inserts data [x] at the beginning of list [l].
140 *  Returns the data's ptr, or lsd_nomem_error() if insertion failed.
141 */
142
143void * list_find_first (List l, ListFindF f, void *key);
144/*
145 *  Traverses list [l] using [f] to match each item with [key].
146 *  Returns a ptr to the first item for which the function [f]
147 *    returns non-zero, or NULL if no such item is found.
148 *  Note: This function differs from list_find() in that it does not require
149 *    a list iterator; it should only be used when all list items are known
150 *    to be unique (according to the function [f]).
151 */
152
153int list_delete_all (List l, ListFindF f, void *key);
154/*
155 *  Traverses list [l] using [f] to match each item with [key].
156 *  Removes all items from the list for which the function [f] returns
157 *    non-zero; if a deletion function was specified when the list was
158 *    created, it will be called to deallocate each item being removed.
159 *  Returns a count of the number of items removed from the list.
160 */
161
162int list_for_each (List l, ListForF f, void *arg);
163/*
164 *  For each item in list [l], invokes the function [f] with [arg].
165 *  Returns a count of the number of items on which [f] was invoked.
166 *  If [f] returns <0 for a given item, the iteration is aborted and the
167 *    function returns the negative of that item's position in the list.
168 */
169
170void list_sort (List l, ListCmpF f);
171/*
172 *  Sorts list [l] into ascending order according to the function [f].
173 *  Note: Sorting a list resets all iterators associated with the list.
174 *  Note: The sort algorithm is stable.
175 */
176
177
178/****************************
179 *  Stack Access Functions  *
180 ****************************/
181
182void * list_push (List l, void *x);
183/*
184 *  Pushes data [x] onto the top of stack [l].
185 *  Returns the data's ptr, or lsd_nomem_error() if insertion failed.
186 */
187
188void * list_pop (List l);
189/*
190 *  Pops the data item at the top of the stack [l].
191 *  Returns the data's ptr, or NULL if the stack is empty.
192 */
193
194void * list_peek (List l);
195/*
196 *  Peeks at the data item at the top of the stack (or head of the queue) [l].
197 *  Returns the data's ptr, or NULL if the stack (or queue) is empty.
198 *  Note: The item is not removed from the list.
199 */
200
201
202/****************************
203 *  Queue Access Functions  *
204 ****************************/
205
206void * list_enqueue (List l, void *x);
207/*
208 *  Enqueues data [x] at the tail of queue [l].
209 *  Returns the data's ptr, or lsd_nomem_error() if insertion failed.
210 */
211
212void * list_dequeue (List l);
213/*
214 *  Dequeues the data item at the head of the queue [l].
215 *  Returns the data's ptr, or NULL if the queue is empty.
216 */
217
218
219/*****************************
220 *  List Iterator Functions  *
221 *****************************/
222
223ListIterator list_iterator_create (List l);
224/*
225 *  Creates and returns a list iterator for non-destructively traversing
226 *    list [l], or lsd_nomem_error() on failure.
227 */
228
229void list_iterator_reset (ListIterator i);
230/*
231 *  Resets the list iterator [i] to start traversal at the beginning
232 *    of the list.
233 */
234
235void list_iterator_destroy (ListIterator i);
236/*
237 *  Destroys the list iterator [i]; list iterators not explicitly destroyed
238 *    in this manner will be destroyed when the list is deallocated via
239 *    list_destroy().
240 */
241
242void * list_next (ListIterator i);
243/*
244 *  Returns a ptr to the next item's data,
245 *    or NULL once the end of the list is reached.
246 *  Example: i=list_iterator_create(i); while ((x=list_next(i))) {...}
247 */
248
249void * list_insert (ListIterator i, void *x);
250/*
251 *  Inserts data [x] immediately before the last item returned via list
252 *    iterator [i]; once the list iterator reaches the end of the list,
253 *    insertion is made at the list's end.
254 *  Returns the data's ptr, or lsd_nomem_error() if insertion failed.
255 */
256
257void * list_find (ListIterator i, ListFindF f, void *key);
258/*
259 *  Traverses the list from the point of the list iterator [i]
260 *    using [f] to match each item with [key].
261 *  Returns a ptr to the next item for which the function [f]
262 *    returns non-zero, or NULL once the end of the list is reached.
263 *  Example: i=list_iterator_reset(i); while ((x=list_find(i,f,k))) {...}
264 */
265
266void * list_remove (ListIterator i);
267/*
268 *  Removes from the list the last item returned via list iterator [i]
269 *    and returns the data's ptr.
270 *  Note: The client is responsible for freeing the returned data.
271 */
272
273int list_delete (ListIterator i);
274/*
275 *  Removes from the list the last item returned via list iterator [i];
276 *    if a deletion function was specified when the list was created,
277 *    it will be called to deallocate the item being removed.
278 *  Returns a count of the number of items removed from the list
279 *    (ie, '1' if the item was removed, and '0' otherwise).
280 */
281
282
283#endif /* !LSD_LIST_H */