RWGQueue(3C++)

Name
     RWGQueue(type) - Rogue Wave library class

Synopsis
              #include <rw/gqueue.h>



              declare(RWGQueue, type)
          RWGQueue(type) a ;




Description
     Class RWGQueue(type) represents a group of ordered elements, not
     accessible by an external key.  A RWGQueue(type) is a first in, first out
     (FIFO) sequential list for which insertions are made at one end (the
     "tail"), but all removals are made at the other (the "head").  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 RWGQueue(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
              RWGQueue(type)();


     Construct an empty queue.

              RWGQueue(type)(type* a);


     Construct a queue with one entry a.

              RWGQueue(type)(const RWGQueue(type)& q);


     Copy constructor.  A shallow copy of q is made.

Assignment Operator
              void
          operator=(const RWGQueue(type)& q);


     Assignment operator.  A shallow copy of q is made.

Public Member Functions
              type*
          append(type* a);


     Adds a to the end of the queue and returns it.  Returns nil if the
     insertion was unsuccessful.

              void
          clear();


     Removes all items from the queue.

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


     Returns TRUE if the queue 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 queue contains an item with the address e.
              size_t
          entries() const;


     Returns the number of items in the queue.

              type*
          first() const;


     Returns the first item in the queue, or nil if the queue is empty.

              type*
          get();


     Returns and removes the first item in the queue.  Returns nil if the
     queue is empty.

              RWBoolean
          isEmpty() const;


     Returns TRUE if the queue is empty, otherwise FALSE.

              type*
          insert(type* a);


     Calls append(type*) with a as the argument.

              type*
          last();


     Returns the last (most recently inserted) item in the queue, or nil if
     the queue is empty.

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


     Returns the number of items in the queue 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 queue with the address e.