RWGStack(3C++)

Name
     RWGStack(type) - Rogue Wave library class

Synopsis
              #include <rw/gstack.h>



              declare(RWGStack,type)
          RWGStack(type) a ;




Description
     Class RWGStack(type) represents a group of ordered elements, not
     accessible by an external key.  A RWGStack(type) is a last in, first out
     (LIFO) sequential list for which insertions and removals are made at the
     beginning of the list.  Hence, the ordering is determined externally by
     the ordering of the insertions.  Duplicates are allowed. This class is
     implemented as a singly-linked list.  Objects of type RWGStack(type) are
     declared with macros defined in the standard C++ header file <generic.h>.
     In order to find a particular item within the collection, a user-provided
     global "tester" function is required to test for a "match," definable in
     any consistent way.  This function should have prototype:

              RWBoolean yourTesterFunction(const type* c, const void* d);





     The argument c is a candidate within the collection to be tested for a
     match.  The argument d is for your convenience and will be passed to
     yourTesterFunction().  The function should return TRUE if a "match" is
     found between c and d.  In order to simplify the documentation below, an
     imaginary typedef

              typedef RWBoolean (*yourTester)(const type*, const void*);





     has been used for this tester function.

Persistence
     None

Public Constructors
              RWGStack(type)();


     Constructs an empty stack.

              RWGStack(type)(type* a);


     Constructs a stack with one entry a.

              RWGStack(type)(const RWGStack(type)& a);


     Copy constructor.  A shallow copy of a is made.

Assignment Operator
              void
          operator=(const RWGStack(type)& a);


     Assignment operator.  A shallow copy of a is made.

Public Member Functions
              void
          clear();


     Removes all items from the stack.

              RWBoolean
          contains(yourTester t, const void* d) const;


     Returns TRUE if the stack contains an item for which the user-defined
     function pointed to by t finds a match with d.

              RWBoolean
          containsReference(const type* e) const;


     Returns TRUE if the stack contains an item with the address e.

              size_t
          entries() const;


     Returns the number of items in the stack.

              RWBoolean
          isEmpty() const;
     Returns TRUE if the stack is empty, otherwise FALSE.

              size_t
          occurrencesOf(yourTester t, const void* d) const;


     Returns the number of items in the stack for which the user-provided
     function pointed to by t finds a match with d.

              size_t
          occurrencesOfReference(const type* e) const;


     Returns the number of items in the stack with the address e.

              type*
          pop();


     Removes and returns the item at the top of the stack, or returns nil if
     the stack is empty.

              void
          push(type* a);


     Adds an item to the top of the stack.

              type*
          top() const;


     Returns the item at the top of the stack or nil if the stack is empty.