RWCollectable(3C++) RWCollectable(3C++)
NameRWCollectable - Rogue Wave library class
Synopsis
typedef RWCollectable Object; // Smalltalk typedef
#include <rw/collect.h>
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 will typically redefine one or more of them.
Persistence
Polymorphic
Virtual Functions
virtual
~RWCollectable();
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
binaryStoreSize() const;
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 Tool.h++ User's Guide Section entitled "Virtual Function
binaryStoreSize" for details.
virtual int
compareTo(const RWCollectable*) const;
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;
Page 1
RWCollectable(3C++) RWCollectable(3C++)
<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.
virtual unsigned
hash() const;
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 which return
TRUE to isEqual().
virtual RWClassID
isA() const;
Returns a class identification number (typedef'd to be an 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.
virtual RWBoolean
isEqual(const RWCollectable* t) const;
Returns TRUE if collectable object "matches" 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.
virtual RWCollectable*
newSpecies() const;
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.
virtual void
restoreGuts(RWFile&);
Read an object's state from a binary file, using class RWFile, replacing
the previous state.
Page 2
RWCollectable(3C++) RWCollectable(3C++)
virtual void
restoreGuts(RWvistream&);
Read an object's state from an input stream, replacing the previous
state.
virtual void
saveGuts(RWFile&) const;
Write an object's state to a binary file, using class RWFile.
virtual void
saveGuts(RWvostream&) const;
Write an object's state to an output stream.
RWStringID
stringID();
Returns the identification string for the class. Acts virtual, although
it is not.
RWspace
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.
Static Public Member Functions
static RWClassID
classID(const RWStringID& name);
Returns the result of looking up the RWClassID associated with name in
the global RWFactory.
Page 3
RWCollectable(3C++) RWCollectable(3C++)
static RWClassID
classIsA();
Returns the RWClassID of this class.
static RWBoolean
isAtom(RWClassID id);
Returns TRUE if id is the RWClassID that is associated with an
RWCollectable class that has a programmer-chosen RWStringID.
static RWspace
nilStoreSize();
Returns the number of bytes required to store a rwnil pointer in an
RWFile.
Related Global Operators
RWvostream&
operator<<(RWvostream&, const RWCollectable& obj);
RWFile&
operator<<(RWFile&, const RWCollectable& obj);
Saves the object obj to a virtual stream or RWFile, respectively.
Recursively calls the virtual function saveGuts(), taking duplicate
objects into account. See the Tools.h++ User's Guide section entitled
"Persistence" for more information.
RWvistream&
operator>>(RWvistream&, RWCollectable& obj);
RWFile&
operator>>(RWFile&, RWCollectable& obj);
Restores an object inheriting from RWCollectable into obj from a virtual
stream or RWFile, respectively, replacing the previous contents of obj.
Recursively calls the virtual function restoreGuts(), taking duplicate
objects into account. See the Tools.h++ User's Guide section entitled
"Persistence" for more information. 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&, RWCollectable*& obj);
RWFile&
operator>>(RWFile&, RWCollectable*& obj);
Page 4
RWCollectable(3C++) RWCollectable(3C++)
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. See the Tools.h++ User's Guide section
entitled "Persistence" for more information. 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). In case
an exception is thrown during this call, the pointer to the partly
restored object will probably be lost, and memory will leak. For this
reason, you may prefer to use the static methods tryRecursiveRestore()
documented above.
Page 5
