RWGDlist(3C++)

Name
     RWGDlist(type) - Rogue Wave library class

Synopsis
              #include <rw/gdlist.h>



              declare(RWGDlist, type)
          RWGDlist(type) a;




Description
     Class RWGDlist(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 doubly-linked list.  Objects of type RWGDlist(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

Example
              #include <rw/gdlist.h>
          #include <rw/rstream.h>
          declare(RWGDlist,int)    /* Declare a list of ints */
          main()  {
            RWGDlist(int) list;    // Define a list of ints
            int *ip;
            list.insert(new int(5));   // Insert some ints
            list.insert(new int(7));
            list.insert(new int(1));
            list.prepend(new int(11));
            RWGDlistIterator(int) next(list);
            while(ip = next() )
              cout << *ip << endl;   // Print out the members
            while(!list.isEmpty())
              delete list.get();     // Remove & delete list items
            return 0;
          }


     Program output:

                   11
               5
               7
               1



Public Constructors
              RWGDlist(type)();


     Construct an empty collection.

              RWGDlist(type)(type* a);


     Construct a collection with one entry a.

              RWGDlist(type)(const RWGDlist(type)& a);


     Copy constructor.  A shallow copy of a is made.

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


     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.  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(type* a);


     Adds an item to the beginning of the collection.  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.