lst.h revision 94589 
1/*
2 * Copyright (c) 1988, 1989, 1990, 1993
3 *	The Regents of the University of California.  All rights reserved.
4 * Copyright (c) 1988, 1989 by Adam de Boor
5 * Copyright (c) 1989 by Berkeley Softworks
6 * All rights reserved.
7 *
8 * This code is derived from software contributed to Berkeley by
9 * Adam de Boor.
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
13 * are met:
14 * 1. Redistributions of source code must retain the above copyright
15 *    notice, this list of conditions and the following disclaimer.
16 * 2. Redistributions in binary form must reproduce the above copyright
17 *    notice, this list of conditions and the following disclaimer in the
18 *    documentation and/or other materials provided with the distribution.
19 * 3. All advertising materials mentioning features or use of this software
20 *    must display the following acknowledgement:
21 *	This product includes software developed by the University of
22 *	California, Berkeley and its contributors.
23 * 4. Neither the name of the University nor the names of its contributors
24 *    may be used to endorse or promote products derived from this software
25 *    without specific prior written permission.
26 *
27 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
28 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
29 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
30 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
31 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
32 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
33 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
34 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
35 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
36 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 * SUCH DAMAGE.
38 *
39 *	@(#)lst.h	8.2 (Berkeley) 4/28/95
40 * $FreeBSD: head/usr.bin/make/lst.h 94589 2002-04-13 10:57:56Z obrien $
41 */
42
43/*-
44 * lst.h --
45 *	Header for using the list library
46 */
47#ifndef _LST_H_
48#define _LST_H_
49
50#include	<sys/param.h>
51#include	<stdlib.h>
52#include	"sprite.h"
53
54/*
55 * basic typedef. This is what the Lst_ functions handle
56 */
57
58typedef	struct	Lst	*Lst;
59typedef	struct	LstNode	*LstNode;
60
61/*
62 * NOFREE can be used as the freeProc to Lst_Destroy when the elements are
63 *	not to be freed.
64 * NOCOPY performs similarly when given as the copyProc to Lst_Duplicate.
65 */
66#define NOFREE		((void (*)(void *)) 0)
67#define NOCOPY		((void * (*)(void *)) 0)
68
69#define LST_CONCNEW	0   /* create new LstNode's when using Lst_Concat */
70#define LST_CONCLINK	1   /* relink LstNode's when using Lst_Concat */
71
72/*
73 * Creation/destruction functions
74 */
75/* Create a new list */
76Lst		Lst_Init(Boolean);
77/* Duplicate an existing list */
78Lst		Lst_Duplicate(Lst, void * (*)(void *));
79/* Destroy an old one */
80void		Lst_Destroy(Lst, void (*)(void *));
81/* True if list is empty */
82Boolean		Lst_IsEmpty(Lst);
83
84/*
85 * Functions to modify a list
86 */
87/* Insert an element before another */
88ReturnStatus	Lst_Insert(Lst, LstNode, void *);
89/* Insert an element after another */
90ReturnStatus	Lst_Append(Lst, LstNode, void *);
91/* Place an element at the front of a lst. */
92ReturnStatus	Lst_AtFront(Lst, void *);
93/* Place an element at the end of a lst. */
94ReturnStatus	Lst_AtEnd(Lst, void *);
95/* Remove an element */
96ReturnStatus	Lst_Remove(Lst, LstNode);
97/* Replace a node with a new value */
98ReturnStatus	Lst_Replace(LstNode, void *);
99/* Concatenate two lists */
100ReturnStatus	Lst_Concat(Lst, Lst, int);
101
102/*
103 * Node-specific functions
104 */
105/* Return first element in list */
106LstNode		Lst_First(Lst);
107/* Return last element in list */
108LstNode		Lst_Last(Lst);
109/* Return successor to given element */
110LstNode		Lst_Succ(LstNode);
111/* Get datum from LstNode */
112void *	Lst_Datum(LstNode);
113
114/*
115 * Functions for entire lists
116 */
117/* Find an element in a list */
118LstNode		Lst_Find(Lst, void *, int (*)(void *, void *));
119/* Find an element starting from somewhere */
120LstNode		Lst_FindFrom(Lst, LstNode, void *, int (*cProc)(void *, void *));
121/*
122 * See if the given datum is on the list. Returns the LstNode containing
123 * the datum
124 */
125LstNode		Lst_Member(Lst, void *);
126/* Apply a function to all elements of a lst */
127void		Lst_ForEach(Lst, int (*)(void *, void *), void *);
128/*
129 * Apply a function to all elements of a lst starting from a certain point.
130 * If the list is circular, the application will wrap around to the
131 * beginning of the list again.
132 */
133void		Lst_ForEachFrom(Lst, LstNode, int (*)(void *, void *), void *);
134/*
135 * these functions are for dealing with a list as a table, of sorts.
136 * An idea of the "current element" is kept and used by all the functions
137 * between Lst_Open() and Lst_Close().
138 */
139/* Open the list */
140ReturnStatus	Lst_Open(Lst);
141/* Next element please */
142LstNode		Lst_Next(Lst);
143/* Done yet? */
144Boolean		Lst_IsAtEnd(Lst);
145/* Finish table access */
146void		Lst_Close(Lst);
147
148/*
149 * for using the list as a queue
150 */
151/* Place an element at tail of queue */
152ReturnStatus	Lst_EnQueue(Lst, void *);
153/* Remove an element from head of queue */
154void *	Lst_DeQueue(Lst);
155
156#endif /* _LST_H_ */
157