RWGSlist(3C++)

Name
     RWGSlist(type) - Rogue Wave library class

Synopsis
              #include <rw/gslist.h>



              declare(RWGSlist, type)
          RWGSlist(type) a ;




Description
     Class RWGSlist(type) represents a group of ordered elements of type type,
     not accessible by an external key.  Duplicates are allowed.  This class
     is implemented as a singly-linked list.  Objects of type RWGSlist(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
              RWGSlist(type)();


     Construct an empty collection.

              RWGSlist(type)(type* a);


     Construct a collection with one entry a.

              RWGSlist(type)(const RWGSlist(type)& a);


     Copy constructor.  A shallow copy of a is made.

Assignment Operator
              void
          operator=(const RWGSlist(type)&);


     Assignment operator.  A shallow copy of a is made.

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


     Adds an item to the end of the collection and returns it.  Returns nil if
     the insertion was unsuccessful.

              void
          apply(void (*ap)(type*, void*), void* );


     Visits all the items in the collection in order, from first to last,
     calling the user-provided function pointed to by ap for each item.  This
     function should have prototype:

              void yourApplyFunction(type* c, void*);





     and can perform any operation on the object at address c.  The last
     argument is useful for passing data to the apply function.

              type*&
          at(size_t i);
          const type*
          at(size_t i) const;


     Returns a pointer to the ith item in the collection.  The first variant
     can be used as an lvalue, the second cannot.  The index i must be between
     zero and the number of items in the collection less one, or an exception
     of type TOOL_INDEX will be thrown.
              void
          clear();


     Removes all items in the collection.

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


     Returns TRUE if the collection 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 collection contains an item with the address e.

              size_t
          entries() const;


     Returns the number of items in the collection.

              type*
          find(yourTester t, const void* d) const;


     Returns the first item in the collection for which the user-provided
     function pointed to by t finds a match with d, or nil if no item is
     found.

              type*
          findReference(const type* e) const;


     Returns the first item in the collection with the address e, or nil if no
     item is found.

              type*
          first() const;


     Returns the first item of the collection.

              type*
          get();


     Returns and removes the first item of the collection.

              type*
          insert(type* e);


     Adds an item to the end of the collection and returns it.  Returns nil if
     the insertion was unsuccessful.

              void
          insertAt(size_t indx, type* e);


     Adds a new item to the collection at position indx.  The item previously
     at position i is moved to i+1, etc.  The index indx must be between 0 and
     the number of items in the collection, or an exception of type TOOL_INDEX
     will be thrown.

              RWBoolean
          isEmpty() const;


     Returns TRUE if the collection is empty, otherwise FALSE.

              type*
          last() const;


     Returns the last item of the collection.

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


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

              type*
          prepend(const type* a);


     Adds an item to the beginning of the collection and returns it.  Returns
     nil if the insertion was unsuccessful.

              type*
          remove(yourTester t, const void* d);

     Removes and returns the first item from the collection for which the
     user-provided function pointed to by t finds a match with d, or returns
     nil if no item is found.

              type*
          removeReference(const type* e);


     Removes and returns the first item from the collection with the address
     e, or returns nil if no item is found.