Class: TUTF8Transcoder

Declaration: UTFTranscoder.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TTranscoder

Inherited By:

None.

Purpose:

TUTF8Transcoder, derived from TTranscoder, provides transcoding between Unicode and the UTF-8 transformation of Unicode.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is designed to be used directly.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TUTF8Transcoder::TUTF8Transcoder

TUTF8Transcoder ()
TUTF8Transcoder (const TUTF8Transcoder & that)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const TUTF8Transcoder & that -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TUTF8Transcoder::~TUTF8Transcoder

virtual ~ TUTF8Transcoder ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TUTF8Transcoder::GetBufferSize

virtual TTextCount GetBufferSize (const TText & uniText, const TTextRange & uniTextRange, TTranscoder :: ETranscodingScope scope =TTranscoder :: kNoRoundTrip) const

Interface Category:

API.

Purpose:

Calculates the actual amount of storage required for a UTF-8 text string that is to be transcoded from Unicode. Requires iterating over the entire TText.

Calling Context:

Typically called before transcoding from Unicode.

Parameters:

const TText & uniText -The Unicode text to be transcoded to a UTF-8 encoding.
const TTextRange & uniTextRange -The range of the Unicode text to be transcoded.
TTranscoder :: ETranscodingScope scope =kNoRoundTrip -How the transcoding should be performed.

Return Value:

Returns a TTextCount for the size of the resulting UTF-8 character string.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

Member Function: TUTF8Transcoder::GetMaximumBytesPerCharacter

virtual TTextCount GetMaximumBytesPerCharacter (TTranscoder :: ETranscodingScope scope =TTranscoder :: kNoRoundTrip) const

Interface Category:

API.

Purpose:

Provides a quick estimate of the number of bytes required to provide storage for strings converted from Unicode.

Calling Context:

Called to quickly estimate a maximum length for the char buffer used in ExtractFromText. If the number of Unicode characters in a TText is multiplied by GetMaximumBytesPerCharacter, the result is guaranteed to produce a buffer sufficiently long for converting that TText to UTF-8 characters.

Parameters:

TTranscoder :: ETranscodingScope scope =kNoRoundTrip -Determines whether this function returns the number of bytes per single character in the UTF-8 character encoding, or the maximum number of bytes required to represent a single Unicode character in the UTF-8 character encoding (see "Return Value").

Return Value:

If the default scope (kNoRoundTrip) is used, this function returns the number of bytes per single character in the UTF-8 character encoding. If any but the default scope is used, it returns the length of the longest expansion for a single exception character in the transcoding, that is, the maximum number of bytes required to represent a single Unicode character in the UTF-8 character encoding.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

Member Function: TUTF8Transcoder::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TUTF8Transcoder::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TUTF8Transcoder::operator=

virtual TUTF8Transcoder & operator =(const TUTF8Transcoder & from)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TUTF8Transcoder & from -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TUTF8Transcoder::DoAppendToText

virtual TTextCount DoAppendToText (const unsigned char * chars, TTextCount charLength, TText & uniText, TTranscoder :: ETranscodingScope scope =TTranscoder :: kNoRoundTrip) const

Interface Category:

API.

Purpose:

A protected function called to convert UTF-8 data in chars to UniChars and append it to a TText.

Calling Context:

Called by AppendToText.

Parameters:

const unsigned char * chars -The UTF-8 text.
TTextCount charLength -The number of characters in the UTF-8 text.
TText & uniText -Receives the Unicode text.
TTranscoder :: ETranscodingScope scope -How the transcoding should be performed.

Return Value:

The number of characters that were converted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TTranscoder function.

Member Function: TUTF8Transcoder::DoExtractFromText

virtual TTextCount DoExtractFromText (const TText & uniText, const TTextRange & uniTextConversionRange, unsigned char * chars, TTextCount & charsLength, TTranscoder :: ETranscodingScope scope =TTranscoder :: kNoRoundTrip) const

Interface Category:

API.

Purpose:

A protected function called to convert UniChars in a TText to chars in a UTF-8 encoding.

Calling Context:

Called by ExtractFromText.

Parameters:

const TText & uniText -The Unicode text.
const TTextRange & uniTextConversionRange -The range to transcode.
unsigned char * chars -Receives the UTF-8 text. The string is not zero-terminated. The number of characters converted is returned in the parameter, charsLength.
TTextCount & charsLength -The maximum length of the chars buffer on input. Transcoding does not occur beyond this length. On output, this is the number of characters that were actually converted.
TTranscoder :: ETranscodingScope scope -How the transcoding should be performed.

Return Value:

The number of characters that were converted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TTranscoder function.

Member Function: TUTF8Transcoder::DoCanConvert

virtual TTextCount DoCanConvert (const TText & uniText, const TTextRange & uniTextConversionRange, TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip) const
virtual TTextCount DoCanConvert (const unsigned char * foreignText, TTextCount length, TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip) const

Interface Category:

API.

Purpose:

A protected function called to return the number of characters that can be converted from Unicode to UTF-8 text.
A protected function called to return the number of characters that can be converted to Unicode from UTF-8 text.

Calling Context:

Called by CanConvert.

Parameters:

const TText & uniText -The Unicode text.
const TTextRange & uniTextConversionRange -The range in uniText to check to see how many characters can be converted.
TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip -How the transcoding should be performed.
const unsigned char * foreignText -The non-Unicode (UTF-8 ) text.
TTextCount length -The number of characters in this text.
TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip -How the transcoding should be performed.

Return Value:

The number of characters that can be converted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TTranscoder function.

Click the icon to mail questions or corrections about this material to Taligent personnel.