ICU 76.1 76.1
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends
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:
icu::Collator icu::UObject icu::UMemory

Public Member Functions

 RuleBasedCollator (const UnicodeString &rules, UErrorCode &status)
 RuleBasedCollator constructor.
 
 RuleBasedCollator (const UnicodeString &rules, ECollationStrength collationStrength, UErrorCode &status)
 RuleBasedCollator constructor.
 
 RuleBasedCollator (const UnicodeString &rules, UColAttributeValue decompositionMode, UErrorCode &status)
 RuleBasedCollator constructor.
 
 RuleBasedCollator (const UnicodeString &rules, ECollationStrength collationStrength, UColAttributeValue decompositionMode, UErrorCode &status)
 RuleBasedCollator constructor.
 
 RuleBasedCollator (const UnicodeString &rules, UParseError &parseError, UnicodeString &reason, UErrorCode &errorCode)
 TODO: document & propose as public API.
 
 RuleBasedCollator (const RuleBasedCollator &other)
 Copy constructor.
 
 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 ~RuleBasedCollator ()
 Destructor.
 
RuleBasedCollatoroperator= (const RuleBasedCollator &other)
 Assignment operator.
 
virtual bool operator== (const Collator &other) const override
 Returns true if argument is the same as this object.
 
virtual RuleBasedCollatorclone () const override
 Makes a copy of this object.
 
virtual CollationElementIteratorcreateCollationElementIterator (const UnicodeString &source) const
 Creates a collation element iterator for the source string.
 
virtual CollationElementIteratorcreateCollationElementIterator (const CharacterIterator &source) const
 Creates a collation element iterator for the source.
 
virtual 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 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 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 UCollationResult compare (UCharIterator &sIter, UCharIterator &tIter, UErrorCode &status) const override
 Compares two strings using the Collator.
 
virtual UCollationResult compareUTF8 (const StringPiece &source, const StringPiece &target, UErrorCode &status) const override
 Compares two UTF-8 strings using the Collator.
 
virtual CollationKeygetCollationKey (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 CollationKeygetCollationKey (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 int32_t hashCode () const override
 Generates the hash code for the rule-based collation object.
 
virtual Locale getLocale (ULocDataLocaleType type, UErrorCode &status) const override
 Gets the locale of the Collator.
 
const UnicodeStringgetRules () const
 Gets the tailoring rules for this collator.
 
virtual void getVersion (UVersionInfo info) const override
 Gets the version information for a Collator.
 
int32_t getMaxExpansion (int32_t order) const
 Returns the maximum length of any expansion sequences that end with the specified comparison order.
 
virtual UClassID getDynamicClassID () const override
 Returns a unique class ID POLYMORPHICALLY.
 
uint8_tcloneRuleData (int32_t &length, UErrorCode &status) const
 Do not use this method: The caller and the ICU library might use different heaps.
 
int32_t cloneBinary (uint8_t *buffer, int32_t capacity, UErrorCode &status) const
 Creates a binary image of a collator.
 
void getRules (UColRuleOption delta, UnicodeString &buffer) const
 Returns current rules.
 
virtual void setAttribute (UColAttribute attr, UColAttributeValue value, UErrorCode &status) override
 Universal attribute setter.
 
virtual UColAttributeValue getAttribute (UColAttribute attr, UErrorCode &status) const override
 Universal attribute getter.
 
virtual CollatorsetMaxVariable (UColReorderCode group, UErrorCode &errorCode) override
 Sets the variable top to the top of the specified reordering group.
 
virtual UColReorderCode getMaxVariable () const override
 Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING.
 
virtual 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 uint32_t setVariableTop (const UnicodeString &varTop, UErrorCode &status) override
 Sets the variable top to the primary weight of the specified string.
 
virtual void setVariableTop (uint32_t varTop, UErrorCode &status) override
 Sets the variable top to the specified primary weight.
 
virtual uint32_t getVariableTop (UErrorCode &status) const override
 Gets the variable top value of a Collator.
 
virtual UnicodeSetgetTailoredSet (UErrorCode &status) const override
 Get a UnicodeSet that contains all the characters and sequences tailored in this collator.
 
virtual 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 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 int32_t getReorderCodes (int32_t *dest, int32_t destCapacity, UErrorCode &status) const override
 Retrieves the reordering codes for this collator.
 
virtual void setReorderCodes (const int32_t *reorderCodes, int32_t reorderCodesLength, UErrorCode &status) override
 Sets the ordering of scripts for this collator.
 
virtual UCollationResult internalCompareUTF8 (const char *left, int32_t leftLength, const char *right, int32_t rightLength, UErrorCode &errorCode) const override
 Implements ucol_strcollUTF8().
 
virtual int32_t internalGetShortDefinitionString (const char *locale, char *buffer, int32_t capacity, UErrorCode &status) const override
 Get the short definition string for a collator.
 
virtual int32_t internalNextSortKeyPart (UCharIterator *iter, uint32_t state[2], uint8_t *dest, int32_t count, UErrorCode &errorCode) const override
 Implements ucol_nextSortKeyPart().
 
 RuleBasedCollator ()
 Only for use in ucol_openRules().
 
const charinternalGetLocaleID (ULocDataLocaleType type, UErrorCode &errorCode) const
 Implements ucol_getLocaleByType().
 
void internalGetContractionsAndExpansions (UnicodeSet *contractions, UnicodeSet *expansions, UBool addPrefixes, UErrorCode &errorCode) const
 Implements ucol_getContractionsAndExpansions().
 
void internalAddContractions (UChar32 c, UnicodeSet &set, UErrorCode &errorCode) const
 Adds the contractions that start with character c to the set.
 
void internalBuildTailoring (const UnicodeString &rules, int32_t strength, UColAttributeValue decompositionMode, UParseError *outParseError, UnicodeString *outReason, UErrorCode &errorCode)
 Implements from-rule constructors, and ucol_openRules().
 
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 UCollationResult compare (const UnicodeString &source, const UnicodeString &target, UErrorCode &status) const=0
 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 UCollationResult compare (const UnicodeString &source, const UnicodeString &target, int32_t length, UErrorCode &status) const=0
 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.
 
virtual UCollationResult compare (const char16_t *source, int32_t sourceLength, const char16_t *target, int32_t targetLength, UErrorCode &status) const=0
 The comparison function compares the character data stored in two different string arrays.
 
virtual UCollationResult compare (UCharIterator &sIter, UCharIterator &tIter, UErrorCode &status) const
 Compares two strings using the Collator.
 
- 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 CollatorsafeClone () const
 Same as clone().
 
UCollatortoUCollator ()
 
const UCollatortoUCollator () const
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor.
 

Static Public Member Functions

static UClassID getStaticClassID ()
 Returns the class ID for this class.
 
static RuleBasedCollatorrbcFromUCollator (UCollator *uc)
 
static const RuleBasedCollatorrbcFromUCollator (const UCollator *uc)
 
- Static Public Member Functions inherited from icu::Collator
static CollatorcreateInstance (UErrorCode &err)
 Creates the Collator object for the current default locale.
 
static CollatorcreateInstance (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 UnicodeStringgetDisplayName (const Locale &objectLocale, const Locale &displayLocale, UnicodeString &name)
 Get name of the object for the desired Locale, in the desired language.
 
static UnicodeStringgetDisplayName (const Locale &objectLocale, UnicodeString &name)
 Get name of the object for the desired Locale, in the language of the default locale.
 
static const LocalegetAvailableLocales (int32_t &count)
 Get the set of Locales for which Collations are installed.
 
static StringEnumerationgetAvailableLocales ()
 Return a StringEnumeration over the locales available at the time of the call, including registered locales.
 
static StringEnumerationgetKeywords (UErrorCode &status)
 Create a string enumerator of all possible keywords that are relevant to collation.
 
static StringEnumerationgetKeywordValues (const char *keyword, UErrorCode &status)
 Given a keyword, create a string enumeration of all values for that keyword that are currently in use.
 
static StringEnumerationgetKeywordValuesForLocale (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 CollatorfromUCollator (UCollator *uc)
 
static const CollatorfromUCollator (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]

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
rulesthe collation rules to build the collation table from.
statusreporting a success or an error.
Stable:
ICU 2.0

◆ RuleBasedCollator() [2/8]

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
rulesthe collation rules to build the collation table from.
collationStrengthstrength for comparison
statusreporting a success or an error.
Stable:
ICU 2.0

◆ RuleBasedCollator() [3/8]

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
rulesthe collation rules to build the collation table from.
decompositionModethe normalisation mode
statusreporting a success or an error.
Stable:
ICU 2.0

◆ RuleBasedCollator() [4/8]

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
rulesthe collation rules to build the collation table from.
collationStrengthstrength for comparison
decompositionModethe normalisation mode
statusreporting a success or an error.
Stable:
ICU 2.0

◆ RuleBasedCollator() [5/8]

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.

◆ RuleBasedCollator() [6/8]

icu::RuleBasedCollator::RuleBasedCollator ( const RuleBasedCollator other)

Copy constructor.

Parameters
otherthe RuleBasedCollator object to be copied
Stable:
ICU 2.0

◆ RuleBasedCollator() [7/8]

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
binbinary image owned by the user and required through the lifetime of the collator
lengthsize of the image. If negative, the API will try to figure out the length of the image
baseBase 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.
statusfor catching errors
Returns
newly created collator
See also
cloneBinary
Stable:
ICU 3.4

◆ ~RuleBasedCollator()

virtual icu::RuleBasedCollator::~RuleBasedCollator ( )
virtual

Destructor.

Stable:
ICU 2.0

◆ RuleBasedCollator() [8/8]

icu::RuleBasedCollator::RuleBasedCollator ( )

Only for use in ucol_openRules().

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

Member Function Documentation

◆ clone()

virtual RuleBasedCollator * icu::RuleBasedCollator::clone ( ) const
overridevirtual

Makes a copy of this object.

Returns
a copy of this object, owned by the caller
Stable:
ICU 2.0

Implements icu::Collator.

◆ cloneBinary()

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
buffera fill-in buffer to receive the binary image
capacitycapacity of the destination buffer
statusfor catching errors
Returns
size of the image
See also
ucol_openBinary
Stable:
ICU 3.4

◆ cloneRuleData()

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
lengthReturns the length of the data, in bytes
statusthe error code status.
Returns
memory, owned by the caller, of size 'length' bytes.
Deprecated:
ICU 52. Use cloneBinary() instead.

◆ compare() [1/11]

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
sourcethe source string array to be compared with.
sourceLengththe length of the source string array. If this value is equal to -1, the string array is null-terminated.
targetthe string that is to be compared with the source string.
targetLengththe 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/11]

virtual UCollationResult icu::RuleBasedCollator::compare ( const char16_t source,
int32_t  sourceLength,
const char16_t target,
int32_t  targetLength,
UErrorCode status 
) const
overridevirtual

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
sourcethe source string array to be compared with.
sourceLengththe length of the source string array. If this value is equal to -1, the string array is null-terminated.
targetthe string that is to be compared with the source string.
targetLengththe length of the target string array. If this value is equal to -1, the string array is null-terminated.
statuspossible 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.

◆ compare() [3/11]

virtual UCollationResult icu::Collator::compare ( const char16_t source,
int32_t  sourceLength,
const char16_t target,
int32_t  targetLength,
UErrorCode status 
) 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.

Parameters
sourcethe source string array to be compared with.
sourceLengththe length of the source string array. If this value is equal to -1, the string array is null-terminated.
targetthe string that is to be compared with the source string.
targetLengththe length of the target string array. If this value is equal to -1, the string array is null-terminated.
statuspossible 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.

◆ compare() [4/11]

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
sourcethe source string to be compared with.
targetthe 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() [5/11]

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
sourcethe source string to be compared with.
targetthe string that is to be compared with the source string.
lengththe 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() [6/11]

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

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

Parameters
sourcethe source string to be compared with.
targetthe string that is to be compared with the source string.
lengththe length the comparison is limited to
statuspossible 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.

◆ compare() [7/11]

virtual UCollationResult icu::Collator::compare ( const UnicodeString source,
const UnicodeString target,
int32_t  length,
UErrorCode status 
) const
virtual

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

Parameters
sourcethe source string to be compared with.
targetthe string that is to be compared with the source string.
lengththe length the comparison is limited to
statuspossible 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.

◆ compare() [8/11]

virtual UCollationResult icu::RuleBasedCollator::compare ( const UnicodeString source,
const UnicodeString target,
UErrorCode status 
) const
overridevirtual

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
sourcethe source string to be compared with.
targetthe string that is to be compared with the source string.
statuspossible 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.

◆ compare() [9/11]

virtual UCollationResult icu::Collator::compare ( const UnicodeString source,
const UnicodeString target,
UErrorCode status 
) 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
sourcethe source string to be compared with.
targetthe string that is to be compared with the source string.
statuspossible 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.

◆ compare() [10/11]

virtual UCollationResult icu::Collator::compare ( UCharIterator sIter,
UCharIterator tIter,
UErrorCode status 
) const
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
sIterthe first ("source") string iterator
tIterthe second ("target") string iterator
statusICU status
Returns
UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
Stable:
ICU 4.2

Reimplemented from icu::Collator.

◆ compare() [11/11]

virtual UCollationResult icu::RuleBasedCollator::compare ( UCharIterator sIter,
UCharIterator tIter,
UErrorCode status 
) const
overridevirtual

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
sIterthe first ("source") string iterator
tIterthe second ("target") string iterator
statusICU status
Returns
UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
Stable:
ICU 4.2

Reimplemented from icu::Collator.

◆ compareUTF8()

virtual UCollationResult icu::RuleBasedCollator::compareUTF8 ( const StringPiece source,
const StringPiece target,
UErrorCode status 
) const
overridevirtual

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
sourcethe first UTF-8 string
targetthe second UTF-8 string
statusICU status
Returns
UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
Stable:
ICU 51

Reimplemented from icu::Collator.

◆ createCollationElementIterator() [1/2]

virtual CollationElementIterator * icu::RuleBasedCollator::createCollationElementIterator ( const CharacterIterator source) const
virtual

Creates a collation element iterator for the source.

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

Parameters
sourcethe 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

◆ createCollationElementIterator() [2/2]

virtual CollationElementIterator * icu::RuleBasedCollator::createCollationElementIterator ( const UnicodeString source) const
virtual

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
sourcethe 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

◆ getAttribute()

virtual UColAttributeValue icu::RuleBasedCollator::getAttribute ( UColAttribute  attr,
UErrorCode status 
) const
overridevirtual

Universal attribute getter.

Parameters
attrattribute type
statusto indicate whether the operation went on smoothly or there were errors
Returns
attribute value
Stable:
ICU 2.2

Implements icu::Collator.

◆ getCollationKey() [1/2]

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

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
sourcethe source string.
sourceLengththe length of the source string.
keythe transformed key of the source string.
statusthe error code status.
Returns
the transformed key.
See also
CollationKey
Stable:
ICU 2.0

Implements icu::Collator.

◆ getCollationKey() [2/2]

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

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
sourcethe source string.
keythe transformed key of the source string.
statusthe error code status.
Returns
the transformed key.
See also
CollationKey
Stable:
ICU 2.0

Implements icu::Collator.

◆ getDynamicClassID()

virtual UClassID icu::RuleBasedCollator::getDynamicClassID ( ) const
overridevirtual

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.

◆ getLocale()

virtual Locale icu::RuleBasedCollator::getLocale ( ULocDataLocaleType  type,
UErrorCode status 
) const
overridevirtual

Gets the locale of the Collator.

Parameters
typecan be either requested, valid or actual locale. For more information see the definition of ULocDataLocaleType in uloc.h
statusthe 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.

◆ getMaxExpansion()

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
ordera 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.

◆ getMaxVariable()

virtual UColReorderCode icu::RuleBasedCollator::getMaxVariable ( ) const
overridevirtual

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.

◆ getReorderCodes()

virtual int32_t icu::RuleBasedCollator::getReorderCodes ( int32_t dest,
int32_t  destCapacity,
UErrorCode status 
) const
overridevirtual

Retrieves the reordering codes for this collator.

Parameters
destThe array to fill with the script ordering.
destCapacityThe 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).
statusA 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.

◆ getRules() [1/2]

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

◆ getRules() [2/2]

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
deltaone of UCOL_TAILORING_ONLY, UCOL_FULL_RULES.
bufferUnicodeString to store the result rules
Stable:
ICU 2.2
See also
UCOL_FULL_RULES

◆ getSortKey() [1/2]

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

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
sourcestring to be processed.
sourceLengthlength of string to be processed. If -1, the string is 0 terminated and length will be decided by the function.
resultbuffer to store result in. If nullptr, number of bytes needed will be returned.
resultLengthlength 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.

◆ getSortKey() [2/2]

virtual int32_t icu::RuleBasedCollator::getSortKey ( const UnicodeString source,
uint8_t result,
int32_t  resultLength 
) const
overridevirtual

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
sourcestring to be processed.
resultbuffer to store result in. If nullptr, number of bytes needed will be returned.
resultLengthlength 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.

◆ getStaticClassID()

static 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

◆ getTailoredSet()

virtual UnicodeSet * icu::RuleBasedCollator::getTailoredSet ( UErrorCode status) const
overridevirtual

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

Parameters
statuserror 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.

◆ getVariableTop()

virtual uint32_t icu::RuleBasedCollator::getVariableTop ( UErrorCode status) const
overridevirtual

Gets the variable top value of a Collator.

Parameters
statuserror 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.

◆ getVersion()

virtual void icu::RuleBasedCollator::getVersion ( UVersionInfo  info) const
overridevirtual

Gets the version information for a Collator.

Parameters
infothe version # information, the result will be filled in
Stable:
ICU 2.0

Implements icu::Collator.

◆ hashCode()

virtual int32_t icu::RuleBasedCollator::hashCode ( ) const
overridevirtual

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

Returns
the hash code.
Stable:
ICU 2.0

Implements icu::Collator.

◆ internalAddContractions()

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.

◆ internalBuildTailoring()

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.

◆ internalCompareUTF8()

virtual UCollationResult icu::RuleBasedCollator::internalCompareUTF8 ( const char left,
int32_t  leftLength,
const char right,
int32_t  rightLength,
UErrorCode errorCode 
) const
overridevirtual

Implements ucol_strcollUTF8().

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

Reimplemented from icu::Collator.

◆ internalGetCEs()

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

◆ internalGetContractionsAndExpansions()

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
contractionsif not nullptr, the set to hold the contractions
expansionsif not nullptr, the set to hold the expansions
addPrefixesinclude prefix contextual mappings
errorCodein/out ICU error code
Internal:
Do not use. This API is for internal use only.

◆ internalGetLocaleID()

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.

◆ internalGetShortDefinitionString()

virtual int32_t icu::RuleBasedCollator::internalGetShortDefinitionString ( const char locale,
char buffer,
int32_t  capacity,
UErrorCode status 
) const
overridevirtual

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
localea locale that will appear as a collators locale in the resulting short string definition. If nullptr, the locale will be harvested from the collator.
bufferspace to hold the resulting string
capacitycapacity of the buffer
statusfor 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.

◆ internalNextSortKeyPart()

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

Implements ucol_nextSortKeyPart().

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

Reimplemented from icu::Collator.

◆ operator=()

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

Assignment operator.

Parameters
otherother RuleBasedCollator object to copy from.
Stable:
ICU 2.0

◆ operator==()

virtual bool icu::RuleBasedCollator::operator== ( const Collator other) const
overridevirtual

Returns true if argument is the same as this object.

Parameters
otherCollator object to be compared.
Returns
true if arguments is the same as this object.
Stable:
ICU 2.0

Reimplemented from icu::Collator.

◆ rbcFromUCollator() [1/2]

static const RuleBasedCollator * icu::RuleBasedCollator::rbcFromUCollator ( const UCollator uc)
inlinestatic
Internal:
Do not use. This API is for internal use only.

Definition at line 790 of file tblcoll.h.

References icu::Collator::fromUCollator().

◆ rbcFromUCollator() [2/2]

static RuleBasedCollator * icu::RuleBasedCollator::rbcFromUCollator ( UCollator uc)
inlinestatic
Internal:
Do not use. This API is for internal use only.

Definition at line 786 of file tblcoll.h.

References icu::Collator::fromUCollator().

◆ setAttribute()

virtual void icu::RuleBasedCollator::setAttribute ( UColAttribute  attr,
UColAttributeValue  value,
UErrorCode status 
)
overridevirtual

Universal attribute setter.

Parameters
attrattribute type
valueattribute value
statusto indicate whether the operation went on smoothly or there were errors
Stable:
ICU 2.2

Implements icu::Collator.

◆ setLocales()

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

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

Parameters
requestedLocalethe requested locale
validLocalethe valid locale
actualLocalethe actual locale
Internal:
Do not use. This API is for internal use only.

Reimplemented from icu::Collator.

◆ setMaxVariable()

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

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
groupone 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
errorCodeStandard 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.

◆ setReorderCodes()

virtual void icu::RuleBasedCollator::setReorderCodes ( const int32_t reorderCodes,
int32_t  reorderCodesLength,
UErrorCode status 
)
overridevirtual

Sets the ordering of scripts for this collator.

Parameters
reorderCodesAn 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.
reorderCodesLengthThe length of reorderCodes.
statuserror code
See also
ucol_setReorderCodes
Collator::getReorderCodes
Collator::getEquivalentReorderCodes
Stable:
ICU 4.8

Reimplemented from icu::Collator.

◆ setVariableTop() [1/3]

virtual uint32_t icu::RuleBasedCollator::setVariableTop ( const char16_t varTop,
int32_t  len,
UErrorCode status 
)
overridevirtual

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
varTopone or more (if contraction) char16_ts to which the variable top should be set
lenlength of variable top string. If -1 it is considered to be zero terminated.
statuserror 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.

◆ setVariableTop() [2/3]

virtual uint32_t icu::RuleBasedCollator::setVariableTop ( const UnicodeString varTop,
UErrorCode status 
)
overridevirtual

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
varTopa UnicodeString size 1 or more (if contraction) of char16_ts to which the variable top should be set
statuserror 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.

◆ setVariableTop() [3/3]

virtual void icu::RuleBasedCollator::setVariableTop ( uint32_t  varTop,
UErrorCode status 
)
overridevirtual

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
varTopprimary weight, as returned by setVariableTop or ucol_getVariableTop
statuserror code
Deprecated:
ICU 53 Call setMaxVariable() instead.

Implements icu::Collator.

Friends And Related Symbol Documentation

◆ CollationElementIterator

Definition at line 812 of file tblcoll.h.

◆ Collator

Definition at line 813 of file tblcoll.h.


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