Class: TLanguageTextOrder

Declaration: TextComparison.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TTextOrder

Inherited By:

TTableBasedTextOrder

Purpose:

TLanguageTextOrder is an abstract class derived from TTextOrder which provides the protocol for language-sensitive comparison of text strings.

Instantiation:

TLanguageTextOrder is an abstract class that cannot be directly instantiated.

Deriving Classes:

The system provides the concrete derived class TTableBasedTextOrder.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLanguageTextOrder::~TLanguageTextOrder

virtual ~ TLanguageTextOrder ()

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: TLanguageTextOrder::Compare

virtual ETextComparisonResult Compare (const TText & sourceText, const TText & targetText) const
virtual ETextComparisonResult Compare (const TText & sourceText, const TText & targetText, TTextCount & sourceCharactersMatched, TTextCount & targetCharactersMatched) const

Interface Category:

API.

Purpose:

Compares two text objects and returns the result as an ETextComparisonResult value.
Compares two text objects and returns the result as an ETextComparisonResult value. Also fills in the given TTextCounts with the number of characters matched in both the source and the target strings.

Calling Context:

Called by clients.
Called by clients.

Parameters:

const TText & sourceText -The source string for the comparison.
const TText & targetText -The target string for the comparison.
const TText & sourceText -The source string for the comparison.
const TText & targetText -The target string for the comparison.
TTextCount & sourceCharactersMatched -Variable to be filled in with the number of characters matched in the source string.
TTextCount & targetCharactersMatched -Variable to be filled in with the number of characters matched in the target string.

Return Value:

The ETextComparisonResult value containing the results of the comparison.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TLanguageTextOrder::CreateTextPatternIterator

virtual TTextPatternIterator * CreateTextPatternIterator (const TText * text, const TText & pattern, const TTextRange & searchRange) const

Interface Category:

API.

Purpose:

Creates an object of the text pattern iterator class, TStandardTextPatternIterator, that uses this text ordering class for pattern iteration.

Calling Context:

Called by clients.

Parameters:

const TText * text -The text object to iterate through.
const TText & pattern -The pattern to search for.
const TTextRange & searchRange -The range of the text object to iterate through.

Return Value:

A TStandardTextPatternIterator object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TLanguageTextOrder::SetOnlyUsePrimaryDifference

virtual void SetOnlyUsePrimaryDifference (bool flag)

Interface Category:

API.

Purpose:

Sets this object to ignore both secondary and tertiary differences when comparing strings. This produces case-insensitive matching if tertiary ordering is not used by the collation table for this object. The default is false.

Calling Context:

Called by clients.

Parameters:

bool flag -Whether or not to ignore both secondary and tertiary differences.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::GetOnlyUsePrimaryDifference

virtual bool GetOnlyUsePrimaryDifference () const

Interface Category:

API.

Purpose:

Queries whether this object is set to ignore both secondary and tertiary differences.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.

Return Value:

Returns true if this object is set to ignore secondary and tertiary differences.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::SetOnlyUsePrimaryAndSecondaryDifference

virtual void SetOnlyUsePrimaryAndSecondaryDifference (bool flag)

Interface Category:

API.

Purpose:

Sets this object to ignore tertiary differences when comparing strings. This produces case-insensitive matching if tertiary ordering is used by the collation table for this object. The default is false.

Calling Context:

Called by clients.

Parameters:

bool flag -Whether or not to ignore tertiary differences.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::GetOnlyUsePrimaryAndSecondaryDifference

virtual bool GetOnlyUsePrimaryAndSecondaryDifference () const

Interface Category:

API.

Purpose:

Queries whether this object is set to ignore tertiary differences but consider secondary differences.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.

Return Value:

Returns true if this object should ignore tertiary differences but consider secondary differences.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::SetBackwardSecondaryOrdering

virtual void SetBackwardSecondaryOrdering (bool flag)

Interface Category:

API.

Purpose:

Sets this object to use backward secondary ordering when comparing strings. For example, in French, secondary ordering is performed from greatest to least. Assuming that C1 is greater than C2, and the difference is secondary, then C1 is less than C2 when backward secondary ordering is used. The default is false.

Calling Context:

Called by clients.

Parameters:

bool flag -Whether or not to use backward secondary ordering.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::GetBackwardSecondaryOrdering

virtual bool GetBackwardSecondaryOrdering () const

Interface Category:

API.

Purpose:

Queries whether this object is set to use backward secondary ordering.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.

Return Value:

Returns true if this object is set to use backward secondary ordering.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::SetBackwardTertiaryOrdering

virtual void SetBackwardTertiaryOrdering (bool flag)

Interface Category:

API.

Purpose:

Sets this object to use backward tertiary ordering. Tertiary ordering is performed from greatest to least. The default is false.

Calling Context:

Called by clients.

Parameters:

bool flag -Whether or not to use backward tertiary ordering.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::GetBackwardTertiaryOrdering

virtual bool GetBackwardTertiaryOrdering () const

Interface Category:

API.

Purpose:

Queries whether this object is set to use backward tertiary ordering.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.

Return Value:

Returns true if this object is set to use backward tertiary ordering.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::TextIsEqual

virtual bool TextIsEqual (const TText & sourceText, const TText & targetText) const

Interface Category:

API.

Purpose:

Compares two TText objects, returning whether or not they are equal.

Calling Context:

Called by clients.

Parameters:

const TText & sourceText -The source text string to compare.
const TText & targetText -The target text string to compare.

Return Value:

Returns true if the text strings are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTextOrder function. This function calls the Compare function. It will consider the strings equal if Compare returns kSourceEqual. This function's results vary according to the level of ordering differences this object is set to ignore. Derived classes should not override this function; they can override Compare instead.

Member Function: TLanguageTextOrder::TextIsGreaterThan

virtual bool TextIsGreaterThan (const TText & sourceText, const TText & targetText) const

Interface Category:

API.

Purpose:

Compares two TText objects, returning whether or not the source text is greater than the target text.

Calling Context:

Called by clients.

Parameters:

const TText & sourceText -The source text string to compare.
const TText & targetText -The target text string to compare.

Return Value:

Returns true if the source text is greater than the target text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTextOrder function. This function calls the Compare function. It will consider the source string greater than the target string if Compare returns either kSourcePrimaryGreater, kSourceSecondaryGreater or kSourceTertiaryGreater. This function's results vary according to the level of ordering differences this object is set to ignore. Derived classes should not override this function; they can override Compare instead.

Member Function: TLanguageTextOrder::TextIsLessThan

virtual bool TextIsLessThan (const TText & sourceText, const TText & targetText) const

Interface Category:

API.

Purpose:

Compares two TText objects, returning whether or not the source text is less than the target text.

Calling Context:

Called by clients.

Parameters:

const TText & sourceText -The source text string to compare.
const TText & targetText -The target text string to compare.

Return Value:

Returns true if the source text is less than the target text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TTextOrder function. This function calls the Compare function. It will consider the source string less than the target string if Compare returns either kSourcePrimaryLess, kSourceSecondaryLess or kSourceTertiaryLess. This function's results vary according to the level of ordering differences this object is set to ignore. Derived classes should not override this function; they can override Compare instead.

Member Function: TLanguageTextOrder::HasSpecialCharacters

bool HasSpecialCharacters () const

Interface Category:

API.

Purpose:

Queries whether the collation table for this object contains ignorable, grouped, or expanding characters.

Calling Context:

Called during comparison.

Parameters:

Takes no parameters.

Return Value:

Returns true if the collation table for this object contains ignorable, grouped, or expanding characters.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLanguageTextOrder::SetHasSpecialCharacters

virtual void SetHasSpecialCharacters (bool flag)

Interface Category:

API.

Purpose:

Specifies whether the collation table for this object contains ignorable, grouped, or expanding characters.

Calling Context:

Called by clients.

Parameters:

bool flag -Whether the collation table for this object contains ignorable, grouped, or expanding characters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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

Overrides inherited MCollectible function.

Member Function: TLanguageTextOrder::operator=

TLanguageTextOrder & operator =(const TLanguageTextOrder & order)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TLanguageTextOrder & order -The source object for this 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: TLanguageTextOrder::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: TLanguageTextOrder::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: TLanguageTextOrder::TLanguageTextOrder

TLanguageTextOrder ()
TLanguageTextOrder (const TLanguageTextOrder & order)

Interface Category:

API.

Purpose:

Default constructor. This constructor is protected.
Copy constructor. This constructor is protected.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const TLanguageTextOrder & order -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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