 @@ -1,14 +1,14 @@
-/*	$NetBSD: lst.h,v 1.59 2020/08/30 11:15:05 rillig Exp $	*/
+/*	$NetBSD: lst.h,v 1.60 2020/09/02 23:33:13 rillig Exp $	*/
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
  * All rights reserved.
+ *
  * This code is derived from software contributed to Berkeley by
  * Adam de Boor.
+ *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
 @@ -63,115 +63,117 @@
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
+ *
  *	from: @(#)lst.h	8.1 (Berkeley) 6/6/93
  */
-/*-
+/* Doubly-linked lists of arbitrary pointers. */
  * lst.h --
  *	Header for using the list library
  */
 #ifndef MAKE_LST_H
 #define MAKE_LST_H
-#include	<sys/param.h>
+#include <sys/param.h>
-#include	<stdlib.h>
+#include <stdlib.h>
 /*
  * basic typedef. This is what the Lst_ functions handle
  */
 /* A doubly-linked list of pointers. */
 typedef	struct List	*Lst;
 /* A single node in the doubly-linked list. */
 typedef	struct ListNode	*LstNode;
 /* Copy a node, usually by allocating a copy of the given object.
  * For reference-counted objects, the original object may need to be
  * modified, therefore the parameter is not const. */
 typedef void *LstCopyProc(void *);
 /* Free the datum of a node, called before freeing the node itself. */
 typedef void LstFreeProc(void *);
-typedef Boolean LstFindProc(const void *, const void *);
+/* Return TRUE if the datum matches the args, for Lst_Find. */
-typedef int LstActionProc(void *, void *);
+typedef Boolean LstFindProc(const void *datum, const void *args);
 /* An action for Lst_ForEach. */
-/*
+typedef int LstActionProc(void *datum, void *args);
  * Creation/destruction functions
- */
+/* Create or destroy a list */
 /* Create a new list */
-Lst		Lst_Init(void);
+/* Create a new list. */
-/* Duplicate an existing list */
+Lst Lst_Init(void);
-Lst		Lst_Copy(Lst, LstCopyProc);
+/* Duplicate an existing list. */
-/* Destroy an old one */
+Lst Lst_Copy(Lst, LstCopyProc);
-void		Lst_Free(Lst);
+/* Free the list, leaving the node data unmodified. */
-void		Lst_Destroy(Lst, LstFreeProc);
+void Lst_Free(Lst);
-/* True if list is empty */
+/* Free the list, freeing the node data using the given function. */
-Boolean		Lst_IsEmpty(Lst);
+void Lst_Destroy(Lst, LstFreeProc);
-/*
+/* Get information about a list */
  * Functions to modify a list
- */
+Boolean Lst_IsEmpty(Lst);
-/* Insert an element before another */
+/* Return the first node of the list, or NULL. */
-void		Lst_InsertBefore(Lst, LstNode, void *);
+LstNode Lst_First(Lst);
-/* Place an element at the front of a lst. */
+/* Return the last node of the list, or NULL. */
-void		Lst_Prepend(Lst, void *);
+LstNode Lst_Last(Lst);
-/* Place an element at the end of a lst. */
+/* Find the first node for which the function returns TRUE, or NULL. */
-void		Lst_Append(Lst, void *);
+LstNode Lst_Find(Lst, LstFindProc, const void *);
-/* Remove an element */
+/* Find the first node for which the function returns TRUE, or NULL.
-void		Lst_Remove(Lst, LstNode);
+ * The search starts at the given node, towards the end of the list. */
-/* Replace a node with a new value */
+LstNode Lst_FindFrom(Lst, LstNode, LstFindProc, const void *);
-void		LstNode_Set(LstNode, void *);
+/* Find the first node that contains the given datum, or NULL. */
-void		LstNode_SetNull(LstNode);
+LstNode Lst_FindDatum(Lst, const void *);
-void		Lst_PrependAll(Lst, Lst);
+/* Modify a list */
 void		Lst_AppendAll(Lst, Lst);
-void		Lst_MoveAll(Lst, Lst);
+/* Insert a datum before the given node. */
 void Lst_InsertBefore(Lst, LstNode, void *);
-/*
+/* Place a datum at the front of the list. */
- * Node-specific functions
+void Lst_Prepend(Lst, void *);
- */
+/* Place a datum at the end of the list. */
-/* Return first element in list */
+void Lst_Append(Lst, void *);
-LstNode		Lst_First(Lst);
+/* Remove the node from the list. */
-/* Return last element in list */
+void Lst_Remove(Lst, LstNode);
-LstNode		Lst_Last(Lst);
+void Lst_PrependAll(Lst, Lst);
-/* Return successor to given element */
+void Lst_AppendAll(Lst, Lst);
-LstNode		LstNode_Next(LstNode);
+void Lst_MoveAll(Lst, Lst);
 /* Return predecessor to given element */
-LstNode		LstNode_Prev(LstNode);
+/* Node-specific functions */
 /* Get datum from LstNode */
-void		*LstNode_Datum(LstNode);
+/* Return the successor of the node, or NULL. */
 LstNode LstNode_Next(LstNode);
-/*
+/* Return the predecessor of the node, or NULL. */
- * Functions for entire lists
+LstNode LstNode_Prev(LstNode);
- */
+/* Return the datum of the node. Usually not NULL. */
-/* Find an element in a list */
+void *LstNode_Datum(LstNode);
-LstNode		Lst_Find(Lst, LstFindProc, const void *);
+/* Replace the value of the node. */
-/* Find an element starting from somewhere */
+void LstNode_Set(LstNode, void *);
-LstNode		Lst_FindFrom(Lst, LstNode, LstFindProc, const void *);
+/* Set the value of the node to NULL. Having NULL in a list is unusual. */
-/* Return the first node that contains the given datum, or NULL. */
+void LstNode_SetNull(LstNode);
 LstNode		Lst_FindDatum(Lst, const void *);
-/* Apply a function to all elements of a lst */
+/* Iterating over a list, using a callback function */
 int		Lst_ForEach(Lst, LstActionProc, void *);
-/* Apply a function to all elements of a lst starting from a certain point. */
+/* Apply a function to each datum of the list, until the callback function
-int		Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *);
+ * returns non-zero. */
-/*
+int Lst_ForEach(Lst, LstActionProc, void *);
- * these functions are for dealing with a list as a table, of sorts.
+/* Apply a function to each datum of the list, starting at the node,
- * An idea of the "current element" is kept and used by all the functions
+ * until the callback function returns non-zero. */
- * between Lst_Open() and Lst_Close().
+int Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *);
  */
-/* Open the list */
+/* Iterating over a list while keeping track of the current node and possible
-void		Lst_Open(Lst);
+ * concurrent modifications */
 /* Next element please, or NULL */
-LstNode		Lst_Next(Lst);
+/* Start iterating the list. */
-/* Finish table access */
+void Lst_Open(Lst);
-void		Lst_Close(Lst);
+/* Return the next node, or NULL. */
 LstNode Lst_Next(Lst);
-/*
+/* Finish iterating the list. */
- * for using the list as a queue
+void Lst_Close(Lst);
  */
-/* Place an element at tail of queue */
+/* Using the list as a queue */
 void		Lst_Enqueue(Lst, void *);
-/* Remove an element from head of queue */
+/* Add a datum at the tail of the queue. */
-void		*Lst_Dequeue(Lst);
+void Lst_Enqueue(Lst, void *);
 /* Remove the head node of the queue and return its datum. */
 void *Lst_Dequeue(Lst);
 #endif /* MAKE_LST_H */