Loading...
Searching...
No Matches
icu::RuleBasedCollator Class Referencefinal

The RuleBasedCollator class provides the implementation of Collator, using data-driven tables. More...

`#include <tblcoll.h>`

Inheritance diagram for icu::RuleBasedCollator:

## Public Member Functions

U_I18N_API | RuleBasedCollator (const UnicodeString &rules, UErrorCode &status)
| RuleBasedCollator constructor.
U_I18N_API | RuleBasedCollator (const UnicodeString &rules, ECollationStrength collationStrength, UErrorCode &status)
| RuleBasedCollator constructor.
U_I18N_API | RuleBasedCollator (const UnicodeString &rules, UColAttributeValue decompositionMode, UErrorCode &status)
| RuleBasedCollator constructor.
U_I18N_API | RuleBasedCollator (const UnicodeString &rules, ECollationStrength collationStrength, UColAttributeValue decompositionMode, UErrorCode &status)
| RuleBasedCollator constructor.
U_I18N_API | RuleBasedCollator (const UnicodeString &rules, UParseError &parseError, UnicodeString &reason, UErrorCode &errorCode)
| TODO: document & propose as public API.
U_I18N_API | RuleBasedCollator (const RuleBasedCollator &other)
| Copy constructor.
U_I18N_API | RuleBasedCollator (const uint8_t *bin, int32_t length, const RuleBasedCollator *base, UErrorCode &status)
| Opens a collator from a collator binary image created using cloneBinary.
virtual U_I18N_API | ~RuleBasedCollator ()
| Destructor.
U_I18N_API RuleBasedCollator & | operator= (const RuleBasedCollator &other)
| Assignment operator.
virtual U_I18N_API bool | operator== (const Collator &other) const override
| Returns true if argument is the same as this object.
virtual U_I18N_API RuleBasedCollator * | clone () const override
| Makes a copy of this object.
U_I18N_API CollationElementIterator * | createCollationElementIterator (const UnicodeString &source) const
| Creates a collation element iterator for the source string.
U_I18N_API CollationElementIterator * | createCollationElementIterator (const CharacterIterator &source) const
| Creates a collation element iterator for the source.
virtual U_I18N_API UCollationResult | compare (const UnicodeString &source, const UnicodeString &target, UErrorCode &status) const override
| The comparison function compares the character data stored in two different strings.
virtual U_I18N_API UCollationResult | compare (const UnicodeString &source, const UnicodeString &target, int32_t length, UErrorCode &status) const override
| Does the same thing as compare but limits the comparison to a specified length.
virtual U_I18N_API UCollationResult | compare (const char16_t *source, int32_t sourceLength, const char16_t *target, int32_t targetLength, UErrorCode &status) const override
| The comparison function compares the character data stored in two different string arrays.
virtual U_I18N_API UCollationResult | compare (UCharIterator &sIter, UCharIterator &tIter, UErrorCode &status) const override
| Compares two strings using the Collator.
virtual U_I18N_API UCollationResult | compareUTF8 (const StringPiece &source, const StringPiece &target, UErrorCode &status) const override
| Compares two UTF-8 strings using the Collator.
virtual U_I18N_API CollationKey & | getCollationKey (const UnicodeString &source, CollationKey &key, UErrorCode &status) const override
| Transforms the string into a series of characters that can be compared with CollationKey.compare().
virtual U_I18N_API CollationKey & | getCollationKey (const char16_t *source, int32_t sourceLength, CollationKey &key, UErrorCode &status) const override
| Transforms a specified region of the string into a series of characters that can be compared with CollationKey.compare.
virtual U_I18N_API int32_t | hashCode () const override
| Generates the hash code for the rule-based collation object.
virtual U_I18N_API Locale | getLocale (ULocDataLocaleType type, UErrorCode &status) const override
| Gets the locale of the Collator.
U_I18N_API const UnicodeString & | getRules () const
| Gets the tailoring rules for this collator.
virtual U_I18N_API void | getVersion (UVersionInfo info) const override
| Gets the version information for a Collator.
U_I18N_API int32_t | getMaxExpansion (int32_t order) const
| Returns the maximum length of any expansion sequences that end with the specified comparison order.
virtual U_I18N_API UClassID | getDynamicClassID () const override
| Returns a unique class ID POLYMORPHICALLY.
U_I18N_API uint8_t * | cloneRuleData (int32_t &length, UErrorCode &status) const
| Do not use this method: The caller and the ICU library might use different heaps.
U_I18N_API int32_t | cloneBinary (uint8_t *buffer, int32_t capacity, UErrorCode &status) const
| Creates a binary image of a collator.
U_I18N_API void | getRules (UColRuleOption delta, UnicodeString &buffer) const
| Returns current rules.
virtual U_I18N_API void | setAttribute (UColAttribute attr, UColAttributeValue value, UErrorCode &status) override
| Universal attribute setter.
virtual U_I18N_API UColAttributeValue | getAttribute (UColAttribute attr, UErrorCode &status) const override
| Universal attribute getter.
virtual U_I18N_API Collator & | setMaxVariable (UColReorderCode group, UErrorCode &errorCode) override
| Sets the variable top to the top of the specified reordering group.
virtual U_I18N_API UColReorderCode | getMaxVariable () const override
| Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING.
virtual U_I18N_API uint32_t | setVariableTop (const char16_t *varTop, int32_t len, UErrorCode &status) override
| Sets the variable top to the primary weight of the specified string.
virtual U_I18N_API uint32_t | setVariableTop (const UnicodeString &varTop, UErrorCode &status) override
| Sets the variable top to the primary weight of the specified string.
virtual U_I18N_API void | setVariableTop (uint32_t varTop, UErrorCode &status) override
| Sets the variable top to the specified primary weight.
virtual U_I18N_API uint32_t | getVariableTop (UErrorCode &status) const override
| Gets the variable top value of a Collator.
virtual U_I18N_API UnicodeSet * | getTailoredSet (UErrorCode &status) const override
| Get a UnicodeSet that contains all the characters and sequences tailored in this collator.
virtual U_I18N_API int32_t | getSortKey (const UnicodeString &source, uint8_t *result, int32_t resultLength) const override
| Get the sort key as an array of bytes from a UnicodeString.
virtual U_I18N_API int32_t | getSortKey (const char16_t *source, int32_t sourceLength, uint8_t *result, int32_t resultLength) const override
| Get the sort key as an array of bytes from a char16_t buffer.
virtual U_I18N_API int32_t | getReorderCodes (int32_t *dest, int32_t destCapacity, UErrorCode &status) const override
| Retrieves the reordering codes for this collator.
virtual U_I18N_API void | setReorderCodes (const int32_t *reorderCodes, int32_t reorderCodesLength, UErrorCode &status) override
| Sets the ordering of scripts for this collator.
virtual U_I18N_API UCollationResult | internalCompareUTF8 (const char *left, int32_t leftLength, const char *right, int32_t rightLength, UErrorCode &errorCode) const override
| Implements ucol_strcollUTF8().
virtual U_I18N_API int32_t | internalGetShortDefinitionString (const char *locale, char *buffer, int32_t capacity, UErrorCode &status) const override
| Get the short definition string for a collator.
virtual U_I18N_API int32_t | internalNextSortKeyPart (UCharIterator *iter, uint32_t state[2], uint8_t *dest, int32_t count, UErrorCode &errorCode) const override
| Implements ucol_nextSortKeyPart().
U_I18N_API | RuleBasedCollator ()
| Only for use in ucol_openRules().
U_I18N_API const char * | internalGetLocaleID (ULocDataLocaleType type, UErrorCode &errorCode) const
| Implements ucol_getLocaleByType().
U_I18N_API void | internalGetContractionsAndExpansions (UnicodeSet *contractions, UnicodeSet *expansions, UBool addPrefixes, UErrorCode &errorCode) const
| Implements ucol_getContractionsAndExpansions().
U_I18N_API void | internalAddContractions (UChar32 c, UnicodeSet &set, UErrorCode &errorCode) const
| Adds the contractions that start with character c to the set.
U_I18N_API void | internalBuildTailoring (const UnicodeString &rules, int32_t strength, UColAttributeValue decompositionMode, UParseError *outParseError, UnicodeString *outReason, UErrorCode &errorCode)
| Implements from-rule constructors, and ucol_openRules().
U_I18N_API void | internalGetCEs (const UnicodeString &str, UVector64 &ces, UErrorCode &errorCode) const
| Appends the CEs for the string to the vector.
virtual EComparisonResult | compare (const UnicodeString &source, const UnicodeString &target) const
| The comparison function compares the character data stored in two different strings.
virtual EComparisonResult | compare (const UnicodeString &source, const UnicodeString &target, int32_t length) const
| Does the same thing as compare but limits the comparison to a specified length.
virtual EComparisonResult | compare (const char16_t *source, int32_t sourceLength, const char16_t *target, int32_t targetLength) const
| The comparison function compares the character data stored in two different string arrays.
Public Member Functions inherited from icu::Collator
virtual | ~Collator ()
| Destructor.
virtual bool | operator!= (const Collator &other) const
| Returns true if "other" is not the same as "this".
UBool | greater (const UnicodeString &source, const UnicodeString &target) const
| Convenience method for comparing two strings based on the collation rules.
UBool | greaterOrEqual (const UnicodeString &source, const UnicodeString &target) const
| Convenience method for comparing two strings based on the collation rules.
UBool | equals (const UnicodeString &source, const UnicodeString &target) const
| Convenience method for comparing two strings based on the collation rules.
auto | equal_to () const
| Creates a comparison function object that uses this collator.
auto | greater () const
| Creates a comparison function object that uses this collator.
auto | less () const
| Creates a comparison function object that uses this collator.
auto | not_equal_to () const
| Creates a comparison function object that uses this collator.
auto | greater_equal () const
| Creates a comparison function object that uses this collator.
auto | less_equal () const
| Creates a comparison function object that uses this collator.
virtual ECollationStrength | getStrength () const
| Determines the minimum strength that will be used in comparison or transformation.
virtual void | setStrength (ECollationStrength newStrength)
| Sets the minimum strength to be used in comparison or transformation.
virtual Collator * | safeClone () const
| Same as clone().
UCollator * | toUCollator ()
const UCollator * | toUCollator () const
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.

## Static Public Member Functions

static U_I18N_API UClassID | getStaticClassID ()
| Returns the class ID for this class.
static RuleBasedCollator * | rbcFromUCollator (UCollator *uc)
static const RuleBasedCollator * | rbcFromUCollator (const UCollator *uc)
Static Public Member Functions inherited from icu::Collator
static Collator * | createInstance (UErrorCode &err)
| Creates the Collator object for the current default locale.
static Collator * | createInstance (const Locale &loc, UErrorCode &err)
| Gets the collation object for the desired locale.
static int32_t | getEquivalentReorderCodes (int32_t reorderCode, int32_t *dest, int32_t destCapacity, UErrorCode &status)
| Retrieves the reorder codes that are grouped with the given reorder code.
static UnicodeString & | getDisplayName (const Locale &objectLocale, const Locale &displayLocale, UnicodeString &name)
| Get name of the object for the desired Locale, in the desired language.
static UnicodeString & | getDisplayName (const Locale &objectLocale, UnicodeString &name)
| Get name of the object for the desired Locale, in the language of the default locale.
static const Locale * | getAvailableLocales (int32_t &count)
| Get the set of Locales for which Collations are installed.
static StringEnumeration * | getAvailableLocales ()
| Return a StringEnumeration over the locales available at the time of the call, including registered locales.
static StringEnumeration * | getKeywords (UErrorCode &status)
| Create a string enumerator of all possible keywords that are relevant to collation.
static StringEnumeration * | getKeywordValues (const char *keyword, UErrorCode &status)
| Given a keyword, create a string enumeration of all values for that keyword that are currently in use.
static StringEnumeration * | getKeywordValuesForLocale (const char *keyword, const Locale &locale, UBool commonlyUsed, UErrorCode &status)
| Given a key and a locale, returns an array of string values in a preferred order that would make a difference.
static Locale | getFunctionalEquivalent (const char *keyword, const Locale &locale, UBool &isAvailable, UErrorCode &status)
| Return the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service.
static URegistryKey | registerInstance (Collator *toAdopt, const Locale &locale, UErrorCode &status)
| Register a new Collator.
static URegistryKey | registerFactory (CollatorFactory *toAdopt, UErrorCode &status)
| Register a new CollatorFactory.
static UBool | unregister (URegistryKey key, UErrorCode &status)
| Unregister a previously-registered Collator or CollatorFactory using the key returned from the register call.
static int32_t | getBound (const uint8_t *source, int32_t sourceLength, UColBoundMode boundType, uint32_t noOfLevels, uint8_t *result, int32_t resultLength, UErrorCode &status)
| Produce a bound for a given sortkey and a number of levels.
static Collator * | fromUCollator (UCollator *uc)
static const Collator * | fromUCollator (const UCollator *uc)

## Protected Member Functions

virtual void | setLocales (const Locale &requestedLocale, const Locale &validLocale, const Locale &actualLocale) override
| Used internally by registration to define the requested and valid locales.
Protected Member Functions inherited from icu::Collator
| Collator ()
| Default constructor.
| Collator (UCollationStrength collationStrength, UNormalizationMode decompositionMode)
| Constructor.
| Collator (const Collator &other)
| Copy constructor.

## Friends

class | CollationElementIterator
class | Collator

## Additional Inherited Members

Public Types inherited from icu::Collator
enum | ECollationStrength { PRIMARY = UCOL_PRIMARY , SECONDARY = UCOL_SECONDARY , TERTIARY = UCOL_TERTIARY , QUATERNARY = UCOL_QUATERNARY , IDENTICAL = UCOL_IDENTICAL }
| Base letter represents a primary difference. More...
enum | EComparisonResult { LESS = UCOL_LESS , EQUAL = UCOL_EQUAL , GREATER = UCOL_GREATER }
| LESS is returned if source string is compared to be less than target string in the compare() method. More...

## Detailed Description

The RuleBasedCollator class provides the implementation of Collator, using data-driven tables.

The user can create a customized table-based collation.

For more information about the collation service see the User Guide.

Collation service provides correct sorting orders for most locales supported in ICU. If specific data for a locale is not available, the orders eventually falls back to the CLDR root sort order.

Sort ordering may be customized by providing your own set of rules. For more on this subject see the Collation Customization section of the User Guide.

Note, RuleBasedCollator is not to be subclassed.

See also
  Collator

Definition at line 115 of file tblcoll.h.

## Constructor & Destructor Documentation

## RuleBasedCollator() [1/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( | const UnicodeString & | rules,
|  | UErrorCode & | status )

RuleBasedCollator constructor.

This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax.

Parameters

  rules | the collation rules to build the collation table from.
  status | reporting a success or an error.

Stable
  ICU 2.0

References U_I18N_API.

Referenced by clone(), operator=(), rbcFromUCollator(), rbcFromUCollator(), RuleBasedCollator(), RuleBasedCollator(), and setLocales().

## RuleBasedCollator() [2/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( | const UnicodeString & | rules,
|  | ECollationStrength | collationStrength,
|  | UErrorCode & | status )

RuleBasedCollator constructor.

This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax.

Parameters

  rules | the collation rules to build the collation table from.
  collationStrength | strength for comparison
  status | reporting a success or an error.

Stable
  ICU 2.0

References U_I18N_API.

## RuleBasedCollator() [3/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( | const UnicodeString & | rules,
|  | UColAttributeValue | decompositionMode,
|  | UErrorCode & | status )

RuleBasedCollator constructor.

This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax.

Parameters

  rules | the collation rules to build the collation table from.
  decompositionMode | the normalisation mode
  status | reporting a success or an error.

Stable
  ICU 2.0

References U_I18N_API.

## RuleBasedCollator() [4/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( | const UnicodeString & | rules,
|  | ECollationStrength | collationStrength,
|  | UColAttributeValue | decompositionMode,
|  | UErrorCode & | status )

RuleBasedCollator constructor.

This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax.

Parameters

  rules | the collation rules to build the collation table from.
  collationStrength | strength for comparison
  decompositionMode | the normalisation mode
  status | reporting a success or an error.

Stable
  ICU 2.0

References U_I18N_API.

## RuleBasedCollator() [5/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( | const UnicodeString & | rules,
|  | UParseError & | parseError,
|  | UnicodeString & | reason,
|  | UErrorCode & | errorCode )

TODO: document & propose as public API.

Internal
  Do not use. This API is for internal use only.

References U_I18N_API.

## RuleBasedCollator() [6/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( | const RuleBasedCollator & | other | ) |

Copy constructor.

Parameters

  other | the RuleBasedCollator object to be copied

Stable
  ICU 2.0

References RuleBasedCollator(), and U_I18N_API.

## RuleBasedCollator() [7/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( | const uint8_t * | bin,
|  | int32_t | length,
|  | const RuleBasedCollator * | base,
|  | UErrorCode & | status )

Opens a collator from a collator binary image created using cloneBinary.

Binary image used in instantiation of the collator remains owned by the user and should stay around for the lifetime of the collator. The API also takes a base collator which must be the root collator.

Parameters

  bin | binary image owned by the user and required through the lifetime of the collator
  length | size of the image. If negative, the API will try to figure out the length of the image
  base | Base collator, for lookup of untailored characters. Must be the root collator, must not be nullptr. The base is required to be present through the lifetime of the collator.
  status | for catching errors

Returns
  newly created collator

See also
  cloneBinary

Stable
  ICU 3.4

References RuleBasedCollator(), and U_I18N_API.

## ~RuleBasedCollator()

virtual U_I18N_API icu::RuleBasedCollator::~RuleBasedCollator | ( |  | ) |

virtual

Destructor.

Stable
  ICU 2.0

References U_I18N_API.

## RuleBasedCollator() [8/8]

U_I18N_API icu::RuleBasedCollator::RuleBasedCollator | ( |  | ) |

Only for use in ucol_openRules().

Internal
  Do not use. This API is for internal use only.

References U_I18N_API.

## Member Function Documentation

## clone()

virtual U_I18N_API RuleBasedCollator * icu::RuleBasedCollator::clone | ( |  | ) | const

override virtual

Makes a copy of this object.

Returns
  a copy of this object, owned by the caller

Stable
  ICU 2.0

Implements icu::Collator.

References RuleBasedCollator(), and U_I18N_API.

## cloneBinary()

U_I18N_API int32_t icu::RuleBasedCollator::cloneBinary | ( | uint8_t * | buffer,
|  | int32_t | capacity,
|  | UErrorCode & | status ) const

Creates a binary image of a collator.

This binary image can be stored and later used to instantiate a collator using ucol_openBinary. This API supports preflighting.

Parameters

  buffer | a fill-in buffer to receive the binary image
  capacity | capacity of the destination buffer
  status | for catching errors

Returns
  size of the image

See also
  ucol_openBinary

Stable
  ICU 3.4

References U_I18N_API.

## cloneRuleData()

U_I18N_API uint8_t * icu::RuleBasedCollator::cloneRuleData | ( | int32_t & | length,
|  | UErrorCode & | status ) const

Do not use this method: The caller and the ICU library might use different heaps.

Use cloneBinary() instead which writes to caller-provided memory.

Returns a binary format of this collator.

Parameters

  length | Returns the length of the data, in bytes
  status | the error code status.

Returns
  memory, owned by the caller, of size 'length' bytes.

Deprecated
  ICU 52. Use cloneBinary() instead.

References U_I18N_API.

## compare() [1/7]

virtual EComparisonResult icu::Collator::compare | ( | const char16_t * | source,
|  | int32_t | sourceLength,
|  | const char16_t * | target,
|  | int32_t | targetLength ) const

virtual

The comparison function compares the character data stored in two different string arrays.

Returns information about whether a string array is less than, greater than or equal to another string array.

Example of use:

    .       char16_t ABC[] = {0x41, 0x42, 0x43, 0};  // = "ABC"
    .       char16_t abc[] = {0x61, 0x62, 0x63, 0};  // = "abc"
    .       UErrorCode status = U_ZERO_ERROR;
    .       Collator *myCollation =
    .                         Collator::createInstance(Locale::getUS(), status);
    .       if (U_FAILURE(status)) return;
    .       myCollation->setStrength(Collator::PRIMARY);
    .       // result would be Collator::EQUAL ("abc" == "ABC")
    .       // (no primary difference between "abc" and "ABC")
    .       Collator::EComparisonResult result =
    .                             myCollation->compare(abc, 3, ABC, 3);
    .       myCollation->setStrength(Collator::TERTIARY);
    .       // result would be Collator::LESS ("abc" <<< "ABC")
    .       // (with tertiary difference between "abc" and "ABC")
    .       result = myCollation->compare(abc, 3, ABC, 3);

Parameters

  source | the source string array to be compared with.
  sourceLength | the length of the source string array. If this value is equal to -1, the string array is null-terminated.
  target | the string that is to be compared with the source string.
  targetLength | the length of the target string array. If this value is equal to -1, the string array is null-terminated.

Returns
  Returns a byte value. GREATER if source is greater than target; EQUAL if source is equal to target; LESS if source is less than target

Deprecated
  ICU 2.6 use the overload with UErrorCode &

Reimplemented from icu::Collator.

## compare() [2/7]

virtual U_I18N_API UCollationResult icu::RuleBasedCollator::compare | ( | const char16_t * | source,
|  | int32_t | sourceLength,
|  | const char16_t * | target,
|  | int32_t | targetLength,
|  | UErrorCode & | status ) const

override virtual

The comparison function compares the character data stored in two different string arrays.

Returns information about whether a string array is less than, greater than or equal to another string array.

Parameters

  source | the source string array to be compared with.
  sourceLength | the length of the source string array. If this value is equal to -1, the string array is null-terminated.
  target | the string that is to be compared with the source string.
  targetLength | the length of the target string array. If this value is equal to -1, the string array is null-terminated.
  status | possible error code

Returns
  Returns an enum value. UCOL_GREATER if source is greater than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less than target

Stable
  ICU 2.6

Implements icu::Collator.

References U_I18N_API.

## compare() [3/7]

virtual EComparisonResult icu::Collator::compare | ( | const UnicodeString & | source,
|  | const UnicodeString & | target ) const

virtual

The comparison function compares the character data stored in two different strings.

Returns information about whether a string is less than, greater than or equal to another string.

Parameters

  source | the source string to be compared with.
  target | the string that is to be compared with the source string.

Returns
  Returns a byte value. GREATER if source is greater than target; EQUAL if source is equal to target; LESS if source is less than target

Deprecated
  ICU 2.6 use the overload with UErrorCode &

Reimplemented from icu::Collator.

## compare() [4/7]

virtual EComparisonResult icu::Collator::compare | ( | const UnicodeString & | source,
|  | const UnicodeString & | target,
|  | int32_t | length ) const

virtual

Does the same thing as compare but limits the comparison to a specified length.

Parameters

  source | the source string to be compared with.
  target | the string that is to be compared with the source string.
  length | the length the comparison is limited to

Returns
  Returns a byte value. GREATER if source (up to the specified length) is greater than target; EQUAL if source (up to specified length) is equal to target; LESS if source (up to the specified length) is less than target.

Deprecated
  ICU 2.6 use the overload with UErrorCode &

Reimplemented from icu::Collator.

## compare() [5/7]

virtual U_I18N_API UCollationResult icu::RuleBasedCollator::compare | ( | const UnicodeString & | source,
|  | const UnicodeString & | target,
|  | int32_t | length,
|  | UErrorCode & | status ) const

override virtual

Does the same thing as compare but limits the comparison to a specified length.

Parameters

  source | the source string to be compared with.
  target | the string that is to be compared with the source string.
  length | the length the comparison is limited to
  status | possible error code

Returns
  Returns an enum value. UCOL_GREATER if source (up to the specified length) is greater than target; UCOL_EQUAL if source (up to specified length) is equal to target; UCOL_LESS if source (up to the specified length) is less than target.

Stable
  ICU 2.6

Implements icu::Collator.

References U_I18N_API.

## compare() [6/7]

virtual U_I18N_API UCollationResult icu::RuleBasedCollator::compare | ( | const UnicodeString & | source,
|  | const UnicodeString & | target,
|  | UErrorCode & | status ) const

override virtual

The comparison function compares the character data stored in two different strings.

Returns information about whether a string is less than, greater than or equal to another string.

Parameters

  source | the source string to be compared with.
  target | the string that is to be compared with the source string.
  status | possible error code

Returns
  Returns an enum value. UCOL_GREATER if source is greater than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less than target

Stable
  ICU 2.6

Implements icu::Collator.

References U_I18N_API.

## compare() [7/7]

virtual U_I18N_API UCollationResult icu::RuleBasedCollator::compare | ( | UCharIterator & | sIter,
|  | UCharIterator & | tIter,
|  | UErrorCode & | status ) const

override virtual

Compares two strings using the Collator.

Returns whether the first one compares less than/equal to/greater than the second one. This version takes UCharIterator input.

Parameters

  sIter | the first ("source") string iterator
  tIter | the second ("target") string iterator
  status | ICU status

Returns
  UCOL_LESS, UCOL_EQUAL or UCOL_GREATER

Stable
  ICU 4.2

Reimplemented from icu::Collator.

References U_I18N_API.

## compareUTF8()

virtual U_I18N_API UCollationResult icu::RuleBasedCollator::compareUTF8 | ( | const StringPiece & | source,
|  | const StringPiece & | target,
|  | UErrorCode & | status ) const

override virtual

Compares two UTF-8 strings using the Collator.

Returns whether the first one compares less than/equal to/greater than the second one. This version takes UTF-8 input. Note that a StringPiece can be implicitly constructed from a std::string or a NUL-terminated const char * string.

Parameters

  source | the first UTF-8 string
  target | the second UTF-8 string
  status | ICU status

Returns
  UCOL_LESS, UCOL_EQUAL or UCOL_GREATER

Stable
  ICU 51

Reimplemented from icu::Collator.

References U_I18N_API.

## createCollationElementIterator() [1/2]

U_I18N_API CollationElementIterator * icu::RuleBasedCollator::createCollationElementIterator | ( | const CharacterIterator & | source | ) | const

Creates a collation element iterator for the source.

The caller of this method is responsible for the memory management of the returned pointer.

Parameters

  source | the CharacterIterator which produces the characters over which the CollationElementItgerator will iterate.

Returns
  the collation element iterator of the source using this as the based Collator.

Stable
  ICU 2.2

References icu::Collator::compare().

## createCollationElementIterator() [2/2]

U_I18N_API CollationElementIterator * icu::RuleBasedCollator::createCollationElementIterator | ( | const UnicodeString & | source | ) | const

Creates a collation element iterator for the source string.

The caller of this method is responsible for the memory management of the return pointer.

Parameters

  source | the string over which the CollationElementIterator will iterate.

Returns
  the collation element iterator of the source string using this as the based Collator.

Stable
  ICU 2.2

References U_I18N_API.

## getAttribute()

virtual U_I18N_API UColAttributeValue icu::RuleBasedCollator::getAttribute | ( | UColAttribute | attr,
|  | UErrorCode & | status ) const

override virtual

Universal attribute getter.

Parameters

  attr | attribute type
  status | to indicate whether the operation went on smoothly or there were errors

Returns
  attribute value

Stable
  ICU 2.2

Implements icu::Collator.

References U_I18N_API.

## getCollationKey() [1/2]

virtual U_I18N_API CollationKey & icu::RuleBasedCollator::getCollationKey | ( | const char16_t * | source,
|  | int32_t | sourceLength,
|  | CollationKey & | key,
|  | UErrorCode & | status ) const

override virtual

Transforms a specified region of the string into a series of characters that can be compared with CollationKey.compare.

Note that sort keys are often less efficient than simply doing comparison. For more details, see the ICU User Guide.

Parameters

  source | the source string.
  sourceLength | the length of the source string.
  key | the transformed key of the source string.
  status | the error code status.

Returns
  the transformed key.

See also
  CollationKey

Stable
  ICU 2.0

Implements icu::Collator.

References U_I18N_API.

## getCollationKey() [2/2]

virtual U_I18N_API CollationKey & icu::RuleBasedCollator::getCollationKey | ( | const UnicodeString & | source,
|  | CollationKey & | key,
|  | UErrorCode & | status ) const

override virtual

Transforms the string into a series of characters that can be compared with CollationKey.compare().

Note that sort keys are often less efficient than simply doing comparison. For more details, see the ICU User Guide.

Parameters

  source | the source string.
  key | the transformed key of the source string.
  status | the error code status.

Returns
  the transformed key.

See also
  CollationKey

Stable
  ICU 2.0

Implements icu::Collator.

References U_I18N_API.

## getDynamicClassID()

virtual U_I18N_API UClassID icu::RuleBasedCollator::getDynamicClassID | ( |  | ) | const

override virtual

Returns a unique class ID POLYMORPHICALLY.

Pure virtual override. This method is to implement a simple version of RTTI, since not all C++ compilers support genuine RTTI. Polymorphic operator==() and clone() methods call this method.

Returns
  The class ID for this object. All objects of a given class have the same class ID. Objects of other classes have different class IDs.

Stable
  ICU 2.0

Implements icu::Collator.

References U_I18N_API.

## getLocale()

virtual U_I18N_API Locale icu::RuleBasedCollator::getLocale | ( | ULocDataLocaleType | type,
|  | UErrorCode & | status ) const

override virtual

Gets the locale of the Collator.

Parameters

  type | can be either requested, valid or actual locale. For more information see the definition of ULocDataLocaleType in uloc.h
  status | the error code status.

Returns
  locale where the collation data lives. If the collator was instantiated from rules, locale is empty.

Deprecated
  ICU 2.8 likely to change in ICU 3.0, based on feedback

Implements icu::Collator.

References U_I18N_API.

## getMaxExpansion()

U_I18N_API int32_t icu::RuleBasedCollator::getMaxExpansion | ( | int32_t | order | ) | const

Returns the maximum length of any expansion sequences that end with the specified comparison order.

This is specific to the kind of collation element values and sequences returned by the CollationElementIterator. Call CollationElementIterator::getMaxExpansion() instead.

Parameters

  order | a collation order returned by CollationElementIterator::previous or CollationElementIterator::next.

Returns
  maximum size of the expansion sequences ending with the collation element, or 1 if the collation element does not occur at the end of any expansion sequence

See also
  CollationElementIterator::getMaxExpansion

Deprecated
  ICU 51 Use CollationElementIterator::getMaxExpansion() instead.

References U_I18N_API.

## getMaxVariable()

virtual U_I18N_API UColReorderCode icu::RuleBasedCollator::getMaxVariable | ( |  | ) | const

override virtual

Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING.

Returns
  the maximum variable reordering group.

See also
  setMaxVariable

Stable
  ICU 53

Reimplemented from icu::Collator.

References U_I18N_API.

## getReorderCodes()

virtual U_I18N_API int32_t icu::RuleBasedCollator::getReorderCodes | ( | int32_t * | dest,
|  | int32_t | destCapacity,
|  | UErrorCode & | status ) const

override virtual

Retrieves the reordering codes for this collator.

Parameters

  dest | The array to fill with the script ordering.
  destCapacity | The length of dest. If it is 0, then dest may be nullptr and the function will only return the length of the result without writing any codes (pre-flighting).
  status | A reference to an error code value, which must not indicate a failure before the function call.

Returns
  The length of the script ordering array.

See also
  ucol_setReorderCodes
  Collator::getEquivalentReorderCodes
  Collator::setReorderCodes

Stable
  ICU 4.8

Reimplemented from icu::Collator.

References U_I18N_API.

## getRules() [1/2]

U_I18N_API const UnicodeString & icu::RuleBasedCollator::getRules | ( |  | ) | const

Gets the tailoring rules for this collator.

Returns
  the collation tailoring from which this collator was created

Stable
  ICU 2.0

References U_I18N_API.

## getRules() [2/2]

U_I18N_API void icu::RuleBasedCollator::getRules | ( | UColRuleOption | delta,
|  | UnicodeString & | buffer ) const

Returns current rules.

Delta defines whether full rules are returned or just the tailoring.

getRules(void) should normally be used instead. See https://unicode-org.github.io/icu/userguide/collation/customization#building-on-existing-locales

Parameters

  delta | one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES.
  buffer | UnicodeString to store the result rules

Stable
  ICU 2.2

See also
  UCOL_FULL_RULES

References U_I18N_API.

## getSortKey() [1/2]

virtual U_I18N_API int32_t icu::RuleBasedCollator::getSortKey | ( | const char16_t * | source,
|  | int32_t | sourceLength,
|  | uint8_t * | result,
|  | int32_t | resultLength ) const

override virtual

Get the sort key as an array of bytes from a char16_t buffer.

Note that sort keys are often less efficient than simply doing comparison. For more details, see the ICU User Guide.

Parameters

  source | string to be processed.
  sourceLength | length of string to be processed. If -1, the string is 0 terminated and length will be decided by the function.
  result | buffer to store result in. If nullptr, number of bytes needed will be returned.
  resultLength | length of the result buffer. If if not enough the buffer will be filled to capacity.

Returns
  Number of bytes needed for storing the sort key

Stable
  ICU 2.2

Implements icu::Collator.

References U_I18N_API.

## getSortKey() [2/2]

virtual U_I18N_API int32_t icu::RuleBasedCollator::getSortKey | ( | const UnicodeString & | source,
|  | uint8_t * | result,
|  | int32_t | resultLength ) const

override virtual

Get the sort key as an array of bytes from a UnicodeString.

Note that sort keys are often less efficient than simply doing comparison. For more details, see the ICU User Guide.

Parameters

  source | string to be processed.
  result | buffer to store result in. If nullptr, number of bytes needed will be returned.
  resultLength | length of the result buffer. If if not enough the buffer will be filled to capacity.

Returns
  Number of bytes needed for storing the sort key

Stable
  ICU 2.0

Implements icu::Collator.

References U_I18N_API.

## getStaticClassID()

U_I18N_API UClassID icu::RuleBasedCollator::getStaticClassID | ( |  | ) |

static

Returns the class ID for this class.

This is useful only for comparing to a return value from getDynamicClassID(). For example:

    Base* polymorphic_pointer = createPolymorphicObject();
    if (polymorphic_pointer->getDynamicClassID() ==
                                             Derived::getStaticClassID()) ...

Returns
  The class ID for all objects of this class.

Stable
  ICU 2.0

References U_I18N_API.

## getTailoredSet()

virtual U_I18N_API UnicodeSet * icu::RuleBasedCollator::getTailoredSet | ( | UErrorCode & | status | ) | const

override virtual

Get a UnicodeSet that contains all the characters and sequences tailored in this collator.

Parameters

  status | error code of the operation

Returns
  a pointer to a UnicodeSet object containing all the code points and sequences that may sort differently than in the root collator. The object must be disposed of by using delete

Stable
  ICU 2.4

Reimplemented from icu::Collator.

References U_I18N_API.

## getVariableTop()

virtual U_I18N_API uint32_t icu::RuleBasedCollator::getVariableTop | ( | UErrorCode & | status | ) | const

override virtual

Gets the variable top value of a Collator.

Parameters

  status | error code (not changed by function). If error code is set, the return value is undefined.

Returns
  the variable top primary weight

See also
  getMaxVariable

Stable
  ICU 2.0

Implements icu::Collator.

References U_I18N_API.

## getVersion()

virtual U_I18N_API void icu::RuleBasedCollator::getVersion | ( | UVersionInfo | info | ) | const

override virtual

Gets the version information for a Collator.

Parameters

  info | the version # information, the result will be filled in

Stable
  ICU 2.0

Implements icu::Collator.

References U_I18N_API.

## hashCode()

virtual U_I18N_API int32_t icu::RuleBasedCollator::hashCode | ( |  | ) | const

override virtual

Generates the hash code for the rule-based collation object.

Returns
  the hash code.

Stable
  ICU 2.0

Implements icu::Collator.

References U_I18N_API.

## internalAddContractions()

U_I18N_API void icu::RuleBasedCollator::internalAddContractions | ( | UChar32 | c,
|  | UnicodeSet & | set,
|  | UErrorCode & | errorCode ) const

Adds the contractions that start with character c to the set.

Ignores prefixes. Used by AlphabeticIndex.

Internal
  Do not use. This API is for internal use only.

References U_I18N_API.

## internalBuildTailoring()

U_I18N_API void icu::RuleBasedCollator::internalBuildTailoring | ( | const UnicodeString & | rules,
|  | int32_t | strength,
|  | UColAttributeValue | decompositionMode,
|  | UParseError * | outParseError,
|  | UnicodeString * | outReason,
|  | UErrorCode & | errorCode )

Implements from-rule constructors, and ucol_openRules().

Internal
  Do not use. This API is for internal use only.

References U_I18N_API.

## internalCompareUTF8()

virtual U_I18N_API UCollationResult icu::RuleBasedCollator::internalCompareUTF8 | ( | const char * | left,
|  | int32_t | leftLength,
|  | const char * | right,
|  | int32_t | rightLength,
|  | UErrorCode & | errorCode ) const

override virtual

Implements ucol_strcollUTF8().

Internal
  Do not use. This API is for internal use only.

Reimplemented from icu::Collator.

References U_I18N_API.

## internalGetCEs()

U_I18N_API void icu::RuleBasedCollator::internalGetCEs | ( | const UnicodeString & | str,
|  | UVector64 & | ces,
|  | UErrorCode & | errorCode ) const

Appends the CEs for the string to the vector.

Internal
  Do not use. This API is for internal use only. for tests & tools

References U_I18N_API.

## internalGetContractionsAndExpansions()

U_I18N_API void icu::RuleBasedCollator::internalGetContractionsAndExpansions | ( | UnicodeSet * | contractions,
|  | UnicodeSet * | expansions,
|  | UBool | addPrefixes,
|  | UErrorCode & | errorCode ) const

Implements ucol_getContractionsAndExpansions().

Gets this collator's sets of contraction strings and/or characters and strings that map to multiple collation elements (expansions). If addPrefixes is true, then contractions that are expressed as prefix/pre-context rules are included.

Parameters

  contractions | if not nullptr, the set to hold the contractions
  expansions | if not nullptr, the set to hold the expansions
  addPrefixes | include prefix contextual mappings
  errorCode | in/out ICU error code

Internal
  Do not use. This API is for internal use only.

References U_I18N_API.

## internalGetLocaleID()

U_I18N_API const char * icu::RuleBasedCollator::internalGetLocaleID | ( | ULocDataLocaleType | type,
|  | UErrorCode & | errorCode ) const

Implements ucol_getLocaleByType().

Needed because the lifetime of the locale ID string must match that of the collator. getLocale() returns a copy of a Locale, with minimal lifetime in a C wrapper.

Internal
  Do not use. This API is for internal use only.

References U_I18N_API.

## internalGetShortDefinitionString()

virtual U_I18N_API int32_t icu::RuleBasedCollator::internalGetShortDefinitionString | ( | const char * | locale,
|  | char * | buffer,
|  | int32_t | capacity,
|  | UErrorCode & | status ) const

override virtual

Get the short definition string for a collator.

This internal API harvests the collator's locale and the attribute set and produces a string that can be used for opening a collator with the same attributes using the ucol_openFromShortString API. This string will be normalized. The structure and the syntax of the string is defined in the "Naming collators" section of the users guide: https://unicode-org.github.io/icu/userguide/collation/concepts#collator-naming-scheme This function supports preflighting.

This is internal, and intended to be used with delegate converters.

Parameters

  locale | a locale that will appear as a collators locale in the resulting short string definition. If nullptr, the locale will be harvested from the collator.
  buffer | space to hold the resulting string
  capacity | capacity of the buffer
  status | for returning errors. All the preflighting errors are featured

Returns
  length of the resulting string

See also
  ucol_openFromShortString
  ucol_normalizeShortDefinitionString
  ucol_getShortDefinitionString

Internal
  Do not use. This API is for internal use only.

Reimplemented from icu::Collator.

References U_I18N_API.

## internalNextSortKeyPart()

virtual U_I18N_API int32_t icu::RuleBasedCollator::internalNextSortKeyPart | ( | UCharIterator * | iter,
|  | uint32_t | state[2],
|  | uint8_t * | dest,
|  | int32_t | count,
|  | UErrorCode & | errorCode ) const

override virtual

Implements ucol_nextSortKeyPart().

Internal
  Do not use. This API is for internal use only.

Reimplemented from icu::Collator.

References U_I18N_API.

## operator=()

U_I18N_API RuleBasedCollator & icu::RuleBasedCollator::operator= | ( | const RuleBasedCollator & | other | ) |

Assignment operator.

Parameters

  other | other RuleBasedCollator object to copy from.

Stable
  ICU 2.0

References RuleBasedCollator(), and U_I18N_API.

## operator==()

virtual U_I18N_API bool icu::RuleBasedCollator::operator== | ( | const Collator & | other | ) | const

override virtual

Returns true if argument is the same as this object.

Parameters

  other | Collator object to be compared.

Returns
  true if arguments is the same as this object.

Stable
  ICU 2.0

Reimplemented from icu::Collator.

References U_I18N_API.

## rbcFromUCollator() [1/2]

const RuleBasedCollator * icu::RuleBasedCollator::rbcFromUCollator | ( | const UCollator * | uc | ) |

inline static

Internal
  Do not use. This API is for internal use only.

Definition at line 799 of file tblcoll.h.

References icu::Collator::fromUCollator(), and RuleBasedCollator().

## rbcFromUCollator() [2/2]

RuleBasedCollator * icu::RuleBasedCollator::rbcFromUCollator | ( | UCollator * | uc | ) |

inline static

Internal
  Do not use. This API is for internal use only.

Definition at line 795 of file tblcoll.h.

References icu::Collator::fromUCollator(), and RuleBasedCollator().

## setAttribute()

virtual U_I18N_API void icu::RuleBasedCollator::setAttribute | ( | UColAttribute | attr,
|  | UColAttributeValue | value,
|  | UErrorCode & | status )

override virtual

Universal attribute setter.

Parameters

  attr | attribute type
  value | attribute value
  status | to indicate whether the operation went on smoothly or there were errors

Stable
  ICU 2.2

Implements icu::Collator.

References U_I18N_API.

## setLocales()

virtual void icu::RuleBasedCollator::setLocales | ( | const Locale & | requestedLocale,
|  | const Locale & | validLocale,
|  | const Locale & | actualLocale )

override protected virtual

Used internally by registration to define the requested and valid locales.

Parameters

  requestedLocale | the requested locale
  validLocale | the valid locale
  actualLocale | the actual locale

Internal
  Do not use. This API is for internal use only.

Reimplemented from icu::Collator.

References RuleBasedCollator(), and UCOL_ATTRIBUTE_COUNT.

## setMaxVariable()

virtual U_I18N_API Collator & icu::RuleBasedCollator::setMaxVariable | ( | UColReorderCode | group,
|  | UErrorCode & | errorCode )

override virtual

Sets the variable top to the top of the specified reordering group.

The variable top determines the highest-sorting character which is affected by UCOL_ALTERNATE_HANDLING. If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect.

Parameters

  group | one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  *this

See also
  getMaxVariable

Stable
  ICU 53

Reimplemented from icu::Collator.

References U_I18N_API.

## setReorderCodes()

virtual U_I18N_API void icu::RuleBasedCollator::setReorderCodes | ( | const int32_t * | reorderCodes,
|  | int32_t | reorderCodesLength,
|  | UErrorCode & | status )

override virtual

Sets the ordering of scripts for this collator.

Parameters

  reorderCodes | An array of script codes in the new order. This can be nullptr if the length is also set to 0. An empty array will clear any reordering codes on the collator.
  reorderCodesLength | The length of reorderCodes.
  status | error code

See also
  ucol_setReorderCodes
  Collator::getReorderCodes
  Collator::getEquivalentReorderCodes

Stable
  ICU 4.8

Reimplemented from icu::Collator.

References U_I18N_API.

## setVariableTop() [1/3]

virtual U_I18N_API uint32_t icu::RuleBasedCollator::setVariableTop | ( | const char16_t * | varTop,
|  | int32_t | len,
|  | UErrorCode & | status )

override virtual

Sets the variable top to the primary weight of the specified string.

Beginning with ICU 53, the variable top is pinned to the top of one of the supported reordering groups, and it must not be beyond the last of those groups. See setMaxVariable().

Parameters

  varTop | one or more (if contraction) char16_ts to which the variable top should be set
  len | length of variable top string. If -1 it is considered to be zero terminated.
  status | error code. If error code is set, the return value is undefined. Errors set by this function are: U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond the last reordering group supported by setMaxVariable()

Returns
  variable top primary weight

Deprecated
  ICU 53 Call setMaxVariable() instead.

Implements icu::Collator.

References U_I18N_API.

## setVariableTop() [2/3]

virtual U_I18N_API uint32_t icu::RuleBasedCollator::setVariableTop | ( | const UnicodeString & | varTop,
|  | UErrorCode & | status )

override virtual

Sets the variable top to the primary weight of the specified string.

Beginning with ICU 53, the variable top is pinned to the top of one of the supported reordering groups, and it must not be beyond the last of those groups. See setMaxVariable().

Parameters

  varTop | a UnicodeString size 1 or more (if contraction) of char16_ts to which the variable top should be set
  status | error code. If error code is set, the return value is undefined. Errors set by this function are: U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond the last reordering group supported by setMaxVariable()

Returns
  variable top primary weight

Deprecated
  ICU 53 Call setMaxVariable() instead.

Implements icu::Collator.

References U_I18N_API.

## setVariableTop() [3/3]

virtual U_I18N_API void icu::RuleBasedCollator::setVariableTop | ( | uint32_t | varTop,
|  | UErrorCode & | status )

override virtual

Sets the variable top to the specified primary weight.

Beginning with ICU 53, the variable top is pinned to the top of one of the supported reordering groups, and it must not be beyond the last of those groups. See setMaxVariable().

Parameters

  varTop | primary weight, as returned by setVariableTop or ucol_getVariableTop
  status | error code

Deprecated
  ICU 53 Call setMaxVariable() instead.

Implements icu::Collator.

References U_I18N_API.

## Friends And Related Symbol Documentation

## CollationElementIterator

friend class CollationElementIterator

friend

Definition at line 823 of file tblcoll.h.

## Collator

friend class Collator

friend

Definition at line 824 of file tblcoll.h.

The documentation for this class was generated from the following file:

- i18n/unicode/tblcoll.h