RWCollectable Class Reference

Contains virtual functions for identifying, hashing, comparing, storing and retrieving collectable objects. More...

#include <rw/collect.h>

Inheritance diagram for RWCollectable:

Public Member Functions
virtual	~RWCollectable ()
virtual RWspace	binaryStoreSize () const
virtual int	compareTo (const RWCollectable *) const
virtual RWCollectable *	copy () const
virtual unsigned	hash () const
virtual RWClassID	isA () const
virtual bool	isEqual (const RWCollectable *t) const
virtual RWCollectable *	newSpecies () const
RWspace	recursiveStoreSize () const
virtual void	restoreGuts (RWFile &)
virtual void	restoreGuts (RWvistream &)
virtual void	saveGuts (RWFile &) const
virtual void	saveGuts (RWvostream &) const
RWStringID	stringID () const

Static Public Member Functions
static RWClassID	classID (const RWStringID &name)
static RWClassID	classIsA ()
static bool	isAtom (RWClassID id)
static RWspace	nilStoreSize ()

Friends
RWvostream &	operator<< (RWvostream &v, const RWCollectable &obj)
RWFile &	operator<< (RWFile &f, const RWCollectable &obj)
RWvistream &	operator>> (RWvistream &s, RWCollectable *&pCl)
RWFile &	operator>> (RWFile &f, RWCollectable *&pCl)
RWvistream &	operator>> (RWvistream &v, RWCollectable &obj)
RWFile &	operator>> (RWFile &f, RWCollectable &obj)

Detailed Description

Class RWCollectable is an abstract base class for collectable objects. This class contains virtual functions for identifying, hashing, comparing, storing and retrieving collectable objects. While these virtual functions have simple default definitions, objects that inherit this base class typically redefine one or more of them.

Synopsis

typedef RWCollectable Object;  // Smalltalk typedef
#include <rw/collect.h>

Persistence

Polymorphic

Constructor & Destructor Documentation

virtual RWCollectable::~RWCollectable ( )

virtual

All functions that inherit class RWCollectable have virtual destructors. This allows them to be deleted by such member functions as removeAndDestroy() without knowing their type.

Member Function Documentation

virtual RWspace RWCollectable::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 in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWDBCheckConstraint, RWCollectableDate, RWCollectableDateTime, RWDBUniqueConstraint, RWDBBlob, RWCollectableString, RWCollectableTime, RWCollectableAssociation, RWDBRow, RWCollection, and RWCollectableInt.

static RWClassID RWCollectable::classID ( const RWStringID &  name )

inlinestatic

Returns the result of looking up the RWClassID associated with name in the global RWFactory.

static RWClassID RWCollectable::classIsA ( )

static

Returns the RWClassID of this class.

virtual int RWCollectable::compareTo ( const RWCollectable *  ) const

virtual

The function compareTo() is necessary to sort the items in a collection. If p1 and p2 are pointers to RWCollectable objects, the statement:

p1->compareTo(p2);

should return:

0 if *p1 "is equal to" *p2;

>0 if *p1 is "larger" than *p2;

<0 if *p1 is "smaller" than *p2.

Note that the meaning of "is equal to," "larger" and "smaller" is left to the user. The default definition provided by the base class is based on the addresses, i.e.,

return this == p2 ? 0 : (this > p2 ? 1 : -1);

and is probably not very useful.

In derived classes, it is recommended that compareTo() first perform ordering on the RWCollectable type (via the isA() method). If both sides are of the same type, then ordering based on the rules for that type should be applied.

Reimplemented in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWCollectableDate, RWCollectableDateTime, RWDBCheckConstraint, RWDBBlob, RWCollectableString, RWDBUniqueConstraint, RWCollectableTime, RWCollectableAssociation, RWCollectableInt, and RWDBRow.

virtual RWCollectable* RWCollectable::copy ( ) const

virtual

Returns a new, copy-constructed object of the same type as self. The caller is responsible for deleting the object.

Reimplemented in RWDBValue, RWDBCollectableExpr, RWDBForeignKey, RWCollectableWString, RWDBBlob, RWDBCheckConstraint, RWDBUniqueConstraint, RWDBRow, RWHashTable, RWSortedVector, RWBTree, RWBag, RWSet, RWSlistCollectablesStack, RWOrdered, RWSlistCollectables, RWCollectableTime, RWCollectableDateTime, RWBinaryTree, RWSlistCollectablesQueue, RWCollectableAssociation, RWDlistCollectables, RWIdentitySet, RWBTreeDictionary, RWCollectableDate, RWIdentityDictionary, RWCollectableString, RWHashDictionary, and RWCollectableInt.

virtual unsigned RWCollectable::hash ( ) const

virtual

Returns a hash value. This function is necessary for collection classes that use hash table look-up. The default definition provided by the base class hashes the object's address:

return (unsigned)this;

It is important that the hash value be the same for all objects that return true to isEqual().

Reimplemented in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWCollectableDate, RWCollectableString, RWCollectableDateTime, RWDBBlob, RWDBCheckConstraint, RWDBUniqueConstraint, RWCollectableTime, RWCollectableAssociation, RWDBRow, and RWCollectableInt.

virtual RWClassID RWCollectable::isA ( ) const

virtual

Returns a class identification number (with a typedef of unsigned short). The default definition returns __RWCOLLECTABLE. Identification numbers greater than or equal to 0x8000 (hex) are reserved for Rogue Wave objects. User-defined classes should define isA() to return a number between 0 and 0x7FFF.

Reimplemented in RWDBValue, RWDBCollectableExpr, RWDBForeignKey, RWCollectableWString, RWDBBlob, RWDBCheckConstraint, RWDBUniqueConstraint, RWDBRow, RWHashTable, RWSortedVector, RWCollection, RWBTree, RWBag, RWSet, RWSlistCollectablesStack, RWSlistCollectables, RWOrdered, RWCollectableTime, RWCollectableDateTime, RWBinaryTree, RWSlistCollectablesQueue, RWCollectableAssociation, RWDlistCollectables, RWIdentitySet, RWBTreeDictionary, RWCollectableDate, RWIdentityDictionary, RWCollectableString, RWHashDictionary, and RWCollectableInt.

static bool RWCollectable::isAtom ( RWClassID  id )

static

Returns true if id is the RWClassID that is associated with an RWCollectable class that has a programmer-chosen RWStringID.

virtual bool RWCollectable::isEqual ( const RWCollectable *  t ) const

virtual

Behaves as if compareTo(t) was invoked, returning true if the result equals 0, false otherwise.

Reimplemented in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWDlistCollectables, RWHashTable, RWSlistCollectables, RWSortedVector, RWBTree, RWHashDictionary, RWBTreeDictionary, RWSet, RWCollectableDate, RWCollectableDateTime, RWBinaryTree, RWCollectableString, RWBag, RWOrdered, RWDBBlob, RWDBCheckConstraint, RWSlistCollectablesStack, RWCollectableTime, RWIdentityDictionary, RWDBUniqueConstraint, RWIdentitySet, RWCollectableAssociation, RWSlistCollectablesQueue, RWCollectableInt, and RWDBRow.

virtual RWCollectable* RWCollectable::newSpecies ( ) const

virtual

Returns a new, default-constructed object of the same type as self. The caller is responsible for deleting the object.

Reimplemented in RWDBValue, RWDBCollectableExpr, RWDBForeignKey, RWCollectableWString, RWDBBlob, RWDBCheckConstraint, RWDBUniqueConstraint, RWDBRow, RWHashTable, RWSortedVector, RWBTree, RWBag, RWSet, RWSlistCollectablesStack, RWOrdered, RWSlistCollectables, RWCollectableTime, RWCollectableDateTime, RWBinaryTree, RWSlistCollectablesQueue, RWCollectableAssociation, RWDlistCollectables, RWIdentitySet, RWBTreeDictionary, RWCollectableDate, RWIdentityDictionary, RWCollectableString, RWHashDictionary, and RWCollectableInt.

static RWspace RWCollectable::nilStoreSize ( )

static

Returns the number of bytes required to store an rwnil pointer in an RWFile.

RWspace RWCollectable::recursiveStoreSize

(

)

const

Returns the number of bytes required to store the object using the global operator:

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

Recursively calls binaryStoreSize(), taking duplicate objects into account.

virtual void RWCollectable::restoreGuts ( RWFile &  )

virtual

Reads an object's state from a binary file, using class RWFile, replacing the previous state.

Reimplemented in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWHashDictionary, RWBTreeDictionary, RWCollectableDateTime, RWCollectableDate, RWDBBlob, RWCollectableString, RWDBCheckConstraint, RWDBUniqueConstraint, RWSlistCollectablesStack, RWCollectableTime, RWCollectableAssociation, RWCollection, RWDBRow, and RWCollectableInt.

virtual void RWCollectable::restoreGuts ( RWvistream &  )

virtual

Reads an object's state from an input stream, replacing the previous state.

Reimplemented in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWHashDictionary, RWBTreeDictionary, RWDBBlob, RWCollectableDateTime, RWCollectableDate, RWCollectableString, RWDBCheckConstraint, RWDBUniqueConstraint, RWSlistCollectablesStack, RWCollectableTime, RWCollectableAssociation, RWDBRow, RWCollection, and RWCollectableInt.

virtual void RWCollectable::saveGuts ( RWFile &  ) const

virtual

Writes an object's state to a binary file, using class RWFile.

Reimplemented in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWCollectableDateTime, RWBinaryTree, RWCollectableDate, RWCollectableString, RWDBBlob, RWDBCheckConstraint, RWDBUniqueConstraint, RWCollectableTime, RWCollectableAssociation, RWCollection, RWCollectableInt, and RWDBRow.

virtual void RWCollectable::saveGuts ( RWvostream &  ) const

virtual

Writes an object's state to an output stream.

Reimplemented in RWDBCollectableExpr, RWDBValue, RWCollectableWString, RWDBForeignKey, RWCollectableDateTime, RWBinaryTree, RWCollectableDate, RWCollectableString, RWDBBlob, RWDBCheckConstraint, RWDBUniqueConstraint, RWCollectableTime, RWCollectableAssociation, RWCollection, RWDBRow, and RWCollectableInt.

RWStringID RWCollectable::stringID ( ) const

inline

Returns the identification string for the class. Acts virtual, although it is not. See the discussion on RWStringID in the Essential Tools Module User's Guide for more information on how to make a non-virtual function act like a virtual function.

Friends And Related Function Documentation

RWvostream& operator<< ( RWvostream &  v, const RWCollectable &  obj  )

friend

Saves the object obj to a virtual stream. Recursively calls the virtual function saveGuts(), taking duplicate objects into account. See the discussion on Persistence in the Essential Tools Module User's Guide for more information.

RWFile& operator<< ( RWFile &  f, const RWCollectable &  obj  )

friend

Saves the object obj to an RWFile. Recursively calls the virtual function saveGuts(), taking duplicate objects into account. See the discussion on Persistence in the Essential Tools Module User's Guide for more information.

RWvistream& operator>> ( RWvistream &  s, RWCollectable *&  pCl  )

friend

Looks at the next object on the input stream or RWFile, respectively, and either creates a new object of the proper type off the heap and returns a pointer to it, or else returns a pointer to a previously read instance. Recursively calls the virtual function restoreGuts(), taking duplicate objects into account. If an object is created off the heap, then you are responsible for deleting it. For more information, see the discussion on Persistence in the Essential Tools Module User's Guide.

Various exceptions that could be thrown are RWInternalErr (if the RWFactory does not know how to make the object), and RWExternalErr (corrupted stream or file). If an exception is thrown during this call, pCl may point to the partly restored object.

RWFile& operator>> ( RWFile &  f, RWCollectable *&  pCl  )

friend

Looks at the next object on the input stream or RWFile, respectively, and either creates a new object of the proper type off the heap and returns a pointer to it, or else returns a pointer to a previously read instance. Recursively calls the virtual function restoreGuts(), taking duplicate objects into account. If an object is created off the heap, then you are responsible for deleting it. For more information, see the discussion on Persistence in the Essential Tools Module User's Guide.

Various exceptions that could be thrown are RWInternalErr (if the RWFactory does not know how to make the object), and RWExternalErr (corrupted stream or file). If an exception is thrown during this call, pCl may point to the partly restored object.

RWvistream& operator>> ( RWvistream &  v, RWCollectable &  obj  )

friend

Restores an object inheriting from RWCollectable into obj from a virtual stream, replacing the previous contents of obj. Recursively calls the virtual function restoreGuts(), taking duplicate objects into account. For more information, see the discussion on Persistence in the Essential Tools Module User's Guide.

Various exceptions that could be thrown are RWInternalErr (if the RWFactory does not know how to make the object), and RWExternalErr (corrupted stream or file).

RWFile& operator>> ( RWFile &  f, RWCollectable &  obj  )

friend

Restores an object inheriting from RWCollectable into obj from an RWFile, replacing the previous contents of obj. Recursively calls the virtual function restoreGuts(), taking duplicate objects into account. For more information, see the discussion on Persistence in the Essential Tools Module User's Guide.

Various exceptions that could be thrown are RWInternalErr (if the RWFactory does not know how to make the object), and RWExternalErr (corrupted stream or file).