Click on the banner to return to the Class Reference home page.
©Copyright 1996 Rogue Wave Software
RWCollectionRWCollectable
#include <rw/colclass.h>
typedef RWCollection Collection; // Smalltalk typedef
Class RWCollection is an abstract base class for the Smalltalk-like collection classes. The class contains virtual functions for inserting and retrieving pointers to RWCollectable objects into the collection classes. Virtual functions are also provided for storing and reading the collections to files and streams. Collections that inherit this base class will typically redefine one or more of these functions.
In the documentation below, pure virtual functions are indicated by "= 0" in their declaration. These functions must be defined in derived classes. For these functions the description is intended to be generic -- all inheriting collection classes generally follow the described pattern. Exceptions are noted in the documentation for the particular class.
For many other functions, a suitable definition is provided by RWCollection and a deriving class may not need to redefine the function. Examples are contains() or restoreGuts().
Polymorphic
void operator+=(const RWCollection&); void operator-=(const RWCollection&);
Adds or removes, respectively, each item in the argument to or from self. Using operator+=(somePreSortedCollection) on an RWBinaryTree can cause that tree to become unbalanced; possibly to the point of stack overflow.
virtual ~RWCollection();
Null definition (does nothing).
virtual void apply(RWapplyCollectable ap, void*) = 0;
This function applies the user-supplied function pointed to by ap to each member of the collection. This function should have prototype
void yourApplyFunction(RWCollectable* ctp, void*);
The function yourApplyFunction() can perform any operation on the item at address ctp that does not change the hash value or sorting order of the item. Client data may be passed to this function through the second argument.
RWBag asBag() const; RWSet asSet() const; RWOrdered asOrderedCollection() const; RWBinaryTree asSortedCollection() const;
Allows any collection to be converted to an RWBag, RWSet, RWOrdered, or an RWBinaryTree. Note that the return value is a copy of the data. This can be very expensive for large collections. You should consider using operator+=() to insert each item from this collection into a collection of your choice. Also note that converting a collection containing data which is already sorted to a RWBinaryTree via the asSortedCollection() or asBinaryTree() methods will build a very unbalanced tree.
virtual RWspace binaryStoreSize() const;
Redefined from class RWCollectable.
virtual void clear() = 0;
Removes all objects from the collection. Does not delete the objects themselves.
virtual void clearAndDestroy();
Removes all objects from the collection and deletes them. Takes into account duplicate objects within a collection and only deletes them once. However, it does not take into account objects shared between different collections. Either do not use this function if you will be sharing objects between separate collections, or put all collections that could be sharing objects into one single "super-collection" and call clearAndDestroy() on that.
virtual int compareTo(const RWCollectable* a) const;
Inherited from class RWCollectable.
virtual RWBoolean contains(const RWCollectable* target) const;
Returns TRUE if the collection contains an item where the virtual function find() returns non-nil.
virtual size_t entries() const = 0;
Returns the total number of items in the collection.
virtual RWCollectable* find(const RWCollectable* target) const = 0;
Returns a pointer to the first item in the collection which "matches" the object pointed to by target or nil if no item was found. For most collections, an item "matches" the target if either isEqual() or compareTo() find equivalence, whichever is appropriate for the actual collection type. However, the "identity collections" (i.e., RWIdentitySet and RWIdentityDictionary) look for an item with the same address (i.e., "is identical to").
virtual unsigned hash() const;
Inherited from class RWCollectable.
virtual RWCollectable* insert(RWCollectable* e) = 0;
Adds an item to the collection and returns a pointer to it. If the item is already in the collection, some collections derived from RWCollection return the old instance, others return nil.
virtual RWClassID isA() const;
Redefined from class RWCollectable to return __RWCOLLECTION.
virtual RWBoolean isEmpty() const = 0;
Returns TRUE if the collection is empty, otherwise returns FALSE.
virtual RWBoolean isEqual(const RWCollectable* a) const;
Inherited from class RWCollectable.
virtual size_t occurrencesOf(const RWCollectable* t) const = 0;
Returns the number of items in the collection which are "matches" t. See function find() for a definition of matches.
virtual void restoreGuts(RWFile&);
Redefined to repeatedly call the global operator
RWFile& operator>>(RWFile&, RWCollectable*&);
followed by insert(RWCollectable*) for each item in the collection.
virtual void restoreGuts(RWvistream&);
Redefined to repeatedly call the global operator
RWvistream& operator>>(RWvistream&, RWCollectable*&);
followed by insert(RWCollectable*) for each item in the collection.
RWCollectable* remove(const RWCollectable* target) = 0;
Removes and returns a pointer to the first item in the collection which "matches" the object pointed to by target. Returns nil if no object was found. Does not delete the object.
virtual void removeAndDestroy(const RWCollectable* target);
Removes and deletes the first item in the collection which "matches" the object pointed to by target.
RWCollection* select(RWtestCollectable tst, void* x) const;
Evaluates the function pointed to by tst for each item in the collection. It inserts those items for which the function returns TRUE into a new collection allocated off the heap of the same type as self and returns a pointer to this new collection. Because the new collection is allocated off the heap, you are responsible for deleting it when done. This is not a virtual function.
virtual void saveGuts(RWFile&);
Redefined to call the global operator
RWFile& operator<<(RWFile&, const RWCollectable&);
for each object in the collection.
virtual void saveGuts(RWvostream&);
Redefined to call the global operator
RWvostream& operator<<(RWvostream&, const RWCollectable&);
for each object in the collection.
