Class: TMacintoshTranscoder

Declaration: Transcoding.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TTranscoder

Inherited By:

None.

Purpose:

TMacintoshTranscoder, derived from TTranscoder, provides protocol and an actual object for acquiring and using transcoders for conversion between Unicode and the Macintosh character encoding.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

There will typically be no deriving classes. Instances for specific Macintosh scripts are provided as TRuleBasedTranscoder derived classes.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TMacintoshTranscoder::SetScript

virtual void SetScript (EMacintoshScriptCode script)

Interface Category:

API.

Purpose:

Allows the client to specify a different script for Macintosh transcoding.

Calling Context:

Called before transcoding if the client wants to transcode with a different script.

Parameters:

EMacintoshScriptCode script -The new script to be used.

Return Value:

None.

Exceptions:

Throws TTranscodingException::kTranscodingNotInstalled if a transcoding cannot be found for the specified script.

Concurrency:

Multithread safe.

Other Considerations:

Actually changes the transcoding used.

Member Function: TMacintoshTranscoder::GetScript

virtual void GetScript (EMacintoshScriptCode & script) const

Interface Category:

API.

Purpose:

Returns the script for which this transcoder can be used.

Calling Context:

Called when clients want to identify the current Macintosh script for transcoding.

Parameters:

EMacintoshScriptCode & script -The script to be returned.

Return Value:

The value of the parameter script.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMacintoshTranscoder::operator=

virtual TMacintoshTranscoder & operator =(const TMacintoshTranscoder & from)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TMacintoshTranscoder & 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:

Multithread safe.

Other Considerations:

None.

Member Function: TMacintoshTranscoder::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:

Multithread safe.

Other Considerations:

None.

Member Function: TMacintoshTranscoder::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:

Multithread safe.

Other Considerations:

None.

Member Function: TMacintoshTranscoder::~TMacintoshTranscoder

virtual ~ TMacintoshTranscoder ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TMacintoshTranscoder::DoExtractFromText

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

Interface Category:

API.

Purpose:

A protected function called to convert UniChars in a TText to chars in a Macintosh character 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 Macintosh 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 =kNoRoundTrip -How the transcoding should be performed.

Return Value:

The number of characters that were converted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited TTranscoder function.

Member Function: TMacintoshTranscoder::DoAppendToText

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

Interface Category:

API.

Purpose:

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

Calling Context:

Called by AppendToText.

Parameters:

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

Return Value:

The number of characters that were converted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited TTranscoder function.

Member Function: TMacintoshTranscoder::DoCanConvert

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

Interface Category:

API.

Purpose:

A protected function called to return the number of characters that can be converted from Unicode to Macintosh text.
A protected function called to return the number of characters that can be converted to Unicode from Macintosh 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 =kFullRoundTrip -How the transcoding should be performed.
const unsigned char * foreignText -The non-Unicode (Macintosh) text.
TTextCount length -The number of characters in this text.
TTranscoder :: ETranscodingScope scope =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:

Multithread safe.

Other Considerations:

This protected function overrides the inherited TTranscoder function.

Member Function: TMacintoshTranscoder::TMacintoshTranscoder

TMacintoshTranscoder ()
TMacintoshTranscoder (EMacintoshScriptCode script)
TMacintoshTranscoder (const TMacintoshTranscoder & source)

Interface Category:

API.

Purpose:

Default constructor.
Creates a transcoder ready for transcoding with the script indicated.
Copy constructor.

Calling Context:

Called by the stream-in operators and by clients who want just the default script for the Macintosh.
Called by clients who want to specify a specific script for Macintosh transcoding.
Called to copy an object.

Parameters:

Takes no parameters.
EMacintoshScriptCode script -The Macintosh script for this transcoder.
const TMacintoshTranscoder & source -The object to copy.

Return Value:

None.

Exceptions:

Throws TTranscodingException::kTranscodingNotInstalled if a transcoding cannot be found.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMacintoshTranscoder::GetMaximumBytesPerCharacter

virtual TTextCount GetMaximumBytesPerCharacter (TTranscoder :: ETranscodingScope scope =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 Macintosh characters.

Parameters:

TTranscoder :: ETranscodingScope scope =kNoRoundTrip -Determines whether this function returns the number of bytes per single character in the Macintosh character set handled by this transcoding, or the maximum number of bytes required to represent a single Unicode character in the Macintosh 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 Macintosh character set handled by this transcoding. 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 Macintosh character set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

Member Function: TMacintoshTranscoder::GetBufferSize

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

Interface Category:

API.

Purpose:

Calculates the actual amount of storage required for a Macintosh 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 Macintosh 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 Macintosh character string.

Exceptions:

Throws TTranscodingException::kTranscodingNotInstalled if a transcoding cannot be found.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TTranscoder function.

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