Output Example
The first example shows how to create and use a chain of streaming elements. It creates a Unicode character output stream that encodes UTF-16 characters using the UCS Transformation Format 8-bit form (UTF-8). The UTF-8 Unicode stream is connected to a buffered binary output stream that sends the transformed bytes to a file:
The class RWUCharToUTF8ByteOutputStreamImp converts the UTF-16 characters to the UCS Transformation Format 8-bit form (UTF-8). The class RWBufferedByteOutputStreamImp is connected to class RWByteToStreambufOutputStreamImp to provide the buffered byte output stream. Figure 13 is a representation of the chain of streaming elements used in this example.
Figure 13 – Streaming elements—output stream
The complete example is located in directory ...\examples\stream in the file UnicodeCharacterFilteredWrite.cpp. Only part of the code is presented below.
RWUChar array[17]= {0x0F00, 0x0F13, 0x0F0A, 0x0F3B, 0x0F8A, 0x0F68,
0x0F35, 0x0F61, 0x0F43, 0x0F39, 0x0F7F, 0x0F1E,
0x0F86, 0x0FA4, 0x0F91, 0x0F88, 0x0F0F}; // 1
// initialize the array of UTF-16 character
filebuf fbuf; // 2
fbuf.open("UnicodeCharacterFilteredWrite.dat", ios::out |
ios::binary);
RWByteOutputStream binOutputStream =
RWByteToStreambufOutputStreamImp::make(fbuf); // 3
RWByteOutputStream bufferedBinOutputStream=
RWBufferedByteOutputStreamImp::make(binOutputStream,1024); // 4
RWUCharOutputStream UTF8OutputStream=
RWUCharToUTF8ByteOutputStreamImp::make(bufferedBinOutputStream);// 5
try {
RWSize i;
for(i=0; i<17; i++)
UTF8OutputStream << array[i]; // 6
for(i=0; i<17; i++)
UTF8OutputStream.write(array[i]); // 7
UTF8OutputStream.write(array,17); // 8
}
catch(const RWIncompleteStreamOperation& e) { // 9
cout << e.why() << endl;
cout << e.elementsProcessed() << endl;
}
catch(const RWExternalStreamException& e) {
cout << e.why() << endl;
}
//1 Stores UTF-16 characters using type RWUChar, which is a typedef for unsigned short. In this example, 17 UTF-16 characters, which are part of the Tibetan Unicode character set, are stored.
//2 Creates an iostreams file buffer, and opens it in output mode. If the code is compiled on a PC platform, the file buffer needs to be opened in binary mode by specifying the flag ios::binary. If you built the Advanced Tools Module with the Standard iostreams library, you need to qualify filebuf and other iostreams elements with std::, or you need to include using declarations. The complete example code makes use of macros defined by the Essential Tools Module in order to support both the classic and Standard iostreams.
//3 Creates a concrete instance of class RWByteToStreambufOutputStreamImp. The class is created by calling its static member function make(), which creates an instance of self and returns it as a binary output stream handle. In this example, the make() function takes a reference to an iostreams streambuf object that is used as the sink of bytes.
//4 Creates a concrete instance of class RWBufferedByteOutputStreamImp. The class is created by calling one of its static member functions make(), which creates an instance of self and returns it as a binary output stream handle. Several static make() functions are available to construct an instance of class RWBufferedByteOutputStreamImp. All take a handle to the next streaming element, which must be of type RWByteOutputStream. The static make() function in this example takes a second parameter that specifies the size of the buffer to be allocated.
//5 Creates a concrete instance of class RWUCharToUTF8ByteOutputStreamImp. The class is created by calling its static member function make(), which creates an instance of self and returns it as a UTF-16 output stream handle. The make() function takes a handle to the next streaming element, which must be of type RWByteOutputStream. It is used as a sink for the bytes generated when converting UTF-16 characters to the UTF-8 form.
//6 Inserts single UTF-16 characters into the stream. Insertion operations can be cascaded as in the following example which inserts the array’s first three UTF-16 characters into the stream, and then the manipulator rwFlush triggers the stream flushing.
UTF8OutputStream << array[0] << array[1] << array[2] << rwFlush;
//7 Inserts single UTF-16 characters into the stream.
//8 Inserts an array of UTF-16 characters into the stream.
//9 Catches exceptions potentially thrown by the stream. The Streams package defines two exception classes: RWExternalStreamException and RWIncompleteStreamOperation.
Class RWExternalStreamException returns an error message and an error code. Class RWIncompleteStreamOperation inherits from class RWExternalStreamException and is thrown when an operation partially succeeds. In the above example, writing an array of UTF-16 characters might fail after writing some of the characters. An instance of class RWIncompleteStreamOperation can be queried for the number of elements successfully written. For more information on exceptions, see Error Handling.
