International Features of the Streams Package

Advanced Tools Module User’s Guide : PART II Advanced Tools Module Packages : Chapter 8 International Features of the Advanced Tools Module : International Features of the Streams Package

This section discusses using the Streams package with and without the Internationalization Module. To determine if you need to use the Internationalization Module, see “Determining your Character Encoding Needs.”

Using the Streams Package without the Internationalization Module

The Streams package provides a number of Unicode-based streams that allow you to stream data in a Unicode format. See Advanced Tools Module | Streams on the Modules tab of the SourcePro API Reference Guide for specific APIs.

Unicode-Based Stream Classes

• RWUCharArrayOutputStream and RWUCharArrayOutputStreamImp

Handle and body output stream classes that allow retrieval of their data as a Unicode character array.

• RWUCharFromByteInputStreamImp and RWUCharToByteOutputStreamImp

Concrete input and output stream classes connecting a Unicode character stream to a binary stream.

• RWUCharInputStream and RWUCharInputStreamImp

Handle and abstract base class for all the Unicode character input stream implementation classes.

• RWUCharOutputStream and RWUCharOutputStreamImp

Handle class and abstract base class for all the Unicode character output stream implementation classes.

• RWUCharToUTF8ByteOutputStreamImp and RWUCharFromUTF8ByteInputStreamImp

Concrete input and output stream classes connecting a Unicode character stream to a binary stream using UTF-8.

• RWUTF8Helper

Class used to encode and decode UTF-8 sequences.

Unicode Converter Classes

RWToUTF8Converter and RWFromUTF8Converter provide character encoding conversions between UTF-8 and UTF-16. These classes use the same interface as the converters in the Internationalization Module, but do not require that module.

NOTE >>	To perform conversions to or from character encodings other than UTF-8 and UTF-16, you will need the Internationalization Module.

These classes also provide interfaces for the RWUChar type and for wchar_t. (RWUChar is a typedef for unsigned short and is used by the Streams package to represent UTF-16 characters.) If you are using these types, use these classes for your conversions between UTF-8 and UTF-16.

However, if you are performing conversions that do not require the RWUChar or wchar_t interface, we recommend that you use instead RWBasicUString and its conversion utilities. For more information, see “Choosing the Appropriate String Class.”

Example

The following examples illustrate how to perform conversions using RWFromUTF8Converter and RWToUTF8Converter.

• Converting from UTF-8 to UTF-16

RWWString destination; // 1

RWCString source(“My UTF8 characters”);

RWFromUTF8Converter converter; // 2

converter.convert(source,destination); // 3

//1 Start with an empty RWWString and an RWCString containing UTF-8 encoded characters.

//2 Create the RWFromUTF8Converterconverter object.

//3 Call the convert() function on RWFromUTF8Converter with the source and destination strings as parameters. After this call, the destination local variable will contain the source string encoded in UTF-16.

• Converting from UTF-16 to UTF-8

RWWString newSource(destination);

RWCString newDestination; // 1

RWToUTF8Converter converter; // 2

converter.convert(newSource,newDestination); // 3

//1 Create a new empty RWCString newDestination and a new RWWString source initialized with the result of the previous conversion.

//2 Create the RWToUTF8Converter object.

//3 Call the convert() function on RWToUTF8Converter with the newSource and newDdestination strings as parameters. After this call, the newDestination local variable will contain an exact replica of the source string re-encoded in UTF-8.

Using the Streams Package with the Internationalization Module

If you wish to convert a string that will be inserted into a stream to a character encoding other than US-ASCII, UTF-8 or UTF-16, you will require the Internationalization Module.

The Internationalization Module converts to and from any supported character encoding to UTF-16. This conversion allows you to write applications in character encodings that require a wide character format (16-bits or greater), such as some Chinese and Japanese character encodings.

In some cases, you will be required to convert these UTF-16 strings and to UTF-8 for use in other SourcePro modules. See the relevant User’s Guide for each module’s requirements.

For more information on the supported character encodings, or other information on internationalization and localization of your applications, see the Internationalization Module User’s Guide.