SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWCollection Class Referenceabstract

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

#include <rw/colclass.h>

Inheritance diagram for RWCollection:
RWCollectable RWBTree RWBag RWBinaryTree RWHashTable RWSequenceable RWBTreeDictionary RWSet RWDlistCollectables RWOrdered RWSlistCollectables RWFactory RWHashDictionary RWIdentitySet RWDBForeignKeyList RWSortedVector RWSlistCollectablesQueue RWSlistCollectablesStack RWIdentityDictionary

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 RWCollectablefind (const RWCollectable *target) const =0
 
virtual RWCollectableinsert (RWCollectable *c)=0
 
virtual RWClassID isA () const
 
virtual bool isEmpty () const =0
 
virtual RWConstIteratornewConstIterator () const =0
 
virtual RWIteratornewIterator ()=0
 
virtual size_t occurrencesOf (const RWCollectable *t) const =0
 
void operator+= (const RWCollection &c)
 
void operator-= (const RWCollection &c)
 
virtual RWCollectableremove (const RWCollectable *target)=0
 
virtual void removeAndDestroy (const RWCollectable *target)
 
virtual void restoreGuts (RWFile &)
 
virtual void restoreGuts (RWvistream &)
 
virtual void saveGuts (RWFile &) const
 
virtual void saveGuts (RWvostream &) const
 
RWCollectionselect (RWtestCollectable tst, void *vp) const
 
- Public Member Functions inherited from RWCollectable
virtual ~RWCollectable ()
 
virtual int compareTo (const RWCollectable *) const
 
virtual RWCollectablecopy () const
 
virtual unsigned hash () const
 
virtual bool isEqual (const RWCollectable *t) const
 
virtual RWCollectablenewSpecies () const
 
RWspace recursiveStoreSize () const
 
RWStringID stringID () const
 

Static Public Attributes

static size_t DEFAULT_CAPACITY
 

Related Symbols

(Note that these are not member symbols.)

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
Contains virtual functions for inserting and retrieving pointers to RWCollectable objects into the co...
Definition colclass.h:60
Persistence
Polymorphic

Constructor & Destructor Documentation

◆ ~RWCollection()

virtual RWCollection::~RWCollection ( )
virtual

Empty destructor.

Member Function Documentation

◆ apply()

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);
Contains virtual functions for identifying, hashing, comparing, storing and retrieving collectable ob...
Definition collect.h:441

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 RWBag, RWBinaryTree, RWBTree, RWDlistCollectables, RWHashTable, RWOrdered, RWSequenceable, and RWSlistCollectables.

◆ asBag()

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.

◆ asBinaryTree()

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.

◆ asOrderedCollection()

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.

◆ asSet()

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.

◆ asSortedCollection()

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.

◆ binaryStoreSize()

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.

◆ clear()

virtual void RWCollection::clear ( )
pure virtual

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

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

◆ clearAndDestroy()

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 RWBag, RWBTreeDictionary, RWHashDictionary, and RWSet.

◆ contains()

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.

◆ entries()

virtual size_t RWCollection::entries ( ) const
pure virtual

Returns the total number of items in the collection.

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

◆ find()

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 RWBag, RWBinaryTree, RWBTree, RWBTreeDictionary, RWDlistCollectables, RWHashDictionary, RWHashTable, RWIdentitySet, RWOrdered, RWSequenceable, and RWSlistCollectables.

◆ insert()

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 RWBag, RWBinaryTree, RWBTree, RWBTreeDictionary, RWDlistCollectables, RWHashDictionary, RWHashTable, RWIdentitySet, RWOrdered, RWSequenceable, RWSet, RWSlistCollectables, RWSlistCollectablesStack, and RWSortedVector.

◆ isA()

◆ isEmpty()

virtual bool RWCollection::isEmpty ( ) const
pure virtual

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

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

◆ newConstIterator()

virtual RWConstIterator * RWCollection::newConstIterator ( ) const
pure virtual

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

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

◆ newIterator()

virtual RWIterator * RWCollection::newIterator ( )
pure virtual

Returns a dynamically allocated iterator for the collection.

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

◆ occurrencesOf()

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 RWBag, RWBinaryTree, RWBTree, RWDlistCollectables, RWHashTable, RWOrdered, RWSequenceable, RWSet, RWSlistCollectables, and RWSortedVector.

◆ operator+=()

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.

◆ operator-=()

void RWCollection::operator-= ( const RWCollection & c)

Removes each item in c from self.

◆ remove()

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 RWBag, RWBinaryTree, RWBTree, RWBTreeDictionary, RWDlistCollectables, RWHashDictionary, RWHashTable, RWIdentitySet, RWOrdered, RWSequenceable, RWSlistCollectables, RWSlistCollectablesQueue, and RWSlistCollectablesStack.

◆ removeAndDestroy()

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 RWBag, RWBTreeDictionary, RWHashDictionary, RWSlistCollectablesQueue, and RWSlistCollectablesStack.

◆ restoreGuts() [1/2]

virtual void RWCollection::restoreGuts ( RWFile & )
virtual

Repeatedly calls the global operator:

RWFile& operator>>(RWFile&, RWCollectable*&);
Represents an abstraction of a filesystem regular file.
Definition rwfile.h:68

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

Reimplemented from RWCollectable.

Reimplemented in RWBTreeDictionary, RWHashDictionary, and RWSlistCollectablesStack.

◆ restoreGuts() [2/2]

virtual void RWCollection::restoreGuts ( RWvistream & )
virtual

Repeatedly calls the global operator:

Abstract base class providing an interface for format-independent retrieval of fundamental types and ...
Definition vstream.h:244

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

Reimplemented from RWCollectable.

Reimplemented in RWBTreeDictionary, RWHashDictionary, and RWSlistCollectablesStack.

◆ saveGuts() [1/2]

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.

◆ saveGuts() [2/2]

virtual void RWCollection::saveGuts ( RWvostream & ) const
virtual

Calls the global operator.

RWvostream& operator<<(RWvostream&, const RWCollectable&);
Abstract base class that provides an interface for format-dependent storage of fundamental types and ...
Definition vstream.h:749

for each object in the collection.

Reimplemented from RWCollectable.

Reimplemented in RWBinaryTree.

◆ select()

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 Symbol Documentation

◆ RWapplyCollectable

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 *)
Definition defs.h:525

◆ RWtestCollectable

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*);
bool(* RWtestCollectable)(const RWCollectable *, const void *)
Definition defs.h:495

◆ RWtestCollectablePair

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:

const void*);
bool(* RWtestCollectablePair)(const RWCollectable *, const RWCollectable *, const void *)
Definition defs.h:509

Member Data Documentation

◆ DEFAULT_CAPACITY

size_t RWCollection::DEFAULT_CAPACITY
static

The default number of buckets in a RWCollection class.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.