RWGSlist(3C++) RWGSlist(3C++)
NameRWGSlist(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 ConstructorsRWGSlist(type)();
Construct an empty collection.
Page 1
RWGSlist(3C++) RWGSlist(3C++)
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.
Page 2
RWGSlist(3C++) RWGSlist(3C++)
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.
Page 3
RWGSlist(3C++) RWGSlist(3C++)
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);
Page 4
RWGSlist(3C++) RWGSlist(3C++)
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
