SourcePro 11.1 |
SourcePro® C++ API Reference Guide |
SourcePro C++ Documentation Home |
Contains virtual functions for identifying, hashing, comparing, storing and retrieving collectable objects. More...
#include <rw/collect.h>
Public Member Functions | |
virtual RWCollectable * | newSpecies () const |
virtual RWClassID | isA () const |
virtual | ~RWCollectable () |
virtual RWspace | binaryStoreSize () const |
virtual int | compareTo (const RWCollectable *) const |
virtual unsigned | hash () const |
virtual bool | isEqual (const RWCollectable *t) const |
virtual void | restoreGuts (RWFile &) |
virtual void | restoreGuts (RWvistream &) |
virtual void | saveGuts (RWFile &) const |
virtual void | saveGuts (RWvostream &) const |
RWspace | recursiveStoreSize () const |
RWStringID | stringID () const |
Static Public Member Functions | |
static RWClassID | classIsA () |
static RWspace | nilStoreSize () |
static RWClassID | classID (const RWStringID &name) |
static bool | isAtom (RWClassID id) |
Friends | |
RWvistream & | operator>> (RWvistream &s, RWCollectable *&pCl) |
RWFile & | operator>> (RWFile &f, RWCollectable *&pCl) |
RWvostream & | operator<< (RWvostream &v, const RWCollectable &obj) |
RWFile & | operator<< (RWFile &f, const RWCollectable &obj) |
RWvistream & | operator>> (RWvistream &v, RWCollectable &obj) |
RWFile & | operator>> (RWFile &f, RWCollectable &obj) |
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.
typedef RWCollectable Object; // Smalltalk typedef #include <rw/collect.h>
Polymorphic
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.
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 RWCollection, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBValue, and RWCollectableDateTime.
static RWClassID RWCollectable::classID | ( | const RWStringID & | name | ) | [inline, static] |
static RWClassID RWCollectable::classIsA | ( | ) | [static] |
Returns the RWClassID of this class.
Reimplemented in RWBinaryTree, RWBTreeDictionary, RWBTree, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBRow, RWDBValue, RWDlistCollectables, RWHashDictionary, RWHashTable, RWIdentityDictionary, RWIdentitySet, RWOrdered, RWSlistCollectablesQueue, RWBag, RWSet, RWSlistCollectables, RWSortedVector, RWSlistCollectablesStack, and RWCollectableDateTime.
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.
Reimplemented in RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBValue, and RWCollectableDateTime.
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 RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBCollectableExpr, RWDBValue, and RWCollectableDateTime.
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 RWBinaryTree, RWBTreeDictionary, RWBTree, RWCollection, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBRow, RWDBValue, RWDlistCollectables, RWHashDictionary, RWHashTable, RWIdentityDictionary, RWIdentitySet, RWOrdered, RWSlistCollectablesQueue, RWBag, RWSet, RWSlistCollectables, RWSortedVector, RWSlistCollectablesStack, and RWCollectableDateTime.
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] |
Returns true
if the collectable object "matches" the object at address t. The default definition is:
return this == t;
i.e., both objects have the same address (a test for identity). The definition may be redefined in any consistent way.
Reimplemented in RWBinaryTree, RWBTreeDictionary, RWBTree, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBCollectableExpr, RWDBValue, RWDlistCollectables, RWHashDictionary, RWHashTable, RWIdentityDictionary, RWIdentitySet, RWOrdered, RWSlistCollectablesQueue, RWBag, RWSet, RWSlistCollectables, RWSortedVector, RWSlistCollectablesStack, and RWCollectableDateTime.
virtual RWCollectable* RWCollectable::newSpecies | ( | ) | const [virtual] |
Allocates a new object off the heap of the same type as self and returns a pointer to it. You are responsible for deleting the object when done with it.
Reimplemented in RWBinaryTree, RWBTreeDictionary, RWBTree, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBRow, RWDBValue, RWDlistCollectables, RWHashDictionary, RWHashTable, RWIdentityDictionary, RWIdentitySet, RWOrdered, RWSlistCollectablesQueue, RWBag, RWSet, RWSlistCollectables, RWSortedVector, RWSlistCollectablesStack, and RWCollectableDateTime.
static RWspace RWCollectable::nilStoreSize | ( | ) | [inline, static] |
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 | ( | RWvistream & | ) | [virtual] |
Reads an object's state from an input stream, replacing the previous state.
Reimplemented in RWCollection, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBValue, RWSlistCollectablesStack, and RWCollectableDateTime.
virtual void RWCollectable::restoreGuts | ( | RWFile & | ) | [virtual] |
Reads an object's state from a binary file, using class RWFile, replacing the previous state.
Reimplemented in RWCollection, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBValue, RWSlistCollectablesStack, and RWCollectableDateTime.
virtual void RWCollectable::saveGuts | ( | RWvostream & | ) | const [virtual] |
Writes an object's state to an output stream.
Reimplemented in RWBinaryTree, RWCollection, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBValue, and RWCollectableDateTime.
virtual void RWCollectable::saveGuts | ( | RWFile & | ) | const [virtual] |
Writes an object's state to a binary file, using class RWFile.
Reimplemented in RWBinaryTree, RWCollection, RWCollectableAssociation, RWCollectableDate, RWCollectableInt, RWCollectableString, RWCollectableWString, RWCollectableTime, RWDBBlob, RWDBValue, and RWCollectableDateTime.
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.
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.
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, | |
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).
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 *& | 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, the pointer to the partly restored object may be lost, creating a memory leak. For this reason, you may prefer to use the static methods tryRecursiveRestore().
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, the pointer to the partly restored object may be lost, creating a memory leak. For this reason, you may prefer to use the static methods tryRecursiveRestore().
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.