#include <rw/gslist.h> declare(RWGSlist, type) RWGSlist(type) a ;
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.
None
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.
void operator=(const RWGSlist(type)&);
Assignment operator. A shallow copy of a is made.
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.