usr.bin/make/lst.h

   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  *      from: @(#)lst.h 8.1 (Berkeley) 6/6/93
  40  * $FreeBSD: src/usr.bin/make/lst.h,v 1.9 1999/08/28 01:03:32 peter Exp $
  41  * $DragonFly: src/usr.bin/make/lst.h,v 1.11 2004/12/09 19:16:03 okumoto Exp $
  42  */
  43
  44 /*-
  45  * lst.h --
  46  *      Header for using the list library
  47  */
  48 #ifndef _LST_H_
  49 #define _LST_H_
  50
  51 #include        <sys/param.h>
  52 #include        <stdlib.h>
  53 #include        "sprite.h"
  54
  55 /*
  56  * Structure of a list node.
  57  */
  58 struct LstNode {
  59         struct LstNode  *prevPtr;   /* previous element in list */
  60         struct LstNode  *nextPtr;   /* next in list */
  61         int     useCount:8; /* Count of functions using the node. Node may not
  62                              * be deleted until count goes to 0 */
  63         int     flags:8;    /* Node status flags */
  64         void    *datum;     /* datum associated with this element */
  65 };
  66 typedef struct  LstNode *LstNode;
  67
  68 /*
  69  * Flags required for synchronization
  70  */
  71 #define LN_DELETED      0x0001      /* List node should be removed when done */
  72
  73 typedef enum {
  74         LstHead, LstMiddle, LstTail, LstUnknown
  75 } LstWhere;
  76
  77 /*
  78  * The list itself
  79  */
  80 struct Lst {
  81         LstNode         firstPtr; /* first node in list */
  82         LstNode         lastPtr;  /* last node in list */
  83         Boolean         isCirc;   /* true if the list should be considered
  84                                    * circular */
  85         /*
  86          * fields for sequential access
  87          */
  88         LstWhere        atEnd;    /* Where in the list the last access was */
  89         Boolean         isOpen;   /* true if list has been Lst_Open'ed */
  90         LstNode         curPtr;   /* current node, if open. NULL if
  91                                    * *just* opened */
  92         LstNode         prevPtr;  /* Previous node, if open. Used by
  93                                    * Lst_Remove */
  94 };
  95 typedef struct  Lst     *Lst;
  96
  97 typedef int CompareProc(void *, void *);
  98 typedef int DoProc(void *, void *);
  99 typedef void *DuplicateProc(void *);
 100 typedef void FreeProc(void *);
 101
 102 /*
 103  * NOFREE can be used as the freeProc to Lst_Destroy when the elements are
 104  *      not to be freed.
 105  * NOCOPY performs similarly when given as the copyProc to Lst_Duplicate.
 106  */
 107 #define NOFREE          ((FreeProc *)NULL)
 108 #define NOCOPY          ((DuplicateProc *)NULL)
 109
 110 #define LST_CONCNEW     0   /* create new LstNode's when using Lst_Concat */
 111 #define LST_CONCLINK    1   /* relink LstNode's when using Lst_Concat */
 112
 113 /*
 114  * Creation/destruction functions
 115  */
 116 /* Create a new list */
 117 Lst             Lst_Init(Boolean);
 118 /* Duplicate an existing list */
 119 Lst             Lst_Duplicate(Lst, DuplicateProc *);
 120 /* Destroy an old one */
 121 void            Lst_Destroy(Lst, FreeProc *);
 122
 123 /*
 124  * Functions to modify a list
 125  */
 126 /* Insert an element before another */
 127 ReturnStatus    Lst_Insert(Lst, LstNode, void *);
 128 /* Insert an element after another */
 129 ReturnStatus    Lst_Append(Lst, LstNode, void *);
 130 /* Place an element at the front of a lst. */
 131 #define Lst_AtFront(LST, D)     (Lst_Insert((LST), Lst_First(LST), (D)))
 132 /* Place an element at the end of a lst. */
 133 #define Lst_AtEnd(LST, D)       (Lst_Append((LST), Lst_Last(LST), (D)))
 134 /* Remove an element */
 135 ReturnStatus    Lst_Remove(Lst, LstNode);
 136 /* Replace a node with a new value */
 137 #define Lst_Replace(NODE, D)    (((NODE) == NULL) ? FAILURE : \
 138                                     (((NODE)->datum = (D)), SUCCESS))
 139 /* Concatenate two lists */
 140 ReturnStatus    Lst_Concat(Lst, Lst, int);
 141
 142 /*
 143  * Node-specific functions
 144  */
 145 /* Return first element in list */
 146 #define Lst_First(LST)  ((Lst_Valid(LST) && !Lst_IsEmpty(LST)) \
 147                             ? (LST)->firstPtr : NULL)
 148 /* Return last element in list */
 149 #define Lst_Last(LST)   ((Lst_Valid(LST) && !Lst_IsEmpty(LST)) \
 150                             ? (LST)->lastPtr : NULL)
 151 /* Return successor to given element */
 152 #define Lst_Succ(NODE)  (((NODE) == NULL) ? NULL : (NODE)->nextPtr)
 153 /* Get datum from LstNode */
 154 #define Lst_Datum(NODE) ((NODE)->datum)
 155
 156 /*
 157  * Functions for entire lists
 158  */
 159 /* Find an element in a list */
 160 #define Lst_Find(LST, D, FN)    (Lst_FindFrom((LST), Lst_First(LST), (D), (FN)))
 161 /* Find an element starting from somewhere */
 162 LstNode         Lst_FindFrom(Lst, LstNode, void *, CompareProc *);
 163 /*
 164  * See if the given datum is on the list. Returns the LstNode containing
 165  * the datum
 166  */
 167 LstNode         Lst_Member(Lst, void *);
 168 /* Apply a function to all elements of a lst */
 169 void            Lst_ForEach(Lst, DoProc *, void *);
 170 #define Lst_ForEach(LST, FN, D) (Lst_ForEachFrom((LST), Lst_First(LST), \
 171                                     (FN), (D)))
 172 /*
 173  * Apply a function to all elements of a lst starting from a certain point.
 174  * If the list is circular, the application will wrap around to the
 175  * beginning of the list again.
 176  */
 177 void            Lst_ForEachFrom(Lst, LstNode, DoProc *, void *);
 178 /*
 179  * these functions are for dealing with a list as a table, of sorts.
 180  * An idea of the "current element" is kept and used by all the functions
 181  * between Lst_Open() and Lst_Close().
 182  */
 183 /* Open the list */
 184 ReturnStatus    Lst_Open(Lst);
 185 /* Next element please */
 186 LstNode         Lst_Next(Lst);
 187 /* Done yet? */
 188 Boolean         Lst_IsAtEnd(Lst);
 189 /* Finish table access */
 190 void            Lst_Close(Lst);
 191
 192 /*
 193  * for using the list as a queue
 194  */
 195 /* Place an element at tail of queue */
 196 #define Lst_EnQueue(LST, D)     (Lst_Valid(LST) \
 197                                     ? Lst_Append((LST), Lst_Last(LST), (D)) \
 198                                     : FAILURE)
 199 /* Remove an element from head of queue */
 200 void *  Lst_DeQueue(Lst);
 201
 202 /*
 203  * LstValid (L) --
 204  *      Return TRUE if the list L is valid
 205  */
 206 #define Lst_Valid(L)    (((L) == NULL) ? FALSE : TRUE)
 207
 208 /*
 209  * LstNodeValid (LN, L) --
 210  *      Return TRUE if the LstNode LN is valid with respect to L
 211  */
 212 #define Lst_NodeValid(LN, L)    (((LN) == NULL) ? FALSE : TRUE)
 213
 214 /*
 215  * Lst_IsEmpty(L) --
 216  *      TRUE if the list L is empty.
 217  */
 218 #define Lst_IsEmpty(L)  (!Lst_Valid(L) || (L)->firstPtr == NULL)
 219
 220
 221 #endif /* _LST_H_ */