The virtual function isA() returns a class identifier: a unique number that identifies an object's class. It can be used to determine the class to which an object belongs. Here's the function declaration provided by macro RWDECLARE_COLLECTABLE:

virtual RWClassID isA() const;

RWClassID is actually a typedef to an unsigned short. Numbers from 0x8000 (hex) and up are reserved for use by Rogue Wave. You may choose a numeric class ID from 9x0001 to 0x7fff. There is a set of class symbols defined in <rw/tooldefs.h> for the Tools.h++ Class Library. Generally, these follow the pattern of a double underscore followed by the class name with all letters in upper case. For example:

RWCollectableString yogi;
yogi.isA() == __RWCOLLECTABLESTRING;         // Evaluates TRUE

The macro RWDECLARE_COLLECTABLE(className) will automatically provide a declaration for isA(). Either RWDEFINITION_MACRO will supply the definition.

The job of this function is to return a pointer to a brand new object of the same type as self. Here is the function declaration provided by macro RWDECLARE_COLLECTABLE:

virtual RWCollectable*  newSpecies() const;

The definition is automatically provided by either version of RWDEFINITION_MACRO.

The stringID() function acts like a virtual function, but it is not.^[23] It returns an instance of RWStringID, a unique string that identifies an object's class. RWStringID is derived from class RWCString. By default, the string identifier for a class is the same as the name of the class. RWStringID can be used instead of, or as a suppplement to, RWClassIDs.

The virtual function compareTo() is used to order objects relative to each other. This function is required in collection classes that depend on such ordering, such as RWBinaryTree or RWBTree. Here is its declaration:

virtual int  compareTo(const RWCollectable*) const;

The function int compareTo(const RWCollectable*) const should return a number greater than zero if self is greater than the argument, a number less than zero if self is less than the argument, and zero if self is equal to the argument.

The definition and meaning of whether one object is greater than, less than, or equal to another object is left to the class designer. The default definition, found in class RWCollectable, is to compare the two addresses of the objects. This default definition should be considered a placeholder; in practice, it is not very useful and could vary from run to run of a program.

Here is a possible definition of compareTo():

int Bus::compareTo(const RWCollectable* c) const
{  const Bus* b = (const Bus*)c;
  if (busNumber_ == b->busNumber_) return 0;
   return busNumber_ > b->busNumber_ ? 1 : -1;
}

Here we are using the bus number as a measure of the ordering of buses. If we need to insert a group of buses into an RWBinaryTree, they would be sorted by their bus number. Note that there are many other possible choices(we could have used the driver name, in which case they would have been sorted by the driver name. Which choice you use will depend on your particular problem.

There is a hazard here. We have been glib in assuming that the actual type of the RWCollectable which c points to is always a Bus. If a careless user inserted, say, an RWCollectableString into the collection, then the results of the cast (const Bus*)c would be invalid, and dereferencing it could bring disaster^[24] . The necessity for all overloaded virtual functions to share the same signatures requires that they return the lowest common denominator, in this case, class RWCollectable. The result is that much compile-time type checking breaks down.

---

Note: You must be careful that the members of a collection are either homogeneous (i.e., all of the same type), or that there is some way of telling them apart. The member functions isA() or stringID() can be used for this.

---

The virtual function isEqual() plays a similar role to the tester function of the generic collection classes described in "Tester Functions" in Chapter 12.

RWBoolean  isEqual(const RWCollectable* c) const;

The function RWBoolean isEqual(const RWCollectable*) should return TRUE if the object and its argument are considered equal, and FALSE otherwise. The definition of equality is left to the class designer. The default definition, as defined in class RWCollectable, is to test the two addresses for equality, that is, to test for identity.

Note that isEqual does not have to be defined as being identical. Rather isEqual can mean that two objects are equivalent in some sense. In fact, the two objects need not even be of the same type. The only requirement is that the object passed as an argument must inherit type RWCollectable. You are responsible for making sure that any typecasts you do are appropriate.

Also note that there is no formal requirement that two objects that compare equal (i.e., compareTo() returns zero) must also return TRUE from isEqual(), although it is hard to imagine a situation where this wouldn't be the case. It is also possible to design a class for which the isEqual test returns true for objects that have different hash values. This would make it impossible to search for such objects in a hash-based collection.

For the Bus class, an appropriate definition of isEqual might be:

RWBoolean Bus::isEqual(const RWCollectable* c) const
{  const Bus* b = (const Bus*)c;
   return busNumber_ == b->busNumber_;
}

Here we are considering buses to be equal if their bus numbers are the same. Again, other choices are possible.

The function hash() should return an appropriate hashing value for the object. Here is the function's declaration:

unsigned  hash() const;

A possible definition of hash() for our class Bus might be:

unsigned Bus::hash() const{
  return (unsigned)busNumber_;
}

The example above simply returns the bus number as a hash value. Alternatively, we could choose the driver's name as a hash value:

unsigned Bus::hash() const{
  return driver_.hash();
}

In the above example, driver_ is an RWCString that already has a hash function defined.

---

Note: we expect that two objects that test TRUE for isEqual will hash to the same value.

---

We've described three inherited virtual functions: compareTo(), isEqual(), and hash(). Here is an example that defines a set of objects, and applies the functions. The results of the functions appear as comments in the code.

RWCollectableString a("a");
RWCollectableString b("b");
RWCollectableString a2("a");
 
a.compareTo(&b);      // Returns -1
a.compareTo(&a2);     // Returns 0 ("compares equal")
b.compareTo(&a);      // Returns 1
 
a.isEqual(&a2);       // Returns TRUE
a.isEqual(&b);        // Returns FALSE
 
a.hash()              // Returns 96 (operating system dependent)

Note that the compareTo() function for RWCollectableStrings has been defined to compare strings lexicographically in a case sensitive manner. See class RWCString in the Class Reference for details.

The saveGuts(RWFile&) and saveGuts(RWvostream&) virtual functions are responsible for polymorphically saving the internal state of an RWCollectable object on either a binary file, using class RWFile, or on a virtual output stream, using class RWvostream.^[25] This allows the object to be restored at some later time, or in a different location. Here are some rules for defining a saveGuts() function:

With these rules in mind, let's look at a possible definition of the saveGuts() functions for the Bus example:

void Bus::saveGuts(RWFile& f) const
{  RWCollectable::saveGuts(f);    // Save base class
   f.Write(busNumber_);           // Write primitive directly
   f << driver_ << customers_;    // Use Rogue Wave 
                                  //provided versions
   f << passengers_;              // Will detect nil pointer
                                  // automatically
}
 
void Bus::saveGuts(RWvostream& strm) const
{  RWCollectable::saveGuts(strm); // Save base class
   strm << busNumber_;            // Write primitives directly
   strm << driver_ << customers_; // Use Rogue Wave 
                                  // provided versions
   strm << passengers_;           // Will detect nil pointer
                                  // automatically
}

Member data busNumber_ is an int, a C++ primitive. It is stored directly using either RWFile::Write(int), or RWvostream::operator<<(int).

Member data driver_ is an RWCString. It does not inherit from RWCollectable. It is stored using:

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

Member data customers_ is an RWSet. It does inherit from RWCollectable. It is stored using:

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

Finally, member data passengers_ is a little tricky. This data is a pointer to an RWSet, which inherits from RWCollectable. However, there is the possibility that the pointer is nil. If it is nil, then passing it to:

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

would be disastrous, as we would have to dereference passengers_:

strm << *passengers_;

Instead, since our class has declared passenger_ as an RWSet*, we pass it to:

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

which automatically detects the nil pointer and stores a record of it.

In a manner similar to saveGuts(), these virtual functions are used to restore the internal state of an RWCollectable from a file or stream. Here is a definition of these functions for the Bus class:

void Bus::restoreGuts(RWFile& f)
{  RWCollectable::restoreGuts(f);   // Restore base class
   f.Read(busNumber_);              // Restore primitive
   f >> driver_ >> customers_;      // Uses Rogue Wave provided
                                    // versions
 
   delete passengers_;              // Delete old RWSet
   f >> passengers_;                // Replace with a new one
}
 
void Bus::restoreGuts(RWvistream& strm)
{  RWCollectable::restoreGuts(strm);   // Restore base class
   strm >> busNumber_ >> driver_ >> customers_;
 
   delete passengers_;                 // Delete old RWSet
   strm >> passengers_;                // Replace with a new one
}

Note that the pointer passengers_ is restored using:

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

If the original passengers_ is non-nil, then this function restores a new RWSet off the heap and returns a pointer to it. Otherwise, it returns a nil pointer. Either way, the old contents of passengers_ are replaced. Hence, we must call delete passengers_ first.

A passenger name can exist in the set pointed to by customers_and in the set pointed to by passengers_; that is, both collections contain the same string. When the Bus is restored, we want to make sure that the pointer relationship is maintained, and that our restoration does not create another copy of the string.

Fortunately, we don't have to do anything special to insure that the pointer relationship stays as it should be. Consider the call:

Bus aBus;
RWFile aFile("busdata.dat");
 
aBus.addPassenger("John");
aFile << aBus;

Because passenger_is a subset of customer_, the function addPassenger puts the name on both the customer list and the passenger list. When we save aBus to aFile, both lists are saved in a single call: first the customer list, then the passenger list. The polymorphic persistence machinery saves the first reference to John, but for the second reference it merely stores a reference to the first copy. During the restore, both references will resolve to the same object, replicating the original morphology of the collection.

The binaryStoreSize() virtual function calculates the number of bytes necessary to store an object using RWFile. The function is:

virtual Rwspace  binaryStoreSize() const;

This function is useful for classes RWFileManager and RWBTreeOnDisk, which require allocation of space for an object before it can be stored. The non-virtual function recursiveStoreSize() returns the number of bytes that is actually stored. Recursive store size uses binaryStoreSize() to do its work.

Writing a version of binaryStoreSize() is usually straightforward. You just follow the pattern set by saveGuts(RWFile&), except that instead of saving member data, you add up their sizes. The only real difference is a syntactic one: instead of insertion operators, you use sizeof() and the member functions indicated below:

Here's a sample definition of a binaryStoreSize() function for class Bus:

RWspace Bus::binaryStoreSize() const{
   RWspace count = RWCollectable::binaryStoreSize() +
     customers_.recursiveStoreSize() +
     sizeof(busNumber_) +
     driver_.binaryStoreSize();
 
   if (passengers_)
     count += passengers_->recursiveStoreSize();
   else
     count += RWCollectable::nilStoreSize();
 
   return count;
}

The versions of saveGuts() and restoreGuts() that Tools.h++ built into class RWCollection are sufficient for most collection classes. The function RWCollection::saveGuts() works by repeatedly calling:

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

for each item in the collection. Similarly, RWCollection::restoreGuts() works by repeatedly calling:

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

This operator allocates a new object of the proper type off the heap, then calls insert(). Because all of the Rogue Wave Smalltalk-like collection classes inherit from RWCollection, they all use this mechanism.

If you decide to write your own collection classes that inherit from class RWCollection, you will rarely have to define your own saveGuts() or restoreGuts().

There are exceptions. For example, class RWBinaryTree has its own version of saveGuts(). This is necessary because the default version of saveGuts() stores items in order. For a binary tree, this would result in a severely unbalanced tree when the tree was read back in—essentially, the degenerate case of a linked list. Hence, RWBinaryTree's version of saveGuts() stores the tree level-by-level.

When you design your class, you must determine whether it has similar special requirements which may need a custom version of saveGuts() and restoreGuts().