365 lines
9.5 KiB
C++
365 lines
9.5 KiB
C++
// VXWList/vxwLstLib.h - simple linked list class
|
|
|
|
// Copyright 1995-1999 Wind River Systems, Inc.
|
|
|
|
// modification history
|
|
// --------------------
|
|
// 01e,28mar99,jdi doc: removed mention of support for Booch class.
|
|
// 01d,23feb99,fle made it refgen parsable
|
|
// 01c,21feb99,jdi added library section, checked in documentation.
|
|
// 01b,03oct95,rhp moved "Using" instructions to library man page;
|
|
// documented constructors and member fns.
|
|
// 01a,15jun95,srh written.
|
|
|
|
// DESCRIPTION
|
|
// The VXWList class supports the creation and maintenance of a doubly
|
|
// linked list. The class contains pointers to the first and last
|
|
// nodes in the list, and a count of the number of nodes in the list.
|
|
// The nodes in the list are derived from the structure NODE, which
|
|
// provides two pointers: `NODE::next' and `NODE::previous'.
|
|
// Both the forward and backward chains are terminated with a NULL pointer.
|
|
//
|
|
// The VXWList class simply manipulates the linked-list data structures;
|
|
// no kernel functions are invoked. In particular, linked lists by themselves
|
|
// provide no task synchronization or mutual exclusion. If multiple tasks will
|
|
// access a single linked list, that list must be guarded with some
|
|
// mutual-exclusion mechanism (such as a mutual-exclusion semaphore).
|
|
//
|
|
// NON-EMPTY LIST:
|
|
// .CS
|
|
// --------- -------- --------
|
|
// | head--------------->| next----------->| next---------
|
|
// | | | | | | |
|
|
// | | ------- prev |<---------- prev | |
|
|
// | | | | | | | |
|
|
// | tail------ | | ... | ----->| ... | |
|
|
// | | | v | v
|
|
// |count=2| | ----- | -----
|
|
// --------- | --- | ---
|
|
// | - | -
|
|
// | |
|
|
// ------------------------
|
|
// .CE
|
|
//
|
|
// EMPTY LIST:
|
|
// .CS
|
|
// -----------
|
|
// | head------------------
|
|
// | | |
|
|
// | tail---------- |
|
|
// | | | v
|
|
// | count=0 | ----- -----
|
|
// ----------- --- ---
|
|
// - -
|
|
// .CE
|
|
//
|
|
// WARNINGS
|
|
// Use only single inheritance! This class is an interface to the
|
|
// VxWorks library lstLib. More sophisticated alternatives are
|
|
// available in the Tools.h++ class libraries.
|
|
//
|
|
// EXAMPLE
|
|
// The following example illustrates how to create a list by deriving
|
|
// elements from NODE and putting them on a VXWList.
|
|
//
|
|
// .CS
|
|
// class myListNode : public NODE
|
|
// {
|
|
// public:
|
|
// myListNode ()
|
|
// {
|
|
// }
|
|
// private:
|
|
// };
|
|
//
|
|
// VXWList myList;
|
|
// myListNode a, b, c;
|
|
//
|
|
// NODE * pEl = &c;
|
|
//
|
|
// void useList ()
|
|
// {
|
|
// myList.add (&a);
|
|
// myList.insert (pEl, &b);
|
|
// }
|
|
// .CE
|
|
//
|
|
// INCLUDE FILES: vxwLstLib.h
|
|
//
|
|
// SECTION: 1C
|
|
//
|
|
|
|
#ifndef vxwLstLib_h
|
|
#define vxwLstLib_h
|
|
|
|
#include "vxWorks.h"
|
|
#include "lstLib.h"
|
|
#include "vxwErr.h"
|
|
|
|
class VXWList : virtual public LIST
|
|
{
|
|
public:
|
|
|
|
//_ VXWList Public Constructors
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::VXWList - initialize a list
|
|
//
|
|
// This constructor initializes a list as an empty list.
|
|
//
|
|
// RETURNS: N/A
|
|
|
|
VXWList ()
|
|
{
|
|
lstInit (&list_);
|
|
}
|
|
|
|
VXWList & operator = (const VXWList &);
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::VXWList - initialize a list as a copy of another
|
|
//
|
|
// This constructor builds a new list as a copy of an existing list.
|
|
//
|
|
// RETURNS: N/A
|
|
|
|
VXWList (const VXWList &);
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::~VXWList - free up a list
|
|
//
|
|
// This destructor frees up memory used for nodes.
|
|
//
|
|
// RETURNS: N/A
|
|
|
|
~VXWList ()
|
|
{
|
|
lstFree (&list_);
|
|
}
|
|
|
|
//_ VXWList Public Member Functions
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::add - add a node to the end of list
|
|
//
|
|
// This routine adds a specified node to the end of the list.
|
|
//
|
|
// RETURNS: N/A
|
|
|
|
void add (NODE *pNode)
|
|
{
|
|
lstAdd (&list_, pNode);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::concat - concatenate two lists
|
|
//
|
|
// This routine concatenates the specified list to the end of the current list.
|
|
// The specified list is left empty. Either list (or both) can be
|
|
// empty at the beginning of the operation.
|
|
//
|
|
// RETURNS: N/A
|
|
|
|
void concat (VXWList &aList)
|
|
{
|
|
lstConcat (&list_, &aList.list_);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::count - report the number of nodes in a list
|
|
//
|
|
// This routine returns the number of nodes in a specified list.
|
|
//
|
|
// RETURNS:
|
|
// The number of nodes in the list.
|
|
|
|
int count () const
|
|
{
|
|
return lstCount ((LIST *) &list_);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::extract - extract a sublist from list
|
|
//
|
|
// This routine extracts the sublist that starts with <pStart> and ends
|
|
// with <pEnd>. It returns the extracted list.
|
|
//
|
|
// RETURNS: The extracted sublist.
|
|
|
|
LIST extract (NODE *pStart, NODE *pEnd)
|
|
{
|
|
LIST rVal;
|
|
lstExtract (&list_, pStart, pEnd, &rVal);
|
|
return rVal;
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::find - find a node in list
|
|
//
|
|
// This routine returns the node number of a specified node (the
|
|
// first node is 1).
|
|
//
|
|
// RETURNS:
|
|
// The node number, or
|
|
// ERROR if the node is not found.
|
|
|
|
int find (NODE *pNode) const
|
|
{
|
|
return lstFind ((LIST *) &list_, pNode);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::first - find first node in list
|
|
//
|
|
// This routine finds the first node in its list.
|
|
//
|
|
// RETURNS
|
|
// A pointer to the first node in the list, or
|
|
// NULL if the list is empty.
|
|
|
|
NODE * first () const
|
|
{
|
|
return lstFirst ((LIST *) &list_);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::get - delete and return the first node from list
|
|
//
|
|
// This routine gets the first node from its list, deletes the node
|
|
// from the list, and returns a pointer to the node gotten.
|
|
//
|
|
// RETURNS
|
|
// A pointer to the node gotten, or
|
|
// NULL if the list is empty.
|
|
|
|
NODE * get ()
|
|
{
|
|
return lstGet (&list_);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::insert - insert a node in list after a specified node
|
|
//
|
|
// This routine inserts a specified node into the list.
|
|
// The new node is placed following the list node <pPrev>.
|
|
// If <pPrev> is NULL, the node is inserted at the head of the list.
|
|
//
|
|
// RETURNS: N/A
|
|
|
|
void insert (NODE *pPrev, NODE *pNode)
|
|
{
|
|
lstInsert (&list_, pPrev, pNode);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::last - find the last node in list
|
|
//
|
|
// This routine finds the last node in its list.
|
|
//
|
|
// RETURNS
|
|
// A pointer to the last node in the list, or
|
|
// NULL if the list is empty.
|
|
|
|
NODE * last () const
|
|
{
|
|
return lstLast ((LIST *) &list_);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::next - find the next node in list
|
|
//
|
|
// This routine locates the node immediately following a specified node.
|
|
//
|
|
// RETURNS:
|
|
// A pointer to the next node in the list, or
|
|
// NULL if there is no next node.
|
|
|
|
NODE * next (NODE *pNode) const
|
|
{
|
|
return lstNext (pNode);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::nStep - find a list node <nStep> steps away from a specified node
|
|
//
|
|
// This routine locates the node <nStep> steps away in either direction from
|
|
// a specified node. If <nStep> is positive, it steps toward the tail. If
|
|
// <nStep> is negative, it steps toward the head. If the number of steps is
|
|
// out of range, NULL is returned.
|
|
//
|
|
// RETURNS:
|
|
// A pointer to the node <nStep> steps away, or
|
|
// NULL if the node is out of range.
|
|
|
|
NODE * nStep (NODE *pNode, int nStep) const
|
|
{
|
|
return lstNStep (pNode, nStep);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::nth - find the Nth node in a list
|
|
//
|
|
// This routine returns a pointer to the node specified by a number <nodeNum>
|
|
// where the first node in the list is numbered 1.
|
|
// Note that the search is optimized by searching forward from the beginning
|
|
// if the node is closer to the head, and searching back from the end
|
|
// if it is closer to the tail.
|
|
//
|
|
// RETURNS:
|
|
// A pointer to the Nth node, or
|
|
// NULL if there is no Nth node.
|
|
|
|
NODE * nth (int nodeNum) const
|
|
{
|
|
return lstNth ((LIST *) &list_, nodeNum);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::previous - find the previous node in list
|
|
//
|
|
// This routine locates the node immediately preceding the node pointed to
|
|
// by <pNode>.
|
|
//
|
|
// RETURNS:
|
|
// A pointer to the previous node in the list, or
|
|
// NULL if there is no previous node.
|
|
|
|
NODE * previous (NODE *pNode) const
|
|
{
|
|
return lstPrevious (pNode);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWList::remove - delete a specified node from list
|
|
//
|
|
// This routine deletes a specified node from its list.
|
|
//
|
|
// RETURNS: N/A
|
|
|
|
void remove (NODE *pNode)
|
|
{
|
|
lstDelete (&list_, pNode);
|
|
}
|
|
protected:
|
|
LIST list_;
|
|
};
|
|
|
|
#endif /* ifndef vxwLstLib_h */
|