[Home] [ToC] [Up] [Prev] [Next]
The iHTML library's doubly-linked list services are a standard set of types and functions for managing arbtrirary doubly-linked list structures. They are used by putting the IHNode structure at the type of another structure that is to be used in a list; the list management routines may then be used directly on that new structure's IHNode field.
typedef struct ih_list_rec {
IHNode *lh_Head; /* The first node in the list */
IHNode *lh_Tail; /* The last node in the list */
} IHList;
This is a handle on a full doubly-linked list of nodes. It can be created two ways: dynamically by calling IH_AllocList(), and statically by reserving memory for the list structure and then calling IH_InitList() on it.
typedef struct ih_node_rec {
IHNode *ln_Succ; /* Pointer to next (successor) */
IHNode *ln_Pred; /* Pointer to previous (predecessor) */
} IHNode;
This type represents a single node in a longer doubly-linked list of nodes. It can be appended to the top of any structure that needs to be put into a list. Any objects that incorporate this node should be allocated by calling IH_AllocNode().
void* IH_AddHead(IHList* ls,IHNode*
nd)
(IHList*)
ls
(IHNode*)
nd
(void*) The new head of the
list, i.e. nd.
Inserts the given node into the front of the list.
void* IH_AddTail(IHList* ls,IHNode*
nd)
(IHList*)
ls
(IHNode*)
nd
(void*) The new tail of the
list, i.e. nd.
Appends the given node to the back of the list.
void* IH_AllocNode(int size)
(int)
size
(void*) A new instance of the
node.
This function is used to allocate a new structure that is being used as a node. The size is the total size of the structure, include the IHNode at the top. Memory for the new structure is allocated, cleared to zeros, and returned.
IHList* IH_AllocList(void)
(IHList*) A new list.
Allocates and initializes a new list.
void IH_FreeList(IHList* ls)
(IHList*)
ls
This function deallocates an IHList, and all nodes attached to it. This can be called on a non-empty list if its nodes can be deallocated by calling free() on them; otherwise, all nodes should be removed from the list and then it may be deallocated.
void* IH_GetHead(IHList* ls)
(IHList*)
ls
(void*) The first node in the
list.
Returns the first node in a list. Returns NULL if the list is empty.
void* IH_GetTail(IHList* ls)
(IHList*)
ls
(void*) The first node in the
list.
Returns the last node in a list. Returns NULL if the list is empty.
void IH_InitList(IHList* ls)
(IHList*)
ls
Initializes the fields on of IHList. This function should be called on any IHList that has not been created with IH_AllocList(), prior to using it.
void* IH_InsNode(IHList* ls,IHNode*
place, IHNode* nd)
(IHList*)
ls
(IHNode*)
place
(IHNode*)
nd
(void*) The new node located
after the position, i.e. nd.
Inserts the given node into the list, after the location indicated by place. If place is NULL, the node is inserted at the head of the list.
void* IH_NextNode(IHList* ls, IHNode*
nd)
(IHList*)
ls
(IHNode*)
nd
(void*) The node that appears
after the given node in the list.
/* Traverse forward through a list. */
IHNode* nd = NULL;
while( (nd=IH_NextNode(ls,nd)) ) {
/* Do something with nd. */
}
Returns the node that occurs after the given node in a list. If the given node is NULL, the first node in the list is returned.
void* IH_PrevNode(IHList* ls, IHNode*
nd)
(IHList*)
ls
(IHNode*)
nd
(void*) The node that appears
prior the given node in the list.
/* Traverse backward through a list. */
IHNode* nd = NULL;
while( (nd=IH_PrevNode(ls,nd)) ) {
/* Do something with nd. */
}
Returns the node that occurs before the given node in a list. If the given node is NULL, the last node in the list is returned.
void* IH_RemHead(IHList* ls)
(IHList*)
ls
(void*) The old head node of
the list.
Removes the head node from the list, and returns it. Returns NULL if the list is empty.
void* IH_RemNode(IHList* ls, IHNode*
nd)
(IHList*)
ls
(IHNode*)
nd
(void*) The node removed from
the list, i.e. nd.
Removes the given node from the list, and returns it. The node must be in the list when this function is called.
void* IH_RemTail(IHList* ls)
(IHList*)
ls
(void*) The old tail node of
the list.
/* Remove and deallocate all nodes from a list. */
IHNode* nd;
while( (nd=IH_RemTail(ls)) ) {
free(nd);
}
Removes the tail node from the list, and returns it. Returns NULL if the list is empty.
[Home] [ToC] [Up] [Prev] [Next]
| Dianne Kyra Hackborn <hackbod@angryredplanet.com> | Last modified: Tue Oct 8 04:11:59 PDT 1996 |