Using a text - ordering object

You instantiate a text-ordering object for a particular language or script by specifying the appropriate set of ordering rules. The ordering object builds a collation table from these rules and uses this table when comparing text. These rules define a ranking, from least to greatest, for each character in the script.

In addition, each character is assigned an ordering priority within the ranking: primary, secondary, or tertiary. For example, in an English collation table:

Collation tables also describe any special characters for the language (for example, grouped or expanding characters). See "Collation features" on page 210 for information about these collating rules.

The class TTableBasedTextOrder, derived from TTextOrder, provides the protocol for text-ordering objects that use collation tables. Sets of ordering rules can be archived, and end users specify their preference in their locale.

You can get the text-ordering object based from the current locale using the locale item identifier TLocale::kTextOrderID, as shown in this example:

      TLocale currentLocale = TLocale::GetCurrentLocale();
  TLocaleItem<TLanguageTextOrder> item;
  TDeleterFor<TLanguageTextOrder> textOrder = 
      item.CopyItem( TLocale::kTextOrderItemID, currentLocale );

Comparison functions

TTextOrder provides comparison functions that compare two text objects--a source string and a target string--and return information about whether the source string is greater than, less than, or equal to the target string. You can use these functions to compare styled text. The styling information is ignored and does not affect the result of the comparison.

When you compare two strings, the first primary difference determines the ordering regardless of the following characters. If there are no primary differences, the first secondary difference determines the ordering. Finally, if there are no primary or secondary differences, the first tertiary difference determines the ordering. Strings are considered equal only if the Unicode values are identical or if there are equivalent Unicode spellings. For example, the character ü is equivalent to the sequence u and xac .

The primary function for comparing strings is the TTextOrder::Compare function. This function compares two text objects and returns an ETextComparisonResult value indicating both the result and the ordering strength of the difference. For example, this table shows the results when comparing strings using the English collation table:

Source Target Result
abc abc kSourceEqual
abc def kSourcePrimaryLess
abc âbc kSourceSecondaryLess
abc Abc kSourceTertiaryLess
def abc kSourcePrimaryGreater
âbc abc kSourceSecondaryGreater
Abc abc kSourceTertiaryGreater

This sample demonstrates how you might compare two strings using the Compare function:

      void
  CompareText( TText& sourceText, TText& targetText )
  {
      TLocale currentLocale = TLocale::GetCurrentLocale();
      TLocaleItem<TLanguageTextOrder> item;
      TDeleterFor<TLanguageTextOrder> textOrder = 
          item.CopyItem( TLocale::kTextOrderItemID, currentLocale );
  
      TTextOrder::ETextComparisonResult result = order->Compare( sourceText, targetText );
  
  
    if ( result == TTextOrder::kSourceTertiaryLess ||
          result == TTextOrder::kSourceTertiaryGreater ||
          result == TTextOrder::kSourceEqual )
      {
          // Strings are equal or have only tertiary differences.
      }
      else 
      {
          // Strings have primary or secondary differences.
      }
  }
If you are not interested in the ordering strength of the difference, the text-ordering class includes a set of functions that provide a simple ordering test. These functions call the Compare function and return a Boolean value:

For example, this sample function demonstrates how you might compare two strings and operate on equal strings in some way:

      void
  CompareStrings(TText& sourceText, TText& targetText)
  {
      TLocale currentLocale = TLocale::GetCurrentLocale();
      TLocaleItem<TLanguageTextOrder> item;
      TDeleterFor<TLanguageTextOrder> textOrder = 
          item.CopyItem( TLocale::kTextOrderItemID, currentLocale );
  
      if ( order->TextIsEqual( sourceText, targetText ) )
      {
          // Strings are equal.
      }
  }
NOTE Copying the ordering object from the locale creates some overhead. If you are comparing multiple strings, copy the object once and reuse it.

Comparison options

To control the level of comparison, you can also specify that the text-ordering ignore tertiary differences or to ignore both secondary and tertiary differences. For example, in an ordering system in which case differences are tertiary, such as English, you can implement case-insensitive matching by ignoring tertiary differences. In an ordering system in which case differences are secondary, you can implement case-insensitive matching by ignoring both secondary and tertiary differences.

Use the TLanguageTextOrder::SetOnlyUsePrimaryDifference and SetOnlyUsePrimaryAndSecondaryDifference member functions to control this behavior. By default, these flags are both set to False, and all levels of differences are considered.

[Contents] [Previous] [Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.

Generated with WebMaker