make(1): improve grouping of the Lst functions
Lst_IsEmpty does not belong in the "create and destroy" group, but in "query information without modifying anything". The functions named LstNode_* all belong together. They do not provide much abstraction, but still they restrict the API and hide a few struct fields that are only used internally by Lst_Open/Lst_Close and Lst_ForEach. Use consistent wording in the documentation of the functions (list, node, datum).
This commit is contained in:
rillig
parent
cd07afa0d7
commit
c62bab2173
|
|
@ -1,4 +1,4 @@
|
|||
/* $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.
|
||||
|
|
@ -73,105 +73,107 @@
|
|||
* from: @(#)lst.h 8.1 (Berkeley) 6/6/93
|
||||
*/
|
||||
|
||||
/*-
|
||||
* lst.h --
|
||||
* Header for using the list library
|
||||
*/
|
||||
/* Doubly-linked lists of arbitrary pointers. */
|
||||
|
||||
#ifndef MAKE_LST_H
|
||||
#define MAKE_LST_H
|
||||
|
||||
#include <sys/param.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
/*
|
||||
* basic typedef. This is what the Lst_ functions handle
|
||||
*/
|
||||
#include <sys/param.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
/* 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 *);
|
||||
typedef int LstActionProc(void *, void *);
|
||||
/* Return TRUE if the datum matches the args, for Lst_Find. */
|
||||
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 a new list */
|
||||
Lst Lst_Init(void);
|
||||
/* Duplicate an existing list */
|
||||
Lst Lst_Copy(Lst, LstCopyProc);
|
||||
/* Destroy an old one */
|
||||
void Lst_Free(Lst);
|
||||
void Lst_Destroy(Lst, LstFreeProc);
|
||||
/* True if list is empty */
|
||||
Boolean Lst_IsEmpty(Lst);
|
||||
/* Create or destroy a list */
|
||||
|
||||
/*
|
||||
* Functions to modify a list
|
||||
*/
|
||||
/* Insert an element before another */
|
||||
void Lst_InsertBefore(Lst, LstNode, void *);
|
||||
/* Place an element at the front of a lst. */
|
||||
void Lst_Prepend(Lst, void *);
|
||||
/* Place an element at the end of a lst. */
|
||||
void Lst_Append(Lst, void *);
|
||||
/* Remove an element */
|
||||
void Lst_Remove(Lst, LstNode);
|
||||
/* Replace a node with a new value */
|
||||
void LstNode_Set(LstNode, void *);
|
||||
void LstNode_SetNull(LstNode);
|
||||
/* Create a new list. */
|
||||
Lst Lst_Init(void);
|
||||
/* Duplicate an existing list. */
|
||||
Lst Lst_Copy(Lst, LstCopyProc);
|
||||
/* Free the list, leaving the node data unmodified. */
|
||||
void Lst_Free(Lst);
|
||||
/* Free the list, freeing the node data using the given function. */
|
||||
void Lst_Destroy(Lst, LstFreeProc);
|
||||
|
||||
void Lst_PrependAll(Lst, Lst);
|
||||
void Lst_AppendAll(Lst, Lst);
|
||||
void Lst_MoveAll(Lst, Lst);
|
||||
/* Get information about a list */
|
||||
|
||||
/*
|
||||
* Node-specific functions
|
||||
*/
|
||||
/* Return first element in list */
|
||||
LstNode Lst_First(Lst);
|
||||
/* Return last element in list */
|
||||
LstNode Lst_Last(Lst);
|
||||
/* Return successor to given element */
|
||||
LstNode LstNode_Next(LstNode);
|
||||
/* Return predecessor to given element */
|
||||
LstNode LstNode_Prev(LstNode);
|
||||
/* Get datum from LstNode */
|
||||
void *LstNode_Datum(LstNode);
|
||||
Boolean Lst_IsEmpty(Lst);
|
||||
/* Return the first node of the list, or NULL. */
|
||||
LstNode Lst_First(Lst);
|
||||
/* Return the last node of the list, or NULL. */
|
||||
LstNode Lst_Last(Lst);
|
||||
/* Find the first node for which the function returns TRUE, or NULL. */
|
||||
LstNode Lst_Find(Lst, LstFindProc, const void *);
|
||||
/* Find the first node for which the function returns TRUE, or NULL.
|
||||
* The search starts at the given node, towards the end of the list. */
|
||||
LstNode Lst_FindFrom(Lst, LstNode, LstFindProc, const void *);
|
||||
/* Find the first node that contains the given datum, or NULL. */
|
||||
LstNode Lst_FindDatum(Lst, const void *);
|
||||
|
||||
/*
|
||||
* Functions for entire lists
|
||||
*/
|
||||
/* Find an element in a list */
|
||||
LstNode Lst_Find(Lst, LstFindProc, const void *);
|
||||
/* Find an element starting from somewhere */
|
||||
LstNode Lst_FindFrom(Lst, LstNode, LstFindProc, const void *);
|
||||
/* Return the first node that contains the given datum, or NULL. */
|
||||
LstNode Lst_FindDatum(Lst, const void *);
|
||||
/* Apply a function to all elements of a lst */
|
||||
int Lst_ForEach(Lst, LstActionProc, void *);
|
||||
/* Apply a function to all elements of a lst starting from a certain point. */
|
||||
int Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *);
|
||||
/*
|
||||
* these functions are for dealing with a list as a table, of sorts.
|
||||
* An idea of the "current element" is kept and used by all the functions
|
||||
* between Lst_Open() and Lst_Close().
|
||||
*/
|
||||
/* Open the list */
|
||||
void Lst_Open(Lst);
|
||||
/* Next element please, or NULL */
|
||||
LstNode Lst_Next(Lst);
|
||||
/* Finish table access */
|
||||
void Lst_Close(Lst);
|
||||
/* Modify a list */
|
||||
|
||||
/*
|
||||
* for using the list as a queue
|
||||
*/
|
||||
/* Place an element at tail of queue */
|
||||
void Lst_Enqueue(Lst, void *);
|
||||
/* Remove an element from head of queue */
|
||||
void *Lst_Dequeue(Lst);
|
||||
/* Insert a datum before the given node. */
|
||||
void Lst_InsertBefore(Lst, LstNode, void *);
|
||||
/* Place a datum at the front of the list. */
|
||||
void Lst_Prepend(Lst, void *);
|
||||
/* Place a datum at the end of the list. */
|
||||
void Lst_Append(Lst, void *);
|
||||
/* Remove the node from the list. */
|
||||
void Lst_Remove(Lst, LstNode);
|
||||
void Lst_PrependAll(Lst, Lst);
|
||||
void Lst_AppendAll(Lst, Lst);
|
||||
void Lst_MoveAll(Lst, Lst);
|
||||
|
||||
/* Node-specific functions */
|
||||
|
||||
/* Return the successor of the node, or NULL. */
|
||||
LstNode LstNode_Next(LstNode);
|
||||
/* Return the predecessor of the node, or NULL. */
|
||||
LstNode LstNode_Prev(LstNode);
|
||||
/* Return the datum of the node. Usually not NULL. */
|
||||
void *LstNode_Datum(LstNode);
|
||||
/* Replace the value of the node. */
|
||||
void LstNode_Set(LstNode, void *);
|
||||
/* Set the value of the node to NULL. Having NULL in a list is unusual. */
|
||||
void LstNode_SetNull(LstNode);
|
||||
|
||||
/* Iterating over a list, using a callback function */
|
||||
|
||||
/* Apply a function to each datum of the list, until the callback function
|
||||
* returns non-zero. */
|
||||
int Lst_ForEach(Lst, LstActionProc, void *);
|
||||
/* Apply a function to each datum of the list, starting at the node,
|
||||
* until the callback function returns non-zero. */
|
||||
int Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *);
|
||||
|
||||
/* Iterating over a list while keeping track of the current node and possible
|
||||
* concurrent modifications */
|
||||
|
||||
/* Start iterating the list. */
|
||||
void Lst_Open(Lst);
|
||||
/* Return the next node, or NULL. */
|
||||
LstNode Lst_Next(Lst);
|
||||
/* Finish iterating the list. */
|
||||
void Lst_Close(Lst);
|
||||
|
||||
/* Using the list as a queue */
|
||||
|
||||
/* Add a datum at the tail of the queue. */
|
||||
void Lst_Enqueue(Lst, void *);
|
||||
/* Remove the head node of the queue and return its datum. */
|
||||
void *Lst_Dequeue(Lst);
|
||||
|
||||
#endif /* MAKE_LST_H */
|
||||
|
|
|
|||
Loading…
Reference in New Issue