Class: TUTF7Transcoder

Declaration: UTFTranscoder.h

Taxonomy Categories:

Member Functions:


Interface Category:

API.

Inherits From:

TTranscoder

Inherited By:

None.

Purpose:

TUTF7Transcoder, derived from TTranscoder, provides transcoding between Unicode and the UTF-7 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: TUTF7Transcoder::TUTF7Transcoder

  1. TUTF7Transcoder ()
  2. TUTF7Transcoder (bool doOptional)
  3. TUTF7Transcoder (const TUTF7Transcoder & that)

Interface Category:

API.

Purpose:

  1. Default constructor.
  2. Creates a constructor that uses ASCII character output instead of encoding output in UTF-7.
  3. Copy constructor.

Calling Context:

  1. Called by the stream-in operators.
  2. Called to create the constructor.
  3. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Refer to RFC 1641 for a detailed definition of UTF-7.

Member Function: TUTF7Transcoder::~TUTF7Transcoder

virtual ~ TUTF7Transcoder ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TUTF7Transcoder::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-7 text string that is to be transcoded from Unicode. Requires iterating over the entire TText.

Calling Context:

Typically called before transcoding from Unicode.

Parameters:

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

Member Function: TUTF7Transcoder::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-7 characters.

Parameters:

Return Value:

If the default scope (kNoRoundTrip) is used, this function returns the number of bytes per single character in the UTF-7 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-7 character encoding.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

Member Function: TUTF7Transcoder::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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: TUTF7Transcoder::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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: TUTF7Transcoder::operator=

virtual TUTF7Transcoder & operator =(const TUTF7Transcoder & from)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

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: TUTF7Transcoder::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-7 data in chars to UniChars and append it to a TText.

Calling Context:

Called by AppendToText.

Parameters:

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: TUTF7Transcoder::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-7 encoding.

Calling Context:

Called by ExtractFromText.

Parameters:

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: TUTF7Transcoder::DoCanConvert

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

Interface Category:

API.

Purpose:

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

Calling Context:

Called by CanConvert.

Parameters:

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.
Copyright©1995 Taligent,Inc. All rights reserved.