NAME
OTC_BoundedStack -
Implements a LIFO or stack with fixed capacity.
SYNOPSIS
#include <OTC/collctn/bndstack.hh>
template<class T>
class OTC_BoundedStack
{
public:
static os_typespec* get_os_typespec();
~OTC_BoundedStack();
OTC_BoundedStack(u_int theCapacity, T* theMem=0);
OTC_BoundedStack(OTC_BoundedStack<T> const& theStack);
OTC_BoundedStack<T>& operator=(
OTC_BoundedStack<T> const& theStack
);
inline OTC_Boolean isEmpty() const;
inline OTC_Boolean isFull() const;
inline u_int count() const;
inline u_int capacity() const;
inline T& top();
inline T const& top() const;
inline T& peek(u_int theIndex);
inline T const& peek(u_int theIndex) const;
inline void push(T const& theItem);
inline T pop();
inline void clear();
inline void discard(u_int theCount);
};
CLASS TYPE
Concrete
DESCRIPTION
OTC_BoundedStack implements a LIFO or stack with fixed capacity.
Note, that it is the user's responsibility to deal with deletion
of objects held in the stack when it is parameterised over a
pointer type; ie., this class works independently of the
OTC_BaseActions class.
INITIALISATION
OTC_BoundedStack(u_int theCapacity, T* theMem=0);
Creates an empty stack which has
capacity to hold theCapacity items.
If a section of memory is provided
through theMem it will be used,
else memory from the free store will
be allocated. If the memory is provided
by the user, it is the user's responsibility
to delete it.
OTC_BoundedStack(OTC_BoundedStack<T> const& theStack);
Creates a copy of theStack. Space for
this stack will always be allocated from
the free store. If holding pointers, only
the pointers are copied, not what the
pointers point at.
ASSIGNMENT
OTC_BoundedStack<T>& operator=(OTC_BoundedStack<T> const& theStack);
Replaces this stack with a copy of
theStack. The capacity of this stack
will be changed to that of theStack.
Space for this stack will always be
allocated from the free store. If holding
pointers, only the pointers are
copied, not what the pointers point at.
QUERY
inline OTC_Boolean isEmpty() const;
Returns OTCLIB_TRUE if the stack is empty.
inline OTC_Boolean isFull() const;
Returns OTCLIB_TRUE if the stack is full.
inline u_int count() const;
Returns the number of items in the stack.
inline u_int capacity() const;
Returns the maximum number of items
which can be placed in the stack.
inline T& top();
Returns a reference to the top item on
the stack. If the stack is empty, an
exception is raised.
inline T const& top() const;
Returns a reference to the top item on
the stack. If the stack is empty, an
exception is raised.
inline T& peek(u_int theIndex);
Returns a reference to the item
in the stack given by theIndex.
An index of 0 is the top of the
stack. Items below the top of the
stack are numbered from 1 onwards.
If theIndex is outside the bounds
of the stack, an exception is
raised.
inline T const& peek(u_int theIndex) const;
Returns a reference to the item
in the stack given by theIndex.
An index of 0 is the top of the
stack. Items below the top of the
stack are numbered from 1 onwards.
If theIndex is outside the bounds
of the stack, an exception is
raised.
MODIFICATION
inline void push(T const& theItem);
Pushes theItem onto the top of
the stack. If the capacity of the
stack would be exceeded, an exception
is raised.
inline T pop();
Removes the top item off the stack and
returns it. If the stack is empty, an
exception is raised.
inline void clear();
inline void discard(u_int theCount);
Discard the top theCount items in
the stack. If there are not that many
items in the stack, an exception
is raised.
NOTES
Being a bounded stack, for efficiency, an array is used in the
internal implementation instead of a linked list. The consequences
are, that when parameterised over a class type, the class must have
a constructor which accepts no arguments and also be capable of
having assignment performed upon it.
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1992 1993 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED