Collator class performs locale-sensitive string
* comparison.
* Collator is an abstract base class. Subclasses implement
* specific collation strategies. One subclass,
* RuleBasedCollator, is currently provided and is applicable
* to a wide set of languages. Other subclasses may be created to handle more
* specialized needs.
*
* Like other locale-sensitive classes, you can use the static factory method,
* createInstance, to obtain the appropriate
* Collator object for a given locale. You will only need to
* look at the subclasses of Collator if you need to
* understand the details of a particular collation strategy or if you need to
* modify that strategy.
*
* The following example shows how to compare two strings using the
* Collator for the default locale.
* \htmlonly
\endhtmlonly
*
* \code
* // Compare two strings in the default locale
* UErrorCode success = U_ZERO_ERROR;
* Collator* myCollator = Collator::createInstance(success);
* if (myCollator->compare("abc", "ABC") < 0)
* cout << "abc is less than ABC" << endl;
* else
* cout << "abc is greater than or equal to ABC" << endl;
* \endcode
*
* \htmlonly\endhtmlonly
*
* You can set a Collator's strength attribute to
* determine the level of difference considered significant in comparisons.
* Five strengths are provided: PRIMARY, SECONDARY,
* TERTIARY, QUATERNARY and IDENTICAL.
* The exact assignment of strengths to language features is locale dependent.
* For example, in Czech, "e" and "f" are considered primary differences,
* while "e" and "\u00EA" are secondary differences, "e" and "E" are tertiary
* differences and "e" and "e" are identical. The following shows how both case
* and accents could be ignored for US English.
* \htmlonly
\endhtmlonly
*
* \code
* //Get the Collator for US English and set its strength to PRIMARY
* UErrorCode success = U_ZERO_ERROR;
* Collator* usCollator = Collator::createInstance(Locale::getUS(), success);
* usCollator->setStrength(Collator::PRIMARY);
* if (usCollator->compare("abc", "ABC") == 0)
* cout << "'abc' and 'ABC' strings are equivalent with strength PRIMARY" << endl;
* \endcode
*
* \htmlonly\endhtmlonly
*
* The getSortKey methods
* convert a string to a series of bytes that can be compared bitwise against
* other sort keys using strcmp(). Sort keys are written as
* zero-terminated byte strings.
*
* Another set of APIs returns a CollationKey object that wraps
* the sort key bytes instead of returning the bytes themselves.
*
*
* Note: Collators with different Locale,
* and CollationStrength settings will return different sort
* orders for the same set of strings. Locales have specific collation rules,
* and the way in which secondary and tertiary differences are taken into
* account, for example, will result in a different sorting order for same
* strings.
*
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);
*
* @param source the source string array to be compared with.
* @param sourceLength the length of the source string array. If this value
* is equal to -1, the string array is null-terminated.
* @param target the string that is to be compared with the source string.
* @param targetLength the length of the target string array. If this value
* is equal to -1, the string array is null-terminated.
* @return 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 &
*/
virtual EComparisonResult compare(const char16_t* source, int32_t sourceLength,
const char16_t* target, int32_t targetLength)
const;
#endif // U_FORCE_HIDE_DEPRECATED_API
/**
* 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.
* @param source the source string array to be compared with.
* @param sourceLength the length of the source string array. If this value
* is equal to -1, the string array is null-terminated.
* @param target the string that is to be compared with the source string.
* @param targetLength the length of the target string array. If this value
* is equal to -1, the string array is null-terminated.
* @param status possible error code
* @return 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
*/
virtual UCollationResult compare(const char16_t* source, int32_t sourceLength,
const char16_t* target, int32_t targetLength,
UErrorCode &status) const = 0;
/**
* 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.
* @param sIter the first ("source") string iterator
* @param tIter the second ("target") string iterator
* @param status ICU status
* @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
* @stable ICU 4.2
*/
virtual UCollationResult compare(UCharIterator &sIter,
UCharIterator &tIter,
UErrorCode &status) const;
/**
* 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.
* @param source the first UTF-8 string
* @param target the second UTF-8 string
* @param status ICU status
* @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
* @stable ICU 4.2
*/
virtual UCollationResult compareUTF8(const StringPiece &source,
const StringPiece &target,
UErrorCode &status) const;
/**
* Transforms the string into a series of characters that can be compared
* with CollationKey::compareTo. It is not possible to restore the original
* string from the chars in the sort key.
* Use CollationKey::equals or CollationKey::compare to compare the * generated sort keys. * If the source string is null, a null collation key will be returned. * * Note that sort keys are often less efficient than simply doing comparison. * For more details, see the ICU User Guide. * * @param source the source string to be transformed into a sort key. * @param key the collation key to be filled in * @param status the error code status. * @return the collation key of the string based on the collation rules. * @see CollationKey#compare * @stable ICU 2.0 */ virtual CollationKey& getCollationKey(const UnicodeString& source, CollationKey& key, UErrorCode& status) const = 0; /** * Transforms the string into a series of characters that can be compared * with CollationKey::compareTo. It is not possible to restore the original * string from the chars in the sort key. *
Use CollationKey::equals or CollationKey::compare to compare the * generated sort keys. *
If the source string is null, a null collation key will be returned. * * Note that sort keys are often less efficient than simply doing comparison. * For more details, see the ICU User Guide. * * @param source the source string to be transformed into a sort key. * @param sourceLength length of the collation key * @param key the collation key to be filled in * @param status the error code status. * @return the collation key of the string based on the collation rules. * @see CollationKey#compare * @stable ICU 2.0 */ virtual CollationKey& getCollationKey(const char16_t*source, int32_t sourceLength, CollationKey& key, UErrorCode& status) const = 0; /** * Generates the hash code for the collation object * @stable ICU 2.0 */ virtual int32_t hashCode(void) const = 0; #ifndef U_FORCE_HIDE_DEPRECATED_API /** * Gets the locale of the Collator * * @param type can be either requested, valid or actual locale. For more * information see the definition of ULocDataLocaleType in * uloc.h * @param status the error code status. * @return locale where the collation data lives. If the collator * was instantiated from rules, locale is empty. * @deprecated ICU 2.8 This API is under consideration for revision * in ICU 3.0. */ virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0; #endif // U_FORCE_HIDE_DEPRECATED_API /** * Convenience method for comparing two strings based on the collation rules. * @param source the source string to be compared with. * @param target the target string to be compared with. * @return true if the first string is greater than the second one, * according to the collation rules. false, otherwise. * @see Collator#compare * @stable ICU 2.0 */ UBool greater(const UnicodeString& source, const UnicodeString& target) const; /** * Convenience method for comparing two strings based on the collation rules. * @param source the source string to be compared with. * @param target the target string to be compared with. * @return true if the first string is greater than or equal to the second * one, according to the collation rules. false, otherwise. * @see Collator#compare * @stable ICU 2.0 */ UBool greaterOrEqual(const UnicodeString& source, const UnicodeString& target) const; /** * Convenience method for comparing two strings based on the collation rules. * @param source the source string to be compared with. * @param target the target string to be compared with. * @return true if the strings are equal according to the collation rules. * false, otherwise. * @see Collator#compare * @stable ICU 2.0 */ UBool equals(const UnicodeString& source, const UnicodeString& target) const; #ifndef U_FORCE_HIDE_DEPRECATED_API /** * Determines the minimum strength that will be used in comparison or * transformation. *
E.g. with strength == SECONDARY, the tertiary difference is ignored *
E.g. with strength == PRIMARY, the secondary and tertiary difference * are ignored. * @return the current comparison level. * @see Collator#setStrength * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead */ virtual ECollationStrength getStrength(void) const; /** * Sets the minimum strength to be used in comparison or transformation. *
Example of use: *
* \code
* UErrorCode status = U_ZERO_ERROR;
* Collator*myCollation = Collator::createInstance(Locale::getUS(), status);
* if (U_FAILURE(status)) return;
* myCollation->setStrength(Collator::PRIMARY);
* // result will be "abc" == "ABC"
* // tertiary differences will be ignored
* Collator::ComparisonResult result = myCollation->compare("abc", "ABC");
* \endcode
*
* @see Collator#getStrength
* @param newStrength the new comparison level.
* @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead
*/
virtual void setStrength(ECollationStrength newStrength);
#endif // U_FORCE_HIDE_DEPRECATED_API
/**
* Retrieves the reordering codes for this collator.
* @param dest The array to fill with the script ordering.
* @param 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).
* @param status A reference to an error code value, which must not indicate
* a failure before the function call.
* @return The length of the script ordering array.
* @see ucol_setReorderCodes
* @see Collator#getEquivalentReorderCodes
* @see Collator#setReorderCodes
* @see UScriptCode
* @see UColReorderCode
* @stable ICU 4.8
*/
virtual int32_t getReorderCodes(int32_t *dest,
int32_t destCapacity,
UErrorCode& status) const;
/**
* Sets the ordering of scripts for this collator.
*
* The reordering codes are a combination of script codes and reorder codes. * @param 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. * @param reorderCodesLength The length of reorderCodes. * @param status error code * @see ucol_setReorderCodes * @see Collator#getReorderCodes * @see Collator#getEquivalentReorderCodes * @see UScriptCode * @see UColReorderCode * @stable ICU 4.8 */ virtual void setReorderCodes(const int32_t* reorderCodes, int32_t reorderCodesLength, UErrorCode& status) ; /** * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder * codes will be grouped and must reorder together. * Beginning with ICU 55, scripts only reorder together if they are primary-equal, * for example Hiragana and Katakana. * * @param reorderCode The reorder code to determine equivalence for. * @param dest The array to fill with the script equivalence reordering codes. * @param 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). * @param status A reference to an error code value, which must not indicate * a failure before the function call. * @return The length of the of the reordering code equivalence array. * @see ucol_setReorderCodes * @see Collator#getReorderCodes * @see Collator#setReorderCodes * @see UScriptCode * @see UColReorderCode * @stable ICU 4.8 */ static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode, int32_t* dest, int32_t destCapacity, UErrorCode& status); /** * Get name of the object for the desired Locale, in the desired language * @param objectLocale must be from getAvailableLocales * @param displayLocale specifies the desired locale for output * @param name the fill-in parameter of the return value * @return display-able name of the object for the object locale in the * desired language * @stable ICU 2.0 */ static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, const Locale& displayLocale, UnicodeString& name); /** * Get name of the object for the desired Locale, in the language of the * default locale. * @param objectLocale must be from getAvailableLocales * @param name the fill-in parameter of the return value * @return name of the object for the desired locale in the default language * @stable ICU 2.0 */ static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, UnicodeString& name); /** * Get the set of Locales for which Collations are installed. * *
Note this does not include locales supported by registered collators. * If collators might have been registered, use the overload of getAvailableLocales * that returns a StringEnumeration.
* * @param count the output parameter of number of elements in the locale list * @return the list of available locales for which collations are installed * @stable ICU 2.0 */ static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); /** * Return a StringEnumeration over the locales available at the time of the call, * including registered locales. If a severe error occurs (such as out of memory * condition) this will return null. If there is no locale data, an empty enumeration * will be returned. * @return a StringEnumeration over the locales available at the time of the call * @stable ICU 2.6 */ static StringEnumeration* U_EXPORT2 getAvailableLocales(void); /** * Create a string enumerator of all possible keywords that are relevant to * collation. At this point, the only recognized keyword for this * service is "collation". * @param status input-output error code * @return a string enumeration over locale strings. The caller is * responsible for closing the result. * @stable ICU 3.0 */ static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status); /** * Given a keyword, create a string enumeration of all values * for that keyword that are currently in use. * @param keyword a particular keyword as enumerated by * ucol_getKeywords. If any other keyword is passed in, status is set * to U_ILLEGAL_ARGUMENT_ERROR. * @param status input-output error code * @return a string enumeration over collation keyword values, or nullptr * upon error. The caller is responsible for deleting the result. * @stable ICU 3.0 */ static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status); /** * Given a key and a locale, returns an array of string values in a preferred * order that would make a difference. These are all and only those values where * the open (creation) of the service with the locale formed from the input locale * plus input keyword and that value has different behavior than creation with the * input locale alone. * @param keyword one of the keys supported by this service. For now, only * "collation" is supported. * @param locale the locale * @param commonlyUsed if set to true it will return only commonly used values * with the given locale in preferred order. Otherwise, * it will return all the available values for the locale. * @param status ICU status * @return a string enumeration over keyword values for the given key and the locale. * @stable ICU 4.2 */ static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale, UBool commonlyUsed, UErrorCode& status); /** * Return the functionally equivalent locale for the given * requested locale, with respect to given keyword, for the * collation service. If two locales return the same result, then * collators instantiated for these locales will behave * equivalently. The converse is not always true; two collators * may in fact be equivalent, but return different results, due to * internal details. The return result has no other meaning than * that stated above, and implies nothing as to the relationship * between the two locales. This is intended for use by * applications who wish to cache collators, or otherwise reuse * collators when possible. The functional equivalent may change * over time. For more information, please see the * Locales and Services section of the ICU User Guide. * @param keyword a particular keyword as enumerated by * ucol_getKeywords. * @param locale the requested locale * @param isAvailable reference to a fillin parameter that * indicates whether the requested locale was 'available' to the * collation service. A locale is defined as 'available' if it * physically exists within the collation locale data. * @param status reference to input-output error code * @return the functionally equivalent collation locale, or the root * locale upon error. * @stable ICU 3.0 */ static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale, UBool& isAvailable, UErrorCode& status); #if !UCONFIG_NO_SERVICE /** * Register a new Collator. The collator will be adopted. * Because ICU may choose to cache collators internally, this must be * called at application startup, prior to any calls to * Collator::createInstance to avoid undefined behavior. * @param toAdopt the Collator instance to be adopted * @param locale the locale with which the collator will be associated * @param status the in/out status code, no special meanings are assigned * @return a registry key that can be used to unregister this collator * @stable ICU 2.6 */ static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status); /** * Register a new CollatorFactory. The factory will be adopted. * Because ICU may choose to cache collators internally, this must be * called at application startup, prior to any calls to * Collator::createInstance to avoid undefined behavior. * @param toAdopt the CollatorFactory instance to be adopted * @param status the in/out status code, no special meanings are assigned * @return a registry key that can be used to unregister this collator * @stable ICU 2.6 */ static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status); /** * Unregister a previously-registered Collator or CollatorFactory * using the key returned from the register call. Key becomes * invalid after a successful call and should not be used again. * The object corresponding to the key will be deleted. * Because ICU may choose to cache collators internally, this should * be called during application shutdown, after all calls to * Collator::createInstance to avoid undefined behavior. * @param key the registry key returned by a previous call to registerInstance * @param status the in/out status code, no special meanings are assigned * @return true if the collator for the key was successfully unregistered * @stable ICU 2.6 */ static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status); #endif /* UCONFIG_NO_SERVICE */ /** * Gets the version information for a Collator. * @param info the version # information, the result will be filled in * @stable ICU 2.0 */ virtual void getVersion(UVersionInfo info) const = 0; /** * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. * 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. * @return 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 */ virtual UClassID getDynamicClassID(void) const override = 0; /** * Universal attribute setter * @param attr attribute type * @param value attribute value * @param status to indicate whether the operation went on smoothly or * there were errors * @stable ICU 2.2 */ virtual void setAttribute(UColAttribute attr, UColAttributeValue value, UErrorCode &status) = 0; /** * Universal attribute getter * @param attr attribute type * @param status to indicate whether the operation went on smoothly or * there were errors * @return attribute value * @stable ICU 2.2 */ virtual UColAttributeValue getAttribute(UColAttribute attr, UErrorCode &status) const = 0; /** * 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. * * The base class implementation sets U_UNSUPPORTED_ERROR. * @param 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 * @param 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.) * @return *this * @see getMaxVariable * @stable ICU 53 */ virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode); /** * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. * * The base class implementation returns UCOL_REORDER_CODE_PUNCTUATION. * @return the maximum variable reordering group. * @see setMaxVariable * @stable ICU 53 */ virtual UColReorderCode getMaxVariable() const; #ifndef U_FORCE_HIDE_DEPRECATED_API /** * 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(). * @param varTop one or more (if contraction) char16_ts to which the variable top should be set * @param len length of variable top string. If -1 it is considered to be zero terminated. * @param status error code. If error code is set, the return value is undefined. Errors set by this function are:* If standard locale display names are sufficient, Collator instances can * be registered using registerInstance instead.
** Note: if the collators are to be used from C APIs, they must be instances * of RuleBasedCollator.
* * @stable ICU 2.6 */ class U_I18N_API CollatorFactory : public UObject { public: /** * Destructor * @stable ICU 3.0 */ virtual ~CollatorFactory(); /** * Return true if this factory is visible. Default is true. * If not visible, the locales supported by this factory will not * be listed by getAvailableLocales. * @return true if the factory is visible. * @stable ICU 2.6 */ virtual UBool visible(void) const; /** * Return a collator for the provided locale. If the locale * is not supported, return nullptr. * @param loc the locale identifying the collator to be created. * @return a new collator if the locale is supported, otherwise nullptr. * @stable ICU 2.6 */ virtual Collator* createCollator(const Locale& loc) = 0; /** * Return the name of the collator for the objectLocale, localized for the displayLocale. * If objectLocale is not supported, or the factory is not visible, set the result string * to bogus. * @param objectLocale the locale identifying the collator * @param displayLocale the locale for which the display name of the collator should be localized * @param result an output parameter for the display name, set to bogus if not supported. * @return the display name * @stable ICU 2.6 */ virtual UnicodeString& getDisplayName(const Locale& objectLocale, const Locale& displayLocale, UnicodeString& result); /** * Return an array of all the locale names directly supported by this factory. * The number of names is returned in count. This array is owned by the factory. * Its contents must never change. * @param count output parameter for the number of locales supported by the factory * @param status the in/out error code * @return a pointer to an array of count UnicodeStrings. * @stable ICU 2.6 */ virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0; }; #endif /* UCONFIG_NO_SERVICE */ // Collator inline methods ----------------------------------------------- U_NAMESPACE_END #endif /* #if !UCONFIG_NO_COLLATION */ #endif /* U_SHOW_CPLUSPLUS_API */ #endif