RWCollection(3C++) RWCollection(3C++)
NameRWCollection - Rogue Wave library class
Synopsis
#include <rw/colclass.h>
typedef RWCollection Collection; // Smalltalk typedef
Description
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().
Persistence
Polymorphic
Public Member Operators
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.
Public Member Functions
virtual
~RWCollection();
Null definition (does nothing).
Page 1
RWCollection(3C++) RWCollection(3C++)
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();
Page 2
RWCollection(3C++) RWCollection(3C++)
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.
Page 3
RWCollection(3C++) RWCollection(3C++)
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.
Page 4
RWCollection(3C++) RWCollection(3C++)
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&);
Page 5
RWCollection(3C++) RWCollection(3C++)
for each object in the collection.
Page 6
