Class: TASCIITranscoder

Declaration: Transcoder.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TTranscoder

Inherited By:

None.

Purpose:

TASCIITranscoder, derived from TTranscoder, provides transcoding between Unicode and 7-bit ASCII.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

There is no need to derive from TASCIITranscoder.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TASCIITranscoder::operator=

virtual TASCIITranscoder & operator =(const TASCIITranscoder & from)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TASCIITranscoder & 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: TASCIITranscoder::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 is streamed 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: TASCIITranscoder::operator>>=

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

Interface Category:

API.

Purpose:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object is streamed 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: TASCIITranscoder::~TASCIITranscoder

virtual ~ TASCIITranscoder ()

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: TASCIITranscoder::TASCIITranscoder

TASCIITranscoder ()
TASCIITranscoder (const TASCIITranscoder & that)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and directly to instantiate this class.
Called to copy an object.

Parameters:

Takes no parameters.
const TASCIITranscoder & 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: TASCIITranscoder::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 an ASCII 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 ASCII 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: TASCIITranscoder::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 ASCII data in chars to UniChars and append it to a TText.

Calling Context:

Called by AppendToText.

Parameters:

const unsigned char * chars -The ASCII text.
TTextCount charLength -The number of characters in ASCII 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: TASCIITranscoder::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 ASCII text.
A protected function called to return the number of characters that can be converted to Unicode from ASCII 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 (ASCII ) 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.

Member Function: TASCIITranscoder::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 7-bit ASCII characters.

Parameters:

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

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

Member Function: TASCIITranscoder::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 an ASCII 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 an ASCII 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 ASCII character string.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

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