2.4 Common Member Functions

Whatever their category, all classes have similar programming interfaces. This section highlights their common functionality.

Tools.h++ uses the following member functions to store an object of type ClassName to and from an RWFile, and to and from the Rogue Wave virtual streams facility, and to restore it later:

RWFile&      operator<<(RWFile& file, const ClassName&);
RWFile&      operator>>(RWFile& file,       ClassName&);
Rwvostream&  operator<<(RWvostream& vstream,const ClassName&);
Rwvistream&  operator>>(RWvistream& vstream,  ClassName&);

Class RWFile, which encapsulates ANSI-C file I/O, saves objects in binary format. The result is efficient storage and retrieval to files. For more information on RWFile, see Section 7 and the Class Reference.

Classes RWvistream and RWvostream are abstract base classes used by the Rogue Wave virtual streams facility. The final output format is determined by the specializing class. For example, RWpistream and RWpostream are two classes that derive from RWvistream and RWvostream, respectively. They store and retrieve objects using a portable ASCII format. The results can be transferred between different operating systems. These classes are discussed in more detail in Section 6 and the Class Reference.

It's up to you to decide whether to store to RWFiles, or to Rogue Wave streams. Storing to RWFiles gives you speed, but limits portability of results to the host machine and operating system. Storing to Rogue Wave streams is not as fast, but you get several specializing classes that provide other useful features, including highly portable format between different machines, and XDR stream encapsulation for distributed computations.

The following common member functions return the number of bytes of secondary storage necessary to store an object of type ClassName to an RWFile:

Rwspace  ClassName::binaryStoreSize() const;
Rwspace  ClassName::recursiveStoreSize() const;

The member functions use the function:

RWFile& operator<<(RWFile& file, const ClassName&);

The above member functions are good for storing objects using classes RWFileManager and RWBTreeOnDisk. For objects that inherit from RWCollectable, the second variant recursiveStoreSize()can calculate the number of bytes used in a recursive store. The variant uses the function:

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

You can use class RWAuditStreamBuffer in conjuction with any stream to count the number of bytes that pass through the buffer. Therefore, this class gives you functionality for streams as the above member functions give you functionality for files. For more information on class RWAuditStreamBuffer, see the Class Reference.

The overloaded left-shift operator <<, taking an ostream object as its first argument, will print the contents of an object in human-readable form. Conversely, the overloaded right-shift operator >>, taking an istream object as its first argument, will read and parse an object from the stream in a human-understandable format.

ostream&  operator<<(ostream& ostr, const ClassName& x);
istream&  operator>>(istream& istr, const ClassName& x);

The overloaded left-shift and right-shift operators contrast with the persistence operators:

Rwvostream&  operator<<(RWvostream& vstream, const ClassName&);
Rwvistream&  operator>>(RWvistream& vstream,       ClassName&);

Although the persistence shift operators may store and restore to and from a stream, they will not necessarily do so in a form that could be called "human-readable."

Finally, most classes have comparison and equality member functions:

int        compareTo(ClassName*) const;
RWBoolean  equalTo(ClassName*) const;

and their logical operator counterparts:

RWBoolean  operator==(const ClassName&) const;
RWBoolean  operator!=(const ClassName&) const;
RWBoolean  operator<=(const ClassName&) const;
RWBoolean  operator>=(const ClassName&) const;
RWBoolean  operator<(const ClassName&) const;
RWBoolean  operator>(const ClassName&) const;