gxListB Linked List Base Class
Overview
Memory Ownership
Thread Safety
Data Members
Example Programs
Functions
Overview
The gxListNodeB and gxListB classes make up a non-template doubly linked list. Each gxListNodeB node holds a void pointer to its data plus pointers to the next and previous nodes. The gxListB class keeps a pointer to the first node (head) and the last node (tail).
You can use gxListB directly by casting each data item to a void pointer. You can also use it as a base class to build a list for one data type. The gxConfig class is built this way. The virtual Add(), AllocNode(), and FreeNode() functions let a derived class change how nodes are created and freed.
The list can be used as a general list, a stack (Push() and Pop()), or a queue (Insert() and Extract()). Copying and assignment are not allowed.
Include file: gxlistb.h. Source file: gxlistb.cpp.
Memory Ownership
The list owns its nodes but does not own the data the nodes point to. The add functions store the data pointer you pass. They do not copy the data. The remove functions delete the node and return the data pointer to you. You must free that data yourself.
ClearList(), Clear(), and the class destructor delete every node but never delete the data. If the data was allocated on the heap, free it before you clear the list or let the list go out of scope. Otherwise the data is leaked.
DestroyList() deletes the data as well as the nodes. It frees each data pointer with delete (char *). This is only correct for data allocated as a single char with new. It does not call the destructor of any class object. It does not match memory allocated with new[] or malloc(). DestroyArrayList() (added 10/24/2026 in version 6.0) frees each data pointer with delete[] (char *), for strings and other char arrays allocated with new[]. For any other kind of data, remove each item and free it yourself.
MakeEmpty() and Release() reset the head and tail pointers without deleting anything. Use Release() when another object still uses the same nodes. If no other object holds the nodes, these calls leak them.
Thread Safety
The gxListB class does no locking. If more than one thread uses the same list, the application must protect every call with its own mutex.
Data Members
The gxListNodeB members are public. The gxListB head and tail pointers are protected so derived classes can use them.
class gxListNodeB
{
public:
void *data; // Pointer to this node data
gxListNodeB *next; // Pointer to the next node in the list
gxListNodeB *prev; // Pointer to the previous node in the list
};
class gxListB
{
protected:
gxListNodeB *head; // First node in the list
gxListNodeB *tail; // Last node in the list
};
Example Programs
No example program uses gxListB directly. The examples_general/config_class program uses the gxConfig class, which is derived from gxListB.
Functions
gxListB::Add()
gxListB::AddAfter()
gxListB::AddBefore()
gxListB::AddToBack()
gxListB::AddToFront()
gxListB::AllocNode()
gxListB::Clear()
gxListB::ClearList()
gxListB::DestroyArrayList()
gxListB::DestroyList()
gxListB::DetachNode()
gxListB::Extract()
gxListB::FreeNode()
gxListB::GetHead()
gxListB::GetHead() const
gxListB::GetTail()
gxListB::GetTail() const
gxListB::Insert()
gxListB::InsertAfter()
gxListB::InsertAtHead()
gxListB::InsertAtTail()
gxListB::InsertBefore()
gxListB::IsEmpty()
gxListB::IsEmpty() const
gxListB::MakeEmpty()
gxListB::MoveAfter()
gxListB::MoveBefore()
gxListB::MoveToBack()
gxListB::MoveToFront()
gxListB::Pop()
gxListB::Push()
gxListB::Release()
gxListB::Remove()
gxListB::RemoveHead()
gxListB::RemoveTail()
gxListNodeB::gxListNodeB()
gxListNodeB::~gxListNodeB()
gxListB::gxListB()
gxListB::gxListB(const gxListB &ob)
gxListB::operator=()
gxListB::~gxListB()
virtual gxListNodeB *gxListB::Add(void *v)Public member function used to add a new node to the back of the list. The node stores the pointer "v". The data is not copied. Returns a pointer to the new node, or a null value if AllocNode() returns null. Derived classes can override this function. NOTE: 10/24/2026: gxConfig overrides it so that untyped data cannot be added to a configuration list. Through a gxListB pointer or reference, Add() on a gxConfig object returns a null value.
gxListNodeB *gxListB::AddAfter(gxListNodeB *pos, void *v)Public member function used to add a new node holding "v" after the node "pos". The "pos" node must be in this list. If the list is empty, "pos" is ignored and the new node becomes the only node. Returns a pointer to the new node, or a null value if the node could not be allocated.
gxListNodeB *gxListB::AddBefore(gxListNodeB *pos, void *v)Public member function used to add a new node holding "v" before the node "pos". The "pos" node must be in this list. If the list is empty, "pos" is ignored and the new node becomes the only node. Returns a pointer to the new node, or a null value if the node could not be allocated.
gxListNodeB *gxListB::AddToBack(void *v)Public member function used to add a new node holding "v" to the back (tail) of the list. Returns a pointer to the new node, or a null value if the node could not be allocated.
gxListNodeB *gxListB::AddToFront(void *v)Public member function used to add a new node holding "v" to the front (head) of the list. Returns a pointer to the new node, or a null value if the node could not be allocated.
virtual gxListNodeB *gxListB::AllocNode(void *v)Protected member function used by all the add functions to create a node. The default version allocates a gxListNodeB with new and sets its data pointer to "v". It assumes "v" already points to valid memory. Derived classes can override this function to use their own node type.
void gxListB::Clear()Public member function that calls ClearList().
void gxListB::ClearList()Public member function used to remove and delete every node in the list, starting at the tail. The node data is not deleted. Free the data first if the list holds heap pointers. The class destructor calls this function.
void gxListB::DestroyArrayList()Public member function used to remove every node and delete each node's data with delete[] (char *). Use it for strings and other char arrays allocated with new[]. NOTE: 10/24/2026: Added in version 6.0. See Memory Ownership.
void gxListB::DestroyList()Public member function used to remove every node and delete each node's data. Each non-null data pointer is freed with delete (char *). This does not call class destructors and does not match new[] or malloc(). See Memory Ownership.
void gxListB::DetachNode(gxListNodeB *n)Public member function used to unlink the node "n" from the list without deleting it. Nothing happens if the list is empty or "n" is null. The next and prev pointers of "n" are set to null. NOTE: "n" must be a node in this list. 10/14/2026: Fixed two problems. If the list held only one node, it was emptied no matter which node was passed in; now nothing happens unless "n" is that node. The links of the detached node used to keep pointing into the list.
void *gxListB::Extract()Queue function used to remove the node at the head of the list. Use it with Insert() for first-in, first-out order. Returns the node's data pointer for the application to free, or a null value if the list is empty.
virtual void *gxListB::FreeNode(gxListNodeB *n)Protected member function used by the remove functions to delete a node. The node must already be detached. The node's data is not deleted. Returns the node's data pointer, or a null value if "n" is null. Derived classes can override this function.
gxListNodeB *gxListB::GetHead()Public member function that returns a pointer to the first node in the list, or a null value if the list is empty.
gxListNodeB *gxListB::GetHead() constConst version of GetHead(). Returns a non-const pointer to the first node in the list, or a null value if the list is empty.
gxListNodeB *gxListB::GetTail()Public member function that returns a pointer to the last node in the list, or a null value if the list is empty.
gxListNodeB *gxListB::GetTail() constConst version of GetTail(). Returns a non-const pointer to the last node in the list, or a null value if the list is empty.
gxListNodeB *gxListB::Insert(void *v)Queue function used to add a new node holding "v" to the back of the list. Returns a pointer to the new node, or a null value if the node could not be allocated.
void gxListB::InsertAfter(gxListNodeB *pos, gxListNodeB *n)Public member function used to link a new or detached node "n" after the node "pos". If the list is empty, "pos" is ignored and "n" becomes the only node with null next and prev pointers. Otherwise "pos" must be a non-null node in this list. NOTE: 10/14/2026: Fixed. A node inserted into an empty list used to keep its old next and prev pointers.
void gxListB::InsertAtHead(gxListNodeB *n)Public member function used to link a new or detached node "n" at the head of the list.
void gxListB::InsertAtTail(gxListNodeB *n)Public member function used to link a new or detached node "n" at the tail of the list.
void gxListB::InsertBefore(gxListNodeB *pos, gxListNodeB *n)Public member function used to link a new or detached node "n" before the node "pos". If the list is empty, "pos" is ignored and "n" becomes the only node with null next and prev pointers. Otherwise "pos" must be a non-null node in this list. NOTE: 10/14/2026: Fixed. A node inserted into an empty list used to keep its old next and prev pointers.
int gxListB::IsEmpty()Public member function that returns true if the list has no nodes.
int gxListB::IsEmpty() constConst version of IsEmpty(). Returns true if the list has no nodes.
void gxListB::MakeEmpty()Public member function used to set the head and tail pointers to null. No nodes or data are deleted. Call it only after all the nodes have been removed, or when another object owns the nodes.
void gxListB::MoveAfter(gxListNodeB *pos, gxListNodeB *n)Public member function used to move the existing node "n" so it follows the node "pos". Both nodes must be in this list. Nothing happens if "pos" and "n" are the same node. NOTE: 10/14/2026: Fixed. Moving a node next to itself used to corrupt the links.
void gxListB::MoveBefore(gxListNodeB *pos, gxListNodeB *n)Public member function used to move the existing node "n" so it comes before the node "pos". Both nodes must be in this list. Nothing happens if "pos" and "n" are the same node. NOTE: 10/14/2026: Fixed. Moving a node next to itself used to corrupt the links.
void gxListB::MoveToBack(gxListNodeB *n)Public member function used to move the node "n" to the back of the list. Nothing happens if "n" is already the tail.
void gxListB::MoveToFront(gxListNodeB *n)Public member function used to move the node "n" to the front of the list. Nothing happens if "n" is already the head.
void *gxListB::Pop()Stack function used to remove the node at the head of the list. Use it with Push() for last-in, first-out order. Returns the node's data pointer for the application to free, or a null value if the list is empty.
gxListNodeB *gxListB::Push(void *v)Stack function used to add a new node holding "v" to the head of the list. Returns a pointer to the new node, or a null value if the node could not be allocated.
void gxListB::Release()Synchronization function used to let go of the list without clearing it. It sets the head and tail pointers to null and deletes nothing. Use it when more than one object refers to the same nodes. After the call, this object can be deleted without affecting the other objects. The nodes stay in memory until the last owner clears them.
void *gxListB::Remove(gxListNodeB *n)Public member function used to unlink and delete the node "n". Returns the node's data pointer for the application to free. Returns a null value if the list is empty or "n" is null. NOTE: "n" must be a node in this list, or a node that was detached with DetachNode(). A detached node is deleted too, which is how a detached node is freed.
void *gxListB::RemoveHead()Public member function used to remove and delete the first node in the list. Returns the node's data pointer for the application to free, or a null value if the list is empty.
void *gxListB::RemoveTail()Public member function used to remove and delete the last node in the list. Returns the node's data pointer for the application to free, or a null value if the list is empty.
gxListNodeB::gxListNodeB()Default node constructor. Sets the data, next, and prev pointers to null.
virtual gxListNodeB::~gxListNodeB()Virtual node destructor. It does nothing. It does not delete the node data.
gxListB::gxListB()Default list constructor. Creates an empty list.
gxListB::gxListB(const gxListB &ob)Private copy constructor used to disallow copying.
void gxListB::operator=(const gxListB &ob)Private assignment operator used to disallow assignment.
virtual gxListB::~gxListB()Virtual class destructor. Calls ClearList() to delete all the nodes. The node data is not deleted. Call Release() first if other objects still use the nodes.