RWGDlist(3C++) RWGDlist(3C++)
NameRWGDlist(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
Page 1
RWGDlist(3C++) RWGDlist(3C++)
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 ConstructorsRWGDlist(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
Page 2
RWGDlist(3C++) RWGDlist(3C++)
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;
Page 3
RWGDlist(3C++) RWGDlist(3C++)
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.
Page 4
RWGDlist(3C++) RWGDlist(3C++)
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.
Page 5