Stack containers maintain an ordered collection of data that's retrieved in the reverse of the order in which the data was entered into the stack (that is, the last item added to the stack is the first to be removed). The stack class is implemented as a templated class, allowing the stacking of any data type.
A second template parameter specifies the storage class used to implement the stack; the WCValSList, WCIsvSList and WCPtrSList classes are appropriate choices.
wcstack.h
The WCStack<Type,FType> class is a templated class used to create objects that maintain data in a stack.
In the description of each member function, the text Type is used to indicate the template parameter defining the type of the elements stored in the stack. The text FType is used to indicate the template parameter defining the storage class used to maintain the stack.
For example, to create a stack of integers, the WCStack<int,WCValSList<int> > class can be used. The WCStack<int *,WCPtrSList<int> > class creates a stack of pointers to integers. To create an intrusive stack of objects of type isv_link (derived from the WCSLink class), the WCStack< isv_link *,WCIsvSList< isv_link > > class can be used.
The WCExcept class is a base class of the WCStack<Type,FType> class, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCStack<Type,FType> object. No exceptions are enabled unless they are set by the exceptions() member function.
Type must provide any constructors and/or operators required by the FType class.
The following member functions are declared in the public interface:
WCStack(); WCStack( void *(*)( size_t ), void (*)( void *, size_t ) ); ~WCStack(); void clear(); int entries() const; int isEmpty() const; Type pop(); int push( const Type & ); Type top() const;
#include <wcstack.h>
#include <iostream.h>
void main() {
WCStack<int,WCValSList<int> > stack;
stack.push( 7 );
stack.push( 8 );
stack.push( 9 );
stack.push( 10 );
cout << "\nNumber of stack entries: "
<< stack.entries() << "\n";
cout << "Top entry = [" << stack.top() << "]\n";
while( !stack.isEmpty() ) {
cout << stack.pop() << "\n";
};
cout.flush();
}
create a WCStack<Type,FType> object
#include <wcstack.h>
public:
WCStack();
WCStack( void *(*allocator)( size_t ),
void (*deallocator)( void *, size_t ) );
There are two forms of the public WCStack<Type,FType> constructor:
If FType is either the WCValSList or WCPtrSList class, then the allocator function is registered to perform all memory allocations of the stack elements, and the deallocator function to perform all freeing of the stack elements' memory. The allocator and deallocator functions are ignored if FType is the WCIsvSList class.
These functions provide the ability to control how the allocation and freeing of memory is performed, allowing for more efficient memory handling than the general purpose global operator new() and operator delete() can provide. Memory management optimizations may potentially be made through the allocator and deallocator functions, but aren't recommended before you understand memory management, and determine that it's worthwhile.
The allocator function shall return a pointer to allocated memory of size at least the argument, or zero(0) if the allocation can't be performed. Initialization of the memory returned is performed by the WCStack<Type,FType> class.
The WCStack<Type,FType> class calls the deallocator function only on memory allocated by the allocator function. The deallocator shall free the memory pointed to by the first argument that is of size given by the second argument. The size passed to the deallocator function is guaranteed to be the same size passed to the allocator function when the memory was allocated.
The allocator and deallocator functions may assume that for a list object instance, the allocator is always called with the same first argument (the size of the memory to be allocated). If FType is the WCValSList<Type> class, then the WCValSListItemSize(Type) macro returns the size of the elements that are allocated by the allocator function. Similarly, the WCPtrSListItemSize(Type) macro returns the size of WCPtrSList<Type> elements.
The FType storage class constructor performs the initialization of the stack.
The public WCStack<Type,FType> constructor creates an initialized WCStack<Type,FType> object.
WCStack<Type,FType>::~WCStack()
destroy a WCStack<Type,FType> object
#include <wcstack.h> public: virtual ~WCStack();
The public WCStack<Type,FType> destructor destroys the WCStack<Type,FType> object. The FType storage class destructor performs the destruction.
The call to this destructor is inserted implicitly by the compiler at the point where the WCStack<Type,FType> object goes out of scope.
If the not_empty exception is enabled, the exception is thrown if the stack isn't empty of stack elements.
The WCStack<Type,FType> object is destroyed.
WCExcept::not_empty, WCStack<Type,FType>::WCStack(), WCStack<Type,FType>::clear()
clear the stack object
#include <wcstack.h> public: void clear();
The clear() public member function is used to clear the stack object and set it to the state it was in just after its initial construction. The stack object isn't destroyed and re-created by this operator, so the object destructor isn't invoked.
The stack elements aren't cleared by the stack class. However, the class used to maintain the stack, FType, may clear the items as part of its clear member function. If it doesn't clear the items, any stack items still in the list are lost unless pointed to by some pointer object in the program code.
The clear() public member function resets the stack object to the state it was in immediately after its initial construction.
WCStack<Type,FType>::~WCStack(), WCStack<Type,FType>::isEmpty()
count the elements in the stack
#include <wcstack.h> public: int entries() const;
The entries() public member function is used to determine the number of stack elements contained in the stack object.
The number of elements on the stack is returned.
WCStack<Type,FType>::isEmpty()
determine whether or not the stack is empty
#include <wcstack.h> public: int isEmpty() const;
The isEmpty() public member function is used to determine if a stack object has any stack elements in it.
A TRUE value (non-zero) is returned if the stack object doesn't have any stack elements in it. A FALSE (zero) result is returned if the stack contains at least one element.
WCStack<Type,FType>::entries()
return the top element of the stack
#include <wcstack.h> public: Type pop();
The pop() public member function returns the top stack element from the stack object (that is, the last element to be pushed onto the stack). This element is also removed from the stack.
If the stack is empty, one of two exceptions can be thrown:
The top stack element is removed and returned. The return value is determined by the get() member function of the FType class if there are no elements on the stack.
WCExcept::empty_container, WCExcept::index_range, FType::get(), WCStack<Type,FType>::isEmpty(), WCStack<Type,FType>::push(), WCStack<Type,FType>::top()
add an element to the top of the stack
#include <wcstack.h> public: int push( const Type & );
The push() public member function is used to push the data onto the top of the stack. It will be the first element on the stack to be popped.
If the push fails, the out_of_memory exception is thrown, if enabled, and the stack remains unchanged.
The stack element is pushed onto the top of the stack. A TRUE value (non-zero) is returned if the push is successful. A FALSE (zero) result is returned if the push fails.
WCExcept::out_of_memory, WCStack<Type,FType>::pop()
return the top element of the stack, without removing it
#include <wcstack.h> public: Type top() const;
The top() public member function returns the top stack element from the stack object (that is, the last element pushed onto the stack). The element isn't removed from the stack.
If the stack is empty, one of two exceptions can be thrown:
The top stack element is returned. The return value is determined by the find() member function of the FType class if there are no elements on the stack.
WCExcept::empty_container, WCExcept::index_range, FType::find(), WCStack<Type,FType>::isEmpty(), WCStack<Type,FType>::pop()