SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWUToUnicodeConversionContext Class Reference

Specifies the default character encoding scheme to use for subsequent implicit conversions from narrow character strings to UTF-16 encoded Unicode strings. More...

#include <rw/i18n/RWUToUnicodeConversionContext.h>

Inheritance diagram for RWUToUnicodeConversionContext:
RWUConversionContext

Public Member Functions

 RWUToUnicodeConversionContext (const char *encoding=RWUConverterBase::getDefaultEncodingName())
 
 ~RWUToUnicodeConversionContext ()
 
RWUToUnicodeConvertergetConverter ()
 

Static Public Member Functions

static RWUToUnicodeConversionContextgetContext ()
 

Friends

class RWTOnlyPointer< RWUToUnicodeConversionContext >
 

Detailed Description

RWUToUnicodeConversionContext specifies the default character encoding scheme to use for subsequent implicit conversions from narrow character strings to UTF-16 encoded Unicode strings.

RWUToUnicodeConversionContext uses the resource acquisition is initialization idiom to manage an internal, per-thread stack of RWUToUnicodeConversionContext instances, each containing an RWUToUnicodeConverter object.

The top-level element of the stack defines the conversion required to translate implicitly a narrow character string into an equivalent UTF-16 encoded Unicode string.

Each RWUToUnicodeConversionContext instance contains an RWUToUnicodeConverter instance used for all relevant implicit conversions.

The RWUToUnicodeConversionContext constructor pushes a reference to the new instance onto the context stack. The RWUToUnicodeConversionContext destructor pops the instance off the context stack.

Instances of this class can only be constructed with static or automatic storage duration; dynamic allocation is not allowed. Do not create unnamed, temporary instances. The destructors for such objects pop the context off the context stack prematurely.

Example
#include <rw/i18n/RWUFromUnicodeConverter.h>
#include <rw/i18n/RWUString.h>
#include <rw/i18n/RWUToUnicodeConversionContext.h>
#include <iostream>
int main() {
// Indicate that source strings should be implicitly
// converted from US-ASCII
RWUToUnicodeConversionContext fromAscii("US-ASCII");
// NOTE! This won't work: RWUToUnicodeConversionContext("US-ASCII");
// Use implicit conversion to construct `str'
RWUString str("US-ASCII");
{
// Create a nested conversion context
RWUToUnicodeConversionContext fromIso_8859_1("ISO-8859-1");
// Use implicit conversion to initialize `str2'
RWUString str2 = " and ISO-8859-1 source: ";
str += str2;
// Nested context goes out of scope
}
// Write a Shift-JIS encoded representation of
// `str' to std::cout
RWUFromUnicodeConverter toShiftJis("Shift-JIS");
std::cout << str.toBytes(toShiftJis) << "in Shift-JIS" << std::endl;
// Original context goes out of scope
return 0;
}
Converts text from UTF-16 to various byte-oriented standard character encoding schemes.
Definition RWUFromUnicodeConverter.h:117
Stores and manipulates Unicode character sequences encoded as UTF-16 code units.
Definition RWUString.h:187
Specifies the default character encoding scheme to use for subsequent implicit conversions from narro...
Definition RWUToUnicodeConversionContext.h:109

Program output:

US-ASCII and ISO-8859-1 source: in Shift-JIS
See also
RWUToUnicodeConverter, RWUFromUnicodeConversionContext, RWUConversionContext

Constructor & Destructor Documentation

◆ RWUToUnicodeConversionContext()

RWUToUnicodeConversionContext::RWUToUnicodeConversionContext ( const char * encoding = RWUConverterBase::getDefaultEncodingName())

Constructs an RWUToUnicodeConversionContext for the specified encoding. The to-Unicode conversion context specifies the default implicit conversion to use when automatically converting a sequence of bytes, encoded accorded to the specified encoding, into a UTF-16 representation. The encoding name is encoded in US-ASCII and must specify one of the names or aliases recognized by the Internationalization Module (see RWUAvailableEncodingList and RWUEncodingAliasList).

The conversion context remains in effect until another conversion context is specified, or until the conversion context instance goes out of scope and is destroyed.

Exceptions
RWUExceptionThrown to indicate that a converter could not be constructed for the specified encoding. The exception carries one of the following status codes:

◆ ~RWUToUnicodeConversionContext()

RWUToUnicodeConversionContext::~RWUToUnicodeConversionContext ( )
inline

Destructor. Destroys self and restores the conversion context that was in effect prior to the construction of this instance.

Member Function Documentation

◆ getContext()

static RWUToUnicodeConversionContext & RWUToUnicodeConversionContext::getContext ( )
static

Returns a reference to the current RWUToUnicodeConversionContext.

Note
Using this method to access a user-defined or root context after the program has exited main() may produce unpredictable or erroneous behavior. Do not use conversion contexts during the destruction of static-duration objects.

◆ getConverter()

RWUToUnicodeConverter & RWUToUnicodeConversionContext::getConverter ( )
inline

Returns a reference to self's internal RWUToUnicodeConverter instance for use in converting strings in various encodings into UTF-16 encoded RWUString instances.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.