Common Functionality Among Classes
This section describes issues that affect almost every Essential Tools Module class, including member functions, memory allocation, information flow, multithread safety, indexing, and finding the module version number.
Common Member Functions
Whatever their category, all classes have similar programming interfaces. This section highlights their common member functions.
Persistence Functions
The Essential Tools Module 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 lower levelC I/O API efficiently, saves/restores objects to/from files. The result is efficient storage and retrieval to files. For more information on
RWFile, see
Chapter 10 and the
SourcePro API Reference Guide.
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
Chapter 5 and the
SourcePro API Reference Guide.
You can 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. These features include a highly portable format between different machines and XDR stream encapsulation for distributed computations.
Store Size Functions
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 conjunction with any stream to count the number of bytes that pass through the buffer.
RWAuditStreamBuffer thus provides the same functionality for streams that the
StoreSize member functions (discussed above) provide for files. For more information on class
RWAuditStreamBuffer, see the
SourcePro API Reference Guide.
Stream I/O Functions
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.”
Comparison Functions
Finally, most classes have comparison and equality member functions:
int compareTo(ClassName*) const;
bool equalTo(ClassName*) const;
and their logical operator counterparts:
bool operator==(const ClassName&) const;
bool operator!=(const ClassName&) const;
bool operator<=(const ClassName&) const;
bool operator>=(const ClassName&) const;
bool operator<(const ClassName&) const;
bool operator>(const ClassName&) const;