The Rogue Wave classes include four types of classes that specialize RWvistream and RWvostream. The first uses a portable ASCII formatting, the second and third a binary formatting, and the fourth an XDR formatting (eXternal Data Representation, a SunMicrosytems standard):

The portable ASCII versions store their inserted items in an ASCII format that escapes special characters (such as tabs, newlines, etc.) in such a manner that they will be restored properly, even under a different operating system. The binary versions do not reformat inserted items, but store them instead in their native format. The endian versions allow for the space and time efficiency of binary format, but can store or retrieve the information in big endian, little endian, or native format. XDR versions send their items to an XDR stream, to be transmitted remotely over a network.

None of these versions retain any state: they can be freely interchanged with regular streams, including XDR. Using them does not lock you into doing all your file I/O with them. For more information, see the respective entries in the Class Reference.

Here's a simple example that exercises RWbostream and RWbistream through their respective abstract base classes, RWvostream and RWvistream:

#include <rw/bstream.h>
#include <rw/cstring.h>
#include <fstream.h>
 
#ifdef __BORLANDC__
# define MODE ios::binary                                   // 1
#else
# define MODE 0
#endif
 
void save(const RWCString& a, RWvostream& v){
  v << a;                    // Save to the virtual output stream
}
 
RWCString recover(RWvistream& v) {
   RWCString dupe;
   v >> dupe;           // Restore from the virtual input stream
   return dupe;
}
 
main(){
   RWCString a("A string with\ttabs and a\nnewline.");
 
   {
     ofstream f("junk.dat", ios::out|MODE);                  // 2
     RWbostream bostr(f);                                    // 3
     save(a, bostr);
   }                                                         // 4
 
   ifstream f("junk.dat", ios::in|MODE);                     // 5
   RWbistream bistr(f);                                      // 6
   RWCString b = recover(bistr);                             // 7
 
   cout << a << endl;  // Compare the two strings            // 8
   cout << b << endl;
   return 0;
}

Program Output::

A string with   tabs and a
newline.
A string with   tabs and a
newline.

The job of function save(const RWCString& a, RWvostream& v) is to save the string a to the virtual output stream v. Function recover(RWvistream&) restores the results. These functions do not know the ultimate format with which the string will be stored. Here are some additional comments on particular lines:

You could simplify this program by using class fstream, which multiply inherits ofstream and ifstream, for both output and input. A seek to beginning-of-file would occur before reading the results back in. Since some early implementations of seekg() have not proven reliable, the simpler approach was not chosen for this example.

In the previous section, you saw how the virtual streams facility abstracts the formatting of items inserted into the stream. The disposition of the items inserted into the streams has also been made abstract: it is set by the type of streambuf used.

Class streambuf is the underlying sequencing layer of the iostreams facility. It is responsible for producing and consuming sequences of characters. Your compiler comes with several versions. For example, class filebuf ultimately gets and puts its characters to a file. Class strstreambuf gets and puts to memory-based character streams; you can think of it as the iostream equivalent to ANSI-C's sprintf() function. Now Tools.h++ adds two Windows-based extensions:

These classes take care of the details of allocating and reallocating memory from Windows as buffers overflow and underflow. In the case of class RWDDEstreambuf, the associated DDEDATA header is also filled in for you. Any class that inherits from class ios can be used with these streambufs, including the familiar istream and ostream, as well as the Rogue Wave virtual stream classes.

The result is that the same code that is used to store a complex structure to a conventional disk-based file, for example, can also be used to transfer that structure through the DDE facility to another application!

Let's look at a more complicated example of how you might use class RWDDEstreambuf to exchange an RWBinaryTree through the Windows DDE facility. You would use a similar technique for the Windows Clipboard.

#include <rw/bintree.h>
#include <rw/collstr.h>
#include <rw/bstream.h>
#include <rw/winstrea.h>
#include <windows.h>
#include <dde.h>
 
BOOL
PostCollection(HWND hwndServer, WORD cFormat){
   RWBinaryTree sc;                                         // 1
   sc.insert(new RWCollectableString("Mary"));
   sc.insert(new RWCollectableString("Bill"));
   sc.insert(new RWCollectableString("Pierre"));
 
   // Allocate an RWDDEstreambuf and use it to initialize
   // an RWbostream:
   RWDDEstreambuf* sbuf = new RWDDEstreambuf(cFormat,       // 2
                                             FALSE,          // 3
                                             TRUE,           // 4
                                             TRUE);          // 5
   RWbostream bostr( sbuf );                                 // 6
 
   // Store the collection to the RWbostream:
   bostr << sc;                                              // 7
 
   // Lock the output stream, and get its handle:
   HANDLE hDDEData = sbuf->str();                            // 8
 
   // Get an atom to identify the DDE Message:
   ATOM atom = GlobalAddAtom("SortedNames");                 // 9
 
   // Post the DDE response:
   return PostMessage(0xFFFF, WM_DDE_DATA, hwndServer,       //10
                      MAKELONG(hDDEData, atom));
}

In the code above, the large memory model has been assumed. Here's the line-by-line description:

A similar and actually simpler technique can be used for Clipboard exchanges.

Note that there is nothing that constrains you to use the specialized streambufs RWCLIPstreambuf and RWDDEstreambuf with only the Rogue Wave virtual streams facility. You could quite easily use them with regular istreams and ostreams; you just wouldn't be able to set the formatting at run time.

Classes RWDDEstreambuf and RWCLIPstreambuf specialize streambuf to hand off the characters according to the Windows API. But there are other useful specializations of a streambuf. Class RWAuditStreamBuffer allows you to count the bytes of any stream, while optionally calling a function of your choice for each character. See the code example in the Class Reference.

In this section, you have seen how an object can be stored to and recovered from a stream without regard for the final destination of the bytes of that stream, whether memory or disk. You have also seen that you need not be concerned with the final formatting of the stream, whether ASCII or binary.

You can also write your own specializing virtual stream class, much like RWpostream and RWpistream. The great advantage of the virtual streams facility is that, if you do write your own specialized virtual stream, you don't have to modify any of the code of the client classes—you just use your stream class as an argument to:

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

In addition to storing and retrieving an object to and from virtual streams, all of the classes can store and retrieve themselves in binary to and from an RWFile. This file encapsulates ANSI-C style file I/O. Although more limited in its abilities than stream I/O, this form of storage and retrieval is slightly faster to and from disk because the virtual dispatching machinery is not needed.