Class: TTransliterator

Declaration: Transliterate.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

THexTransliterator TRuleBasedTransliterator

Purpose:

TTransliterator is an abstract base class that transforms text based upon well-defined rules or an algorithm. Derived classes of TTransliterator can be used to perform intra-script transformation, such as accent composition and upper or lower casing, or inter-script phonetic transcription. Inter-script transliteration provides an alternative way of entering non-Roman text. For example, instead of using a Hebrew keyboard, Hebrew text can be entered with an American keyboard using Roman to Hebrew transliteration. This class is also used to aid typing by providing smart quotes and other punctuation modifiers. TTransliterator provides functions for translating text as well as reversing the effect. These functions must be overridden by the concrete derived classes. TTransliterator is designed to enable chaining multiple objects together. One or more such objects can work within the editable text classes to allow for transliteration during typing input.

Instantiation:

TTransliterator is an abstract class and cannot be instantiated directly.

Deriving Classes:

TTransliterator is an abstract class. Derived classes should override the pure virtual member functions to provide the translation mechanism.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTransliterator::~TTransliterator

virtual ~ TTransliterator ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTransliterator::GetMaxExpandFactor

virtual TTextCount GetMaxExpandFactor () const

Interface Category:

API.

Purpose:

Returns the maximum expansion possible for this transliterator when doing forward translation. For example, if any single character can turn into four characters, the expansion factor is 4.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

Takes no parameters.

Return Value:

The expansion factor.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is pure virtual. The maximum expansion cannot exceed 256 characters.

Member Function: TTransliterator::GetMaxBackExpandFactor

virtual TTextCount GetMaxBackExpandFactor () const

Interface Category:

API.

Purpose:

Return the maximum expansion possible for this transliterator when doing backward translation. For example, if any single character can turn into four characters, the expansion factor is 4.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

Takes no parameters.

Return Value:

The expansion factor.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is pure virtual. The maximum expansion cannot exceed 256 characters.

Member Function: TTransliterator::GetName

virtual void GetName (TLocalizableName & name) const

Interface Category:

API.

Purpose:

Gets the localizable name of this transliterator.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

TLocalizableName & name -The localizable name of this transliterator.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTransliterator::SetName

virtual void SetName (const TLocalizableName & name)

Interface Category:

API.

Purpose:

Specifies the localizable name of this transliterator.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

const TLocalizableName & name -The localizable name of this transliterator.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTransliterator::operator=

TTransliterator & operator =(const TTransliterator & tran)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

const TTransliterator & tran -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: TTransliterator::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

This function is designed to be called directly and has no special requirements.

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

This function is designed to be called directly and has no special requirements.

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

TTransliterator ()
TTransliterator (const TTransliterator & tran)
TTransliterator (const TLocalizableName & name)

Interface Category:

API.

Purpose:

Default constructor. This constructor is protected.
Copy constructor. This constructor is protected.
Constructs a transliterator with a particular name. Finds a transliterator with this name. If not found, constructs an empty one with the argument as its name. This constructor is protected.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

Takes no parameters.
const TTransliterator & tran -The object to copy.
const TLocalizableName & name -The name of the transliterator to construct.

Member Function: TTransliterator::TranslateInline

virtual bool TranslateInline (const TText & currentText, const TTextRange & newRange, const TText & newText, TText & replacementText, TTextRange & replacementRange) const
virtual bool TranslateInline (TText & currentText, const TTextRange & newRange, const TText & newText, TTextRange & replacementRange, TTextCount & numNewChars) const

Interface Category:

API.

Purpose:

Invoked for inline transliteration such as when the user is typing. Returns the replacement text and range so that the caller can edit the input text.
Similar to the first function, except that the text is changed directly.

Calling Context:

This function is designed to be called directly and has no special requirements.

Parameters:

const TText & currentText -The text in the document before user input.
const TTextRange & newRange -The range in currentText indicating where new text is to be inserted, including any backspaces. Note: newRange.GetCount is defined to be the number of deletions, and newRange.GetEnd is defined to be the insertion point relative to currentText.
const TText & newText -New user input.
TText & replacementText -Text to be inserted into the text to modify it.
TTextRange & replacementRange -The range in currentText that should be replaced.
TText & currentText -Text in the document before user input. This argument will be modified directly.
const TTextRange & newRange -The range indicating where new text is to be inserted, including any backspaces. Note: newRange.GetLength is defined to be the number of deletions, and newRange.GetEnd is defined to be the insertion point relative to currentText.
const TText & newText -New user input.
TTextRange & replacementRange -The range in currentText that was replaced.
unsigned long & numNewChars -The number of new characters introduced by the translation process.

Return Value:

Returns true if translation was performed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

By default, the second function calls the first, which calls DoTranslate. These functions should not be overridden. Instead, override DoTranslate to change behavior.

Member Function: TTransliterator::TranslateBack

virtual bool TranslateBack (TText & text) const
virtual bool TranslateBack (const TText & sourceText, const TTextRange & sourceRange, TText & replacementText, TTextRange & replacementRange) const
virtual bool TranslateBack (TText & sourceText, const TTextRange & sourceRange, TTextRange & replacementRange, TTextCount & numNewChars) const

Interface Category:

API.

Purpose:

This function directly translates back the specified text object.
Given a text object (sourceText) and a range within it (sourceRange), this function returns the replacement (translated back) text and range.
Given a text object and a range within it, this function calls DoTranslateBack to directly change the text object and return the range replaced and the number of new characters inserted.

Calling Context:

This function is designed to be called directly and has no special requirements. It is also called internally by functions such as TranslateInline.

Parameters:

TText & text -The text to translate back.
const TText & sourceText -The text to translate back.
const TTextRange & sourceRange -The range in the sourceText to translate back.
TText & replacementText -The replacement text.
TTextRange & replacementRange -The range in sourceText that should be replaced.
TText & sourceText -The text to translate back.
const TTextRange & sourceRange -The range in the sourceText to translate back.
TTextRange & replacementRange -The range in sourceText that was replaced.
TTextCount & numNewChars -The number of new characters introduced during the translation.

Return Value:

Returns true if translation back was performed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The first and second functions call the third by default. Note that it is not always possible to reverse the translation effect and return the text to its original state, so the result will sometimes be an approximation of the original. Also, in some derived classes, reverse translation does not make sense. In such cases, the third TranslateBack should be overridden to do nothing.

Member Function: TTransliterator::Translate

virtual bool Translate (TText & text) const
virtual bool Translate (const TText & sourceText, const TTextRange & sourceRange, TText & replacementText, TTextRange & replacementRange) const
virtual bool Translate (TText & sourceText, const TTextRange & sourceRange, TTextRange & replacementRange, TTextCount & numNewChars) const

Interface Category:

API.

Purpose:

This function directly translates the specified text object.
Given a text object (sourceText) and a range within it (sourceRange), this function returns the replacement text and range.
Given a text object and a range within it, this function calls DoTranslate to directly change the text object and return the range replaced and the number of new characters inserted.

Calling Context:

This function is designed to be called directly and has no special requirements. It is also called internally by functions such as TranslateInline.

Parameters:

TText & text -The text to translate.
const TText & sourceText -The text to translate.
const TTextRange & sourceRange -The range in the sourceText to translate.
TText & replacementText -The replacement text.
TTextRange & replacementRange -The range in sourceText that should be replaced.
TText & sourceText -The text to translate.
const TTextRange & sourceRange -The range in the sourceText to translate.
TTextRange & replacementRange -The range in sourceText that was replaced.
TTextCount & numNewChars -The number of new characters introduced during the translation.

Return Value:

Returns true if translation was performed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The first and second functions call the third by default.

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