SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWUFromUnicodeConversionContext Class Reference

Specifies the character encoding scheme to use for default conversions from UTF-16 strings into another encoding. More...

#include <rw/i18n/RWUFromUnicodeConversionContext.h>

Inheritance diagram for RWUFromUnicodeConversionContext:
RWUConversionContext

Public Member Functions

 RWUFromUnicodeConversionContext (const char *encoding=RWUConverterBase::getDefaultEncodingName())
 
 ~RWUFromUnicodeConversionContext ()
 
RWUFromUnicodeConvertergetConverter ()
 

Static Public Member Functions

static RWUFromUnicodeConversionContextgetContext ()
 

Friends

class RWTOnlyPointer< RWUFromUnicodeConversionContext >
 

Detailed Description

RWUFromUnicodeConversionContext specifies the character encoding scheme to use for subsequent implicit conversions from UTF-16 encoded Unicode strings into another encoding.

RWUFromUnicodeConversionContext uses the resource acquisition is initialization idiom to manage internal, per-thread stacks of RWUFromUnicodeConversionContext instances, each containing an RWUFromUnicodeConverter object. The RWUFromUnicodeConversionContext constructor pushes a reference to the new instance onto the context stack. The RWUFromUnicodeConversionContext destructor pops the instance off the context stack. The top-level element of each thread's stack defines the conversion required to translate implicitly a UTF-16 encoded Unicode string into another encoding.

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/RWUFromUnicodeConversionContext.h>
#include <rw/i18n/RWUString.h>
#include <rw/i18n/RWUToUnicodeConverter.h>
#include <iostream>
int main() {
// Indicate that strings should be implicitly converted
// to ISO-8859-1 when output to std::cout.
RWUFromUnicodeConversionContext toIso_8859_1("ISO-8859-1");
// NOTE! This won't work: RWUFromUnicodeConversionContext("ISO-8859-1");
// Use explicit conversion to construct `str'
RWUToUnicodeConverter fromAscii("US-ASCII");
RWUString str("US-ASCII source: ", fromAscii);
// Write an ISO-8859-1 encoded representation of
// `str' to std::cout
std::cout << str << "in ISO-8859-1" << std::endl;
{
// Create a nested conversion context
RWUFromUnicodeConversionContext toShiftJis("Shift-JIS");
// Write a Shift-JIS encoded representation of
// `str' to std::cout
std::cout << str << "in Shift-JIS" << std::endl;
// Nested context goes out of scope
}
// Original context goes out of scope
return 0;
}
Specifies the character encoding scheme to use for default conversions from UTF-16 strings into anoth...
Definition RWUFromUnicodeConversionContext.h:102
Stores and manipulates Unicode character sequences encoded as UTF-16 code units.
Definition RWUString.h:187
Provides unidirectional text conversion from strings in various encodings to UTF-16-encoded RWUString...
Definition RWUToUnicodeConverter.h:152

Program output:

US-ASCII source: in ISO-8859-1
US-ASCII source: in Shift-JIS
See also
RWUFromUnicodeConverter, RWUToUnicodeConversionContext, RWUConversionContext

Constructor & Destructor Documentation

◆ RWUFromUnicodeConversionContext()

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

Constructs an RWUFromUnicodeConversionContext for the specified encoding. The from-Unicode conversion context specifies the converter to use when implicitly converting a sequence of UTF-16 code units into a sequence of bytes encoded according to the specified encoding.

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:

◆ ~RWUFromUnicodeConversionContext()

RWUFromUnicodeConversionContext::~RWUFromUnicodeConversionContext ( )
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 RWUFromUnicodeConversionContext & RWUFromUnicodeConversionContext::getContext ( )
static

Returns a reference to the current RWUFromUnicodeConversionContext.

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()

RWUFromUnicodeConverter & RWUFromUnicodeConversionContext::getConverter ( )
inline

Returns a reference to the internal RWUFromUnicodeConverter instance used in converting UTF-16 encoded strings to another encoding.

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