RWCollection Class Reference

Contains virtual functions for inserting and retrieving pointers to RWCollectable objects into the collection classes. More...

#include <rw/colclass.h>

Inheritance diagram for RWCollection:

Public Member Functions
virtual	~RWCollection ()
virtual void	apply (RWapplyCollectable ap, void *vp)=0
RWBag	asBag () const
RWBinaryTree	asBinaryTree () const
RWOrdered	asOrderedCollection () const
RWSet	asSet () const
RWBinaryTree	asSortedCollection () const
virtual RWspace	binaryStoreSize () const
virtual void	clear ()=0
virtual void	clearAndDestroy ()
virtual bool	contains (const RWCollectable *target) const
virtual size_t	entries () const =0
virtual RWCollectable *	find (const RWCollectable *target) const =0
virtual RWCollectable *	insert (RWCollectable *c)=0
virtual RWClassID	isA () const
virtual bool	isEmpty () const =0
virtual RWConstIterator *	newConstIterator () const =0
virtual RWIterator *	newIterator ()=0
virtual size_t	occurrencesOf (const RWCollectable *t) const =0
void	operator+= (const RWCollection &c)
void	operator-= (const RWCollection &c)
virtual RWCollectable *	remove (const RWCollectable *target)=0
virtual void	removeAndDestroy (const RWCollectable *target)
virtual void	restoreGuts (RWvistream &)
virtual void	restoreGuts (RWFile &)
virtual void	saveGuts (RWvostream &) const
virtual void	saveGuts (RWFile &) const
RWCollection *	select (RWtestCollectable tst, void *vp) const
Public Member Functions inherited from RWCollectable
virtual	~RWCollectable ()
virtual int	compareTo (const RWCollectable *) const
virtual RWCollectable *	copy () const
virtual unsigned	hash () const
virtual bool	isEqual (const RWCollectable *t) const
virtual RWCollectable *	newSpecies () const
RWspace	recursiveStoreSize () const
RWStringID	stringID () const

Static Public Attributes
static size_t	DEFAULT_CAPACITY

Related Functions
(Note that these are not member functions.)
typedef void(*	RWapplyCollectable) (RWCollectable *, void *)
typedef bool(*	RWtestCollectable) (const RWCollectable *, const void *)
typedef bool(*	RWtestCollectablePair) (const RWCollectable *, const RWCollectable *, const void *)

Additional Inherited Members
Static Public Member Functions inherited from RWCollectable
static RWClassID	classID (const RWStringID &name)
static RWClassID	classIsA ()
static bool	isAtom (RWClassID id)
static RWspace	nilStoreSize ()

Detailed 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 typically redefine one or more of these functions.

Several of the methods of this class are abstract. 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().

Synopsis

#include <rw/colclass.h>
typedef RWCollection Collection;   // Smalltalk typedef

Persistence

Polymorphic

Constructor & Destructor Documentation

virtual RWCollection::~RWCollection ( )

virtual

Empty destructor.

Member Function Documentation

virtual void RWCollection::apply ( RWapplyCollectable  ap, void *  vp  )

pure virtual

This function applies the user-supplied function pointed to by ap to each member of the collection. This function should have the following prototype:

void yourApplyFunction(RWCollectable* ctp, void* vp);

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 vp.

Implemented in RWHashTable, RWBTree, RWDlistCollectables, RWBinaryTree, RWSlistCollectables, RWBag, RWOrdered, and RWSequenceable.

RWBag RWCollection::asBag

(

)

const

Allows any collection to be converted to an RWBag. 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.

Note

If self contains pairs of keys and values, the result of this call is a container holding objects of type RWCollectableAssociation.

RWBinaryTree RWCollection::asBinaryTree

(

)

const

Allows any collection to be converted to an RWBinaryTree. 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.

Note

Converting a collection containing data which is already sorted to an RWBinaryTree with this method may build a very unbalanced tree.

If self contains pairs of keys and values, the result of this call is a container holding objects of type RWCollectableAssociation.

RWOrdered RWCollection::asOrderedCollection

(

)

const

Allows any collection to be converted to an RWOrdered. 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.

Note

If self contains pairs of keys and values, the result of this call is a container holding objects of type RWCollectableAssociation.

RWSet RWCollection::asSet

(

)

const

Allows any collection to be converted to an RWSet. 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.

Note

If self contains pairs of keys and values, the result of this call is a container holding objects of type RWCollectableAssociation.

RWBinaryTree RWCollection::asSortedCollection

(

)

const

Allows any collection to be converted to an RWBinaryTree. 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.

Note

Converting a collection containing data which is already sorted to an RWBinaryTree with this method may build a very unbalanced tree.

If self contains pairs of keys and values, the result of this call is a container holding objects of type RWCollectableAssociation.

virtual RWspace RWCollection::binaryStoreSize ( ) const

virtual

Returns the number of bytes used by the virtual function saveGuts(RWFile&) to store an object. Typically, this involves adding up the space required to store all primitives, plus the results of calling recursiveStoreSize() for all objects inheriting from RWCollectable. See the Essential Tools Module User's Guide for details.

Reimplemented from RWCollectable.

virtual void RWCollection::clear ( )

pure virtual

Removes all objects from the collection. Does not delete the objects themselves.

Implemented in RWHashTable, RWDlistCollectables, RWSlistCollectables, RWBTree, RWBinaryTree, RWHashDictionary, RWBag, RWOrdered, RWBTreeDictionary, and RWSequenceable.

virtual void RWCollection::clearAndDestroy ( )

virtual

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 are sharing objects between separate collections, or put all collections that could be sharing objects into one single "super-collection" and call clearAndDestroy() on that.

Reimplemented in RWSet, RWHashDictionary, RWBag, and RWBTreeDictionary.

virtual bool RWCollection::contains ( const RWCollectable *  target ) const

virtual

Returns true if the collection contains an item where the virtual function find() returns non-nil.

Reimplemented in RWDlistCollectables, and RWSlistCollectables.

virtual size_t RWCollection::entries ( ) const

pure virtual

Returns the total number of items in the collection.

Implemented in RWHashTable, RWDlistCollectables, RWSlistCollectables, RWBTree, RWBinaryTree, RWBag, RWOrdered, and RWSequenceable.

virtual RWCollectable* RWCollection::find ( const RWCollectable *  target ) const

pure virtual

Returns a pointer to the first item in the collection which "matches" the object pointed to by target or rwnil 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").

Implemented in RWHashTable, RWDlistCollectables, RWSlistCollectables, RWBTree, RWBag, RWBinaryTree, RWHashDictionary, RWOrdered, RWBTreeDictionary, RWIdentitySet, and RWSequenceable.

virtual RWCollectable* RWCollection::insert ( RWCollectable *  c )

pure virtual

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 rwnil.

Note

If self is a collection of key-value pairs (e.g. RWHashDictionary), this function throws std::bad_cast if c does not inherit from RWCollectableAssociation. If the collection does not contain an association with a key that "matches" the key of c, then a copy of the association is inserted and that association's key is returned. Otherwise, the insert fails by returning either rwnil or a pointer to the existing association's key.

Implemented in RWHashTable, RWDlistCollectables, RWSlistCollectables, RWSortedVector, RWBTree, RWHashDictionary, RWBTreeDictionary, RWSet, RWBinaryTree, RWBag, RWOrdered, RWSlistCollectablesStack, RWIdentitySet, and RWSequenceable.

virtual RWClassID RWCollection::isA ( ) const

inlinevirtual

Returns __RWCOLLECTION

Reimplemented from RWCollectable.

Reimplemented in RWHashTable, RWSortedVector, RWBTree, RWBag, RWSet, RWSlistCollectablesStack, RWSlistCollectables, RWOrdered, RWBinaryTree, RWSlistCollectablesQueue, RWDlistCollectables, RWIdentitySet, RWBTreeDictionary, RWIdentityDictionary, and RWHashDictionary.

virtual bool RWCollection::isEmpty ( ) const

pure virtual

Returns true if the collection is empty, otherwise returns false.

Implemented in RWDlistCollectables, RWHashTable, RWSlistCollectables, RWBTree, RWBinaryTree, RWBag, RWOrdered, and RWSequenceable.

virtual RWConstIterator* RWCollection::newConstIterator ( ) const

pure virtual

Returns a const pointer to a dynamically allocated iterator for the collection.

Implemented in RWDlistCollectables, RWSlistCollectables, RWHashDictionary, RWHashTable, RWBTree, RWBinaryTree, RWBag, RWOrdered, and RWSet.

virtual RWIterator* RWCollection::newIterator ( )

pure virtual

Returns a dynamically allocated iterator for the collection.

Implemented in RWDlistCollectables, RWSlistCollectables, RWHashDictionary, RWHashTable, RWBTree, RWBinaryTree, RWBag, RWOrdered, and RWSet.

virtual size_t RWCollection::occurrencesOf ( const RWCollectable *  t ) const

pure virtual

Returns the number of items in the collection which are "matches" for t. See function find() for a definition of matches.

Implemented in RWDlistCollectables, RWSlistCollectables, RWHashTable, RWBTree, RWSortedVector, RWSet, RWBinaryTree, RWOrdered, RWBag, and RWSequenceable.

void RWCollection::operator+=

(

const RWCollection &

c

)

Adds each item in c to self.

Note

Calling operator+=() on a RWBinaryTree where c is a sorted collection can cause that tree to become unbalanced, possibly to the point of stack overflow.

If c is a collection of key-value pairs (e.g. RWHashDictionary), this call inserts the associations held by c into self. If self is a collection of key-value pairs, this function throws std::bad_cast if a collectable in c does not inherit from RWCollectableAssociation.

void RWCollection::operator-=

(

const RWCollection &

c

)

Removes each item in c from self.

virtual RWCollectable* RWCollection::remove ( const RWCollectable *  target )

pure virtual

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. See function find() for a definition of matches.

Implemented in RWDlistCollectables, RWSlistCollectables, RWHashTable, RWBTree, RWHashDictionary, RWBTreeDictionary, RWOrdered, RWBinaryTree, RWBag, RWSlistCollectablesStack, RWSlistCollectablesQueue, RWIdentitySet, and RWSequenceable.

virtual void RWCollection::removeAndDestroy ( const RWCollectable *  target )

virtual

Removes and deletes the first item in the collection which "matches" the object pointed to by target.

Reimplemented in RWHashDictionary, RWBTreeDictionary, RWBag, RWSlistCollectablesStack, and RWSlistCollectablesQueue.

virtual void RWCollection::restoreGuts ( RWvistream &  )

virtual

Repeatedly calls the global operator:

RWvistream& operator>>(RWvistream&, RWCollectable*&);

followed by insert(RWCollectable*) for each item in the collection.

Reimplemented from RWCollectable.

Reimplemented in RWHashDictionary, RWBTreeDictionary, and RWSlistCollectablesStack.

virtual void RWCollection::restoreGuts ( RWFile &  )

virtual

Repeatedly calls the global operator:

RWFile&  operator>>(RWFile&, RWCollectable*&);

followed by insert(RWCollectable*) for each item in the collection.

Reimplemented from RWCollectable.

Reimplemented in RWHashDictionary, RWBTreeDictionary, and RWSlistCollectablesStack.

virtual void RWCollection::saveGuts ( RWvostream &  ) const

virtual

Calls the global operator.

RWvostream& operator<<(RWvostream&, const RWCollectable&);

for each object in the collection.

Reimplemented from RWCollectable.

Reimplemented in RWBinaryTree.

virtual void RWCollection::saveGuts ( RWFile &  ) const

virtual

Calls the global operator:

RWFile& operator<<(RWFile&, const RWCollectable&);

for each object in the collection.

Reimplemented from RWCollectable.

Reimplemented in RWBinaryTree.

RWCollection* RWCollection::select	(	RWtestCollectable	tst,
		void *	vp
	)		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.

Friends And Related Function Documentation

typedef void(* RWapplyCollectable) (RWCollectable *, void *)

related

A global function used by the apply() method in RWCollection classes to apply a user defined action to an RWCollectable object. A applyCollectable function has prototype:

void RWapplyCollectable(RWCollectable*, void*);

typedef bool(* RWtestCollectable) (const RWCollectable *, const void *)

related

A global function used by the select() method in RWCollection classes to test an RWCollectable object for a user defined property. A testCollectable function has prototype:

bool RWtestCollectable(const RWCollectable*, const void*);

typedef bool(* RWtestCollectablePair) (const RWCollectable *, const RWCollectable *, const void *)

related

A global function used by the select() method in RWCollection classes to test a pair of RWCollectable objects for a user defined property. A testCollectablePair function has prototype:

bool RWtestCollectablePair(const RWCollectable*, const RWCollectable*, const void*);

Member Data Documentation

size_t RWCollection::DEFAULT_CAPACITY

static

The default number of buckets in a RWCollection class.