contrib/bmake/lst.h

   1 /*      $NetBSD: lst.h,v 1.60 2020/09/02 23:33:13 rillig Exp $  */
   2
   3 /*
   4  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
   5  * All rights reserved.
   6  *
   7  * This code is derived from software contributed to Berkeley by
   8  * Adam de Boor.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions
  12  * are met:
  13  * 1. Redistributions of source code must retain the above copyright
  14  *    notice, this list of conditions and the following disclaimer.
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in the
  17  *    documentation and/or other materials provided with the distribution.
  18  * 3. Neither the name of the University nor the names of its contributors
  19  *    may be used to endorse or promote products derived from this software
  20  *    without specific prior written permission.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32  * SUCH DAMAGE.
  33  *
  34  *      from: @(#)lst.h 8.1 (Berkeley) 6/6/93
  35  */
  36
  37 /*
  38  * Copyright (c) 1988, 1989 by Adam de Boor
  39  * Copyright (c) 1989 by Berkeley Softworks
  40  * All rights reserved.
  41  *
  42  * This code is derived from software contributed to Berkeley by
  43  * Adam de Boor.
  44  *
  45  * Redistribution and use in source and binary forms, with or without
  46  * modification, are permitted provided that the following conditions
  47  * are met:
  48  * 1. Redistributions of source code must retain the above copyright
  49  *    notice, this list of conditions and the following disclaimer.
  50  * 2. Redistributions in binary form must reproduce the above copyright
  51  *    notice, this list of conditions and the following disclaimer in the
  52  *    documentation and/or other materials provided with the distribution.
  53  * 3. All advertising materials mentioning features or use of this software
  54  *    must display the following acknowledgement:
  55  *      This product includes software developed by the University of
  56  *      California, Berkeley and its contributors.
  57  * 4. Neither the name of the University nor the names of its contributors
  58  *    may be used to endorse or promote products derived from this software
  59  *    without specific prior written permission.
  60  *
  61  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  62  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  63  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  64  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  65  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  66  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  67  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  68  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  69  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  70  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  71  * SUCH DAMAGE.
  72  *
  73  *      from: @(#)lst.h 8.1 (Berkeley) 6/6/93
  74  */
  75
  76 /* Doubly-linked lists of arbitrary pointers. */
  77
  78 #ifndef MAKE_LST_H
  79 #define MAKE_LST_H
  80
  81 #include <sys/param.h>
  82 #include <stdlib.h>
  83
  84 /* A doubly-linked list of pointers. */
  85 typedef struct List     *Lst;
  86 /* A single node in the doubly-linked list. */
  87 typedef struct ListNode *LstNode;
  88
  89 /* Copy a node, usually by allocating a copy of the given object.
  90  * For reference-counted objects, the original object may need to be
  91  * modified, therefore the parameter is not const. */
  92 typedef void *LstCopyProc(void *);
  93 /* Free the datum of a node, called before freeing the node itself. */
  94 typedef void LstFreeProc(void *);
  95 /* Return TRUE if the datum matches the args, for Lst_Find. */
  96 typedef Boolean LstFindProc(const void *datum, const void *args);
  97 /* An action for Lst_ForEach. */
  98 typedef int LstActionProc(void *datum, void *args);
  99
 100 /* Create or destroy a list */
 101
 102 /* Create a new list. */
 103 Lst Lst_Init(void);
 104 /* Duplicate an existing list. */
 105 Lst Lst_Copy(Lst, LstCopyProc);
 106 /* Free the list, leaving the node data unmodified. */
 107 void Lst_Free(Lst);
 108 /* Free the list, freeing the node data using the given function. */
 109 void Lst_Destroy(Lst, LstFreeProc);
 110
 111 /* Get information about a list */
 112
 113 Boolean Lst_IsEmpty(Lst);
 114 /* Return the first node of the list, or NULL. */
 115 LstNode Lst_First(Lst);
 116 /* Return the last node of the list, or NULL. */
 117 LstNode Lst_Last(Lst);
 118 /* Find the first node for which the function returns TRUE, or NULL. */
 119 LstNode Lst_Find(Lst, LstFindProc, const void *);
 120 /* Find the first node for which the function returns TRUE, or NULL.
 121  * The search starts at the given node, towards the end of the list. */
 122 LstNode Lst_FindFrom(Lst, LstNode, LstFindProc, const void *);
 123 /* Find the first node that contains the given datum, or NULL. */
 124 LstNode Lst_FindDatum(Lst, const void *);
 125
 126 /* Modify a list */
 127
 128 /* Insert a datum before the given node. */
 129 void Lst_InsertBefore(Lst, LstNode, void *);
 130 /* Place a datum at the front of the list. */
 131 void Lst_Prepend(Lst, void *);
 132 /* Place a datum at the end of the list. */
 133 void Lst_Append(Lst, void *);
 134 /* Remove the node from the list. */
 135 void Lst_Remove(Lst, LstNode);
 136 void Lst_PrependAll(Lst, Lst);
 137 void Lst_AppendAll(Lst, Lst);
 138 void Lst_MoveAll(Lst, Lst);
 139
 140 /* Node-specific functions */
 141
 142 /* Return the successor of the node, or NULL. */
 143 LstNode LstNode_Next(LstNode);
 144 /* Return the predecessor of the node, or NULL. */
 145 LstNode LstNode_Prev(LstNode);
 146 /* Return the datum of the node. Usually not NULL. */
 147 void *LstNode_Datum(LstNode);
 148 /* Replace the value of the node. */
 149 void LstNode_Set(LstNode, void *);
 150 /* Set the value of the node to NULL. Having NULL in a list is unusual. */
 151 void LstNode_SetNull(LstNode);
 152
 153 /* Iterating over a list, using a callback function */
 154
 155 /* Apply a function to each datum of the list, until the callback function
 156  * returns non-zero. */
 157 int Lst_ForEach(Lst, LstActionProc, void *);
 158 /* Apply a function to each datum of the list, starting at the node,
 159  * until the callback function returns non-zero. */
 160 int Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *);
 161
 162 /* Iterating over a list while keeping track of the current node and possible
 163  * concurrent modifications */
 164
 165 /* Start iterating the list. */
 166 void Lst_Open(Lst);
 167 /* Return the next node, or NULL. */
 168 LstNode Lst_Next(Lst);
 169 /* Finish iterating the list. */
 170 void Lst_Close(Lst);
 171
 172 /* Using the list as a queue */
 173
 174 /* Add a datum at the tail of the queue. */
 175 void Lst_Enqueue(Lst, void *);
 176 /* Remove the head node of the queue and return its datum. */
 177 void *Lst_Dequeue(Lst);
 178
 179 #endif /* MAKE_LST_H */