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.

Whatever their category, all classes have similar programming interfaces. This section highlights their common member 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:

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 C++ 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 C++ 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.

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

The member functions use the function:

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:

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 C++ API Reference Guide.

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.

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

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:

and their logical operator counterparts: