Class: TTranscoder

Declaration: Transcoder.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TASCIITranscoder TMacintoshTranscoder TRuleBasedTranscoder TUTF7Transcoder TUTF8Transcoder

Purpose:

An abstract base class that defines the basic protocol for conversion of character data in a foreign (non-Unicode) encoding to and from Unicode.

Instantiation:

Abstract class; do not allocate directly.

Deriving Classes:

Derived classes are derived for each foreign encoding standard. Reasonable values for the character encoding, name, and maximum bytes per character should be maintained. Deriving classes need not implement CreateStringFromText because the default calls ExtractFromText.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTranscoder::TTranscoder

TTranscoder (const TTranscoder & copyIn)
TTranscoder ()
TTranscoder (const TToken & encoding)

Interface Category:

API.

Purpose:

Copy constructor. This constructor is protected.
Default constructor. This constructor is protected.
Initializes a transcoder for a specific encoding. This constructor is protected.

Calling Context:

Called to copy an object.
Called by the stream-in operators.
Most commonly called by derived classes.

Parameters:

const TTranscoder & copyIn -The object to copy.
Takes no parameters.
const TToken & encoding -The encoding system (for example, kMacintoshEncoding).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTranscoder::SetMaximumBytesPerCharacter

virtual void SetMaximumBytesPerCharacter (TTextCount bytes)

Interface Category:

API.

Purpose:

Allows derived classes to set the maximum bytes for foreign character value.

Calling Context:

Called by derived classes to update this value. Typically called during the editing process as rules are added.

Parameters:

TTextCount bytes -The maximum bytes required to map a single UniChar to the foreign encoding. For example, a Macintosh Roman transcoder can be created that maps Unicode characters, such as LATIN CAPITAL LETTER R HACEK, which do not exist as single characters in Macintosh Roman, into the base letter R, followed by a hacek diacritic. In this case, bytes should be 2.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTranscoder::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

The numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTranscoder::IsEqual

virtual bool IsEqual (const MCollectible * obj) const

Interface Category:

API.

Purpose:

Compares two objects for equality.

Calling Context:

Called to compare compatible objects.

Parameters:

const MCollectible * obj -The object to compare to this object.

Return Value:

Returns true if the objects match.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTranscoder::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: TTranscoder::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 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: TTranscoder::operator=

TTranscoder & operator =(const TTranscoder & from)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTranscoder & 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: TTranscoder::~TTranscoder

virtual ~ TTranscoder ()

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: TTranscoder::DoCreateStringFromText

virtual TTextCount DoCreateStringFromText (unsigned char * & string, const TText & uniText, const TTextRange & uniTextConversionRange, TTranscoder :: ETranscodingScope scope) const

Interface Category:

API.

Purpose:

A protected function called to create a null-terminated string from Unicode text. Default calls DoExtractFromText.

Calling Context:

Called by CreateStringFromText.

Parameters:

unsigned char * & string -The non-Unicode text.
const TText & uniText -The Unicode text.
const TTextRange & uniTextConversionRange -The range to transcode.
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 function is protected.

Member Function: TTranscoder::DoExtractFromText

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

Interface Category:

API.

Purpose:

A protected function called to convert UniChars in a TText to chars in foreign (non_Unicode) 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 non-Unicode 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 is a protected pure virtual function and needs to be overridden.

Member Function: TTranscoder::DoAppendToText

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

Interface Category:

API.

Purpose:

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

Calling Context:

Called by AppendToText.

Parameters:

const unsigned char * chars -The non-Unicode text.
TTextCount charLength -The number of characters in the non-Unicode 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 is a protected pure virtual function and needs to be overridden.

Member Function: TTranscoder::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 the particular type of non-Unicode text managed by the derived class implementing this function.
A protected function called to return the number of characters that can be converted to Unicode from the particular type of non-Unicode text managed by the derived class implementing this function.

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 text.
TTextCount length -The number of characters in this text.
TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip -How the transcoding should be performed.

Parameters:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTranscoder::CanConvert

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

Interface Category:

API.

Purpose:

A fast way of determining the number of UniChars in the parameter uniText that can be converted to foreign encoding with the given scope.
A fast way of determining the number of characters in foreignText that can be converted to Unicode with the given scope.
A fast way of determining the number of characters in foreignText that can be converted to Unicode with the given scope.
A fast way of determining the number of characters in foreignText that can be converted to Unicode with the given scope.

Calling Context:

Called before transcoding to select a transcoder that can convert the largest number of characters from Unicode. Can also be used, for example, to warn users that characters typed into a dialogue cannot all be converted from Unicode.
Called before transcoding to select a transcoder that can convert the largest number of characters to Unicode.
Called before transcoding to select a transcoder that can convert the largest number of characters to Unicode.
Called before transcoding to select a transcoder that can convert the largest number of characters to Unicode.

Parameters:

const TText & uniText -The Unicode characters to be converted to a foreign encoding.
const TTextRange & uniTextConversionRange -The range of the Unicode characters to be converted.
TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip -How the transcoding should be performed.
const unsigned char * foreignText -The non-Unicode characters to be converted to Unicode.
TTextCount length -The length of the non-Unicode characters.
TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip -How the transcoding should be performed.
const signed char * foreignText -The non-Unicode characters to be converted to Unicode.
TTextCount length -The length of the non-Unicode characters.
TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip -How the transcoding should be performed.
const char * foreignText -The non-Unicode characters to be converted to Unicode.
TTextCount length -The length of the non-Unicode characters.
TTranscoder :: ETranscodingScope scope =TTranscoder :: kFullRoundTrip -How the transcoding should be performed.

Return Value:

The index of the first character that cannot be converted or the length of the string if all characters can be converted.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTranscoder::CreateStringFromText

TTextCount CreateStringFromText (unsigned char * & string, const TText & uniText, const TTextRange & uniTextConversionRange =TTextRange :: GetMaximumRange (), TTranscoder :: ETranscodingScope scope =kNoRoundTrip) const
TTextCount CreateStringFromText (signed char * & string, const TText & uniText, const TTextRange & uniTextConversionRange =TTextRange :: GetMaximumRange (), TTranscoder :: ETranscodingScope scope =kNoRoundTrip) const
TTextCount CreateStringFromText (char * & string, const TText & uniText, const TTextRange & uniTextConversionRange =TTextRange :: GetMaximumRange (), TTranscoder :: ETranscodingScope scope =kNoRoundTrip) const

Interface Category:

API.

Purpose:

Provides an interface for transcoding from Unicode to unsigned char that frees clients from the details of computing and allocating storage for foreign chars.
Provides an interface for transcoding from Unicode to signed char that frees clients from the details of computing and allocating storage for foreign chars.
Provides an interface for transcoding from Unicode to char that frees clients from the details of computing and allocating storage for foreign chars.

Calling Context:

Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

unsigned char * & string -A zero-terminated unsigned char string containing the converted UniChars. The transcoder creates it and the caller must delete it.
const TText & uniText -The source UniChars to be converted to a foreign character set.
const TTextRange & uniTextConversionRange =TTextRange :: kMaximumRange -The range of the UniChars to be converted. The default value causes the full text to be converted.
TTranscoder :: ETranscodingScope scope =kNoRoundTrip -How the transcoding should be performed.
signed char * & string -A zero-terminated signed char string containing the converted UniChars.
const TText & uniText -The source UniChars to be converted to a foreign character set.
const TTextRange & uniTextConversionRange =TTextRange :: kMaximumRange -The range of the UniChars to be converted. The default value causes the full text to be converted.
TTranscoder :: ETranscodingScope scope =kNoRoundTrip -How the transcoding should be performed.
char * & string -A zero-terminated char string containing the converted UniChars.
const TText & uniText -The source UniChars to be converted to a foreign character set.
const TTextRange & uniTextConversionRange =TTextRange :: kMaximumRange -The range of the UniChars to be converted. The default value causes the full text to be converted.
TTranscoder :: ETranscodingScope scope =kNoRoundTrip -How the transcoding should be performed.

Return Value:

TTextCount is the actual length of the converted foreign chars. The chars are returned in the string parameter.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTranscoder::ExtractFromText

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

Interface Category:

API.

Purpose:

Converts Unicode characters in TText to foreign encoding in unsigned char*.
Converts Unicode characters in TText to foreign encoding in signed chars.
Converts Unicode characters in TText to foreign encoding in chars.

Calling Context:

Typically called when exporting text out of the Taligent system or to subsystems that require a non-Unicode interface. The caller has complete control over the output char buffer. This is so that successive calls can be made efficiently by copying the output into a fixed size buffer. Where storage management is not a concern, use CreateStringFromText.

Called to transcode unsigned char* data.
Called to transcode signed char* data.
Called to transcode char* data.

Parameters:

const TText & uniText -The source TText containing the UniChar string to be converted.
const TTextRange & uniTextConversionRange -The range of UniChars in the TText that are to be converted.
unsigned char * chars -A pointer to the string of chars to be filled in by ExtractFromText. The caller must create and delete the string. 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.
const TText & uniText -The source TText containing the UniChar string to be converted.
const TTextRange & uniTextConversionRange -The range of UniChars in the TText that are to be converted.
signed char * chars -A pointer to the string of chars to be filled in by ExtractFromText.
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.
const TText & uniText -The source TText containing the UniChar string to be converted.
const TTextRange & uniTextConversionRange -The range of UniChars in the TText that are to be converted.
char * chars -A pointer to the string of chars to be filled in by ExtractFromText.
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 UniChars converted. If this is less than the original length of the TText parameter, the caller might want to call ExtractFromText again.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTranscoder::AppendToText

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

Interface Category:

API.

Purpose:

Converts a string of unsigned char from a foreign encoding to Unicode and appends to the TText parameter.
Converts a string of signed char from a foreign encoding to Unicode and appends to the TText parameter.
Converts a string of char from a foreign encoding to Unicode and appends to the TText parameter.

Calling Context:

Typically called when importing non-Unicode unsigned char* data into the Taligent system.
Typically called when importing non-Unicode signed char data into the Taligent system.
Typically called when importing non-Unicode char data into the Taligent system.

Parameters:

const unsigned char * chars -The source foreign character string.
TTextCount charLength -The byte length of the foreign character string.
TText & uniText -The TText that will contain the converted Unicodes. Note that UniChars are appended to uniText.
TTranscoder :: ETranscodingScope scope =kNoRoundTrip -How the conversion should be performed. If scope =kNoRoundTrip (the default) the entire input string is converted in one pass. Characters for which conversions do not exist in the table or that cannot be mapped one-to-one are converted as missing characters (TGeneralPunctuation::kReplacementCharacter). If scope =kPartialRoundTrip or kFullRoundTrip, then extra processing is done to manage the composition or decomposition of characters. Conversion stops at the first character for which there is no mapping to allow a substitute table to be used.
const signed char * chars -The source foreign character string.
TTextCount charLength -The byte length of the foreign character string.
TText & uniText -The TText that will contain the converted Unicodes.
TTranscoder :: ETranscodingScope scope =kNoRoundTrip -How the conversion should be performed.
const char * chars -The source foreign character string.
TTextCount charLength -The byte length of the foreign character string.
TText & uniText -The TText that will contain the converted Unicodes.
TTranscoder :: ETranscodingScope scope =kNoRoundTrip -How the conversion should be performed.

Return Value:

Returns TTextCount for the number of foreign chars actually converted. If this number is less than charLength, then the client should call AppendToText for another pass. The converted UniChars are returned in the TText parameter.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

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