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 property 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 dependant.
* 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::US, 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
*
* For comparing strings exactly once, the compare method
* provides the best performance. When sorting a list of strings however, it
* is generally necessary to compare each string multiple times. In this case,
* sort keys provide better performance. 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. They consist of several substrings, one for
* each collation strength level, that are delimited by 0x01 bytes.
* If the string code points are appended for UCOL_IDENTICAL, then they are
* processed for correct code point order comparison and may contain 0x01
* bytes but not zero bytes.
*
* An older set of APIs returns a CollationKey object that wraps
* the sort key bytes instead of returning the bytes themselves.
* Its use is deprecated, but it is still available for compatibility with
* Java.
*
* 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.
*
* Note: this API will be removed in a future release. Use * createInstance(const Locale&, UErrorCode&) instead.
* * @param loc The locale ID for which to open a collator. * @param version The requested collator version. * @param err A reference to a UErrorCode, * must not indicate a failure before calling this function. * @return A pointer to a Collator, or 0 if an error occurred * or a collator with the requested version is not available. * * @see getVersion * @obsolete ICU 2.6 */ static Collator *createInstance(const Locale &loc, UVersionInfo version, UErrorCode &err); #endif /** * 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. * @param source the source string to be compared with. * @param target the string that is to be compared with the source string. * @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 UnicodeString& source, const UnicodeString& target) const; /** * 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. * @param source the source string to be compared with. * @param target the string that is to be compared with the source string. * @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 UnicodeString& source, const UnicodeString& target, UErrorCode &status) const = 0; /** * Does the same thing as compare but limits the comparison to a specified * length * @param source the source string to be compared with. * @param target the string that is to be compared with the source string. * @param length the length the comparison is limited to * @return 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 & */ 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 * @param source the source string to be compared with. * @param target the string that is to be compared with the source string. * @param length the length the comparison is limited to * @param status possible error code * @return 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 */ virtual UCollationResult compare(const UnicodeString& source, const UnicodeString& target, int32_t length, UErrorCode &status) const = 0; /** * 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. * @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 UChar* source, int32_t sourceLength, const UChar* target, int32_t targetLength) const; /** * 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 UChar* source, int32_t sourceLength, const UChar* 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. The generated sort key handles * only a limited number of ignorable characters. *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. * @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 * @deprecated ICU 2.8 Use getSortKey(...) instead */ 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. The generated sort key handles * only a limited number of ignorable characters. *
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. * @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 * @deprecated ICU 2.8 Use getSortKey(...) instead */ virtual CollationKey& getCollationKey(const UChar*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; /** * 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 const Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0; /** * 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; /** * Determines the minimum strength that will be use 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 = 0; /** * 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::US, 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) = 0;
/**
* Get the current reordering of scripts (if one has been set).
* @param dest The array to fill with the script ordering.
* @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
* @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a failure before the function call.
* @return The length of the array of the script ordering.
* @see ucol_getReorderCodes
* @internal
*/
virtual int32_t getReorderCodes(int32_t *dest,
int32_t destCapacity,
UErrorCode& status) const;
/**
* Set the ordering of scripts for this collator.
* @param reorderCodes An array of reorder codes in the new order.
* @param reorderCodesLength The length of reorderCodes.
* @see ucol_setReorderCodes
* @internal
*/
virtual void setReorderCodes(const int32_t* reorderCodes,
int32_t reorderCodesLength,
UErrorCode& status) ;
/**
* Get name of the object for the desired Locale, in the desired langauge
* @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 langauge 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 NULL * 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. * @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. * @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. * @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 = 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) = 0; /** * Sets the variable top to a collation element value of a string supplied. * @param varTop one or more (if contraction) UChars 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 NULL. * @param loc the locale identifying the collator to be created. * @return a new collator if the locale is supported, otherwise NULL. * @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