jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ****************************************************************************** jpayne@69: * Copyright (C) 1996-2016, International Business Machines jpayne@69: * Corporation and others. All Rights Reserved. jpayne@69: ****************************************************************************** jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C++ API: Collation Service. jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * File coll.h jpayne@69: * jpayne@69: * Created by: Helena Shih jpayne@69: * jpayne@69: * Modification History: jpayne@69: * jpayne@69: * Date Name Description jpayne@69: * 02/5/97 aliu Modified createDefault to load collation data from jpayne@69: * binary files when possible. Added related methods jpayne@69: * createCollationFromFile, chopLocale, createPathName. jpayne@69: * 02/11/97 aliu Added members addToCache, findInCache, and fgCache. jpayne@69: * 02/12/97 aliu Modified to create objects from RuleBasedCollator cache. jpayne@69: * Moved cache out of Collation class. jpayne@69: * 02/13/97 aliu Moved several methods out of this class and into jpayne@69: * RuleBasedCollator, with modifications. Modified jpayne@69: * createDefault() to call new RuleBasedCollator(Locale&) jpayne@69: * constructor. General clean up and documentation. jpayne@69: * 02/20/97 helena Added clone, operator==, operator!=, operator=, copy jpayne@69: * constructor and getDynamicClassID. jpayne@69: * 03/25/97 helena Updated with platform independent data types. jpayne@69: * 05/06/97 helena Added memory allocation error detection. jpayne@69: * 06/20/97 helena Java class name change. jpayne@69: * 09/03/97 helena Added createCollationKeyValues(). jpayne@69: * 02/10/98 damiba Added compare() with length as parameter. jpayne@69: * 04/23/99 stephen Removed EDecompositionMode, merged with jpayne@69: * Normalizer::EMode. jpayne@69: * 11/02/99 helena Collator performance enhancements. Eliminates the jpayne@69: * UnicodeString construction and special case for NO_OP. jpayne@69: * 11/23/99 srl More performance enhancements. Inlining of jpayne@69: * critical accessors. jpayne@69: * 05/15/00 helena Added version information API. jpayne@69: * 01/29/01 synwee Modified into a C++ wrapper which calls C apis jpayne@69: * (ucol.h). jpayne@69: * 2012-2014 markus Rewritten in C++ again. jpayne@69: */ jpayne@69: jpayne@69: #ifndef COLL_H jpayne@69: #define COLL_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: #if !UCONFIG_NO_COLLATION jpayne@69: jpayne@69: #include "unicode/uobject.h" jpayne@69: #include "unicode/ucol.h" jpayne@69: #include "unicode/unorm.h" jpayne@69: #include "unicode/locid.h" jpayne@69: #include "unicode/uniset.h" jpayne@69: #include "unicode/umisc.h" jpayne@69: #include "unicode/uiter.h" jpayne@69: #include "unicode/stringpiece.h" jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: class StringEnumeration; jpayne@69: jpayne@69: #if !UCONFIG_NO_SERVICE jpayne@69: /** jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: class CollatorFactory; jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: class CollationKey; jpayne@69: jpayne@69: /** jpayne@69: * The Collator class performs locale-sensitive string jpayne@69: * comparison.
jpayne@69: * You use this class to build searching and sorting routines for natural jpayne@69: * language text. jpayne@69: *

jpayne@69: * Collator is an abstract base class. Subclasses implement jpayne@69: * specific collation strategies. One subclass, jpayne@69: * RuleBasedCollator, is currently provided and is applicable jpayne@69: * to a wide set of languages. Other subclasses may be created to handle more jpayne@69: * specialized needs. jpayne@69: *

jpayne@69: * Like other locale-sensitive classes, you can use the static factory method, jpayne@69: * createInstance, to obtain the appropriate jpayne@69: * Collator object for a given locale. You will only need to jpayne@69: * look at the subclasses of Collator if you need to jpayne@69: * understand the details of a particular collation strategy or if you need to jpayne@69: * modify that strategy. jpayne@69: *

jpayne@69: * The following example shows how to compare two strings using the jpayne@69: * Collator for the default locale. jpayne@69: * \htmlonly

\endhtmlonly jpayne@69: * 
jpayne@69: * \code
jpayne@69: * // Compare two strings in the default locale
jpayne@69: * UErrorCode success = U_ZERO_ERROR;
jpayne@69: * Collator* myCollator = Collator::createInstance(success);
jpayne@69: * if (myCollator->compare("abc", "ABC") < 0)
jpayne@69: *   cout << "abc is less than ABC" << endl;
jpayne@69: * else
jpayne@69: *   cout << "abc is greater than or equal to ABC" << endl;
jpayne@69: * \endcode
jpayne@69: *
jpayne@69: * \htmlonly
\endhtmlonly jpayne@69: *

jpayne@69: * You can set a Collator's strength attribute to jpayne@69: * determine the level of difference considered significant in comparisons. jpayne@69: * Five strengths are provided: PRIMARY, SECONDARY, jpayne@69: * TERTIARY, QUATERNARY and IDENTICAL. jpayne@69: * The exact assignment of strengths to language features is locale dependent. jpayne@69: * For example, in Czech, "e" and "f" are considered primary differences, jpayne@69: * while "e" and "\u00EA" are secondary differences, "e" and "E" are tertiary jpayne@69: * differences and "e" and "e" are identical. The following shows how both case jpayne@69: * and accents could be ignored for US English. jpayne@69: * \htmlonly

\endhtmlonly jpayne@69: * 
jpayne@69: * \code
jpayne@69: * //Get the Collator for US English and set its strength to PRIMARY
jpayne@69: * UErrorCode success = U_ZERO_ERROR;
jpayne@69: * Collator* usCollator = Collator::createInstance(Locale::getUS(), success);
jpayne@69: * usCollator->setStrength(Collator::PRIMARY);
jpayne@69: * if (usCollator->compare("abc", "ABC") == 0)
jpayne@69: *     cout << "'abc' and 'ABC' strings are equivalent with strength PRIMARY" << endl;
jpayne@69: * \endcode
jpayne@69: *
jpayne@69: * \htmlonly
\endhtmlonly jpayne@69: * jpayne@69: * The getSortKey methods jpayne@69: * convert a string to a series of bytes that can be compared bitwise against jpayne@69: * other sort keys using strcmp(). Sort keys are written as jpayne@69: * zero-terminated byte strings. jpayne@69: * jpayne@69: * Another set of APIs returns a CollationKey object that wraps jpayne@69: * the sort key bytes instead of returning the bytes themselves. jpayne@69: *

jpayne@69: *

jpayne@69: * Note: Collators with different Locale, jpayne@69: * and CollationStrength settings will return different sort jpayne@69: * orders for the same set of strings. Locales have specific collation rules, jpayne@69: * and the way in which secondary and tertiary differences are taken into jpayne@69: * account, for example, will result in a different sorting order for same jpayne@69: * strings. jpayne@69: *

jpayne@69: * @see RuleBasedCollator jpayne@69: * @see CollationKey jpayne@69: * @see CollationElementIterator jpayne@69: * @see Locale jpayne@69: * @see Normalizer2 jpayne@69: * @version 2.0 11/15/01 jpayne@69: */ jpayne@69: jpayne@69: class U_I18N_API Collator : public UObject { jpayne@69: public: jpayne@69: jpayne@69: // Collator public enums ----------------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Base letter represents a primary difference. Set comparison level to jpayne@69: * PRIMARY to ignore secondary and tertiary differences.
jpayne@69: * Use this to set the strength of a Collator object.
jpayne@69: * Example of primary difference, "abc" < "abd" jpayne@69: * jpayne@69: * Diacritical differences on the same base letter represent a secondary jpayne@69: * difference. Set comparison level to SECONDARY to ignore tertiary jpayne@69: * differences. Use this to set the strength of a Collator object.
jpayne@69: * Example of secondary difference, "ä" >> "a". jpayne@69: * jpayne@69: * Uppercase and lowercase versions of the same character represents a jpayne@69: * tertiary difference. Set comparison level to TERTIARY to include all jpayne@69: * comparison differences. Use this to set the strength of a Collator jpayne@69: * object.
jpayne@69: * Example of tertiary difference, "abc" <<< "ABC". jpayne@69: * jpayne@69: * Two characters are considered "identical" when they have the same unicode jpayne@69: * spellings.
jpayne@69: * For example, "ä" == "ä". jpayne@69: * jpayne@69: * UCollationStrength is also used to determine the strength of sort keys jpayne@69: * generated from Collator objects. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum ECollationStrength jpayne@69: { jpayne@69: PRIMARY = UCOL_PRIMARY, // 0 jpayne@69: SECONDARY = UCOL_SECONDARY, // 1 jpayne@69: TERTIARY = UCOL_TERTIARY, // 2 jpayne@69: QUATERNARY = UCOL_QUATERNARY, // 3 jpayne@69: IDENTICAL = UCOL_IDENTICAL // 15 jpayne@69: }; jpayne@69: jpayne@69: jpayne@69: // Cannot use #ifndef U_HIDE_DEPRECATED_API for the following, it is jpayne@69: // used by virtual methods that cannot have that conditional. jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * LESS is returned if source string is compared to be less than target jpayne@69: * string in the compare() method. jpayne@69: * EQUAL is returned if source string is compared to be equal to target jpayne@69: * string in the compare() method. jpayne@69: * GREATER is returned if source string is compared to be greater than jpayne@69: * target string in the compare() method. jpayne@69: * @see Collator#compare jpayne@69: * @deprecated ICU 2.6. Use C enum UCollationResult defined in ucol.h jpayne@69: */ jpayne@69: enum EComparisonResult jpayne@69: { jpayne@69: LESS = UCOL_LESS, // -1 jpayne@69: EQUAL = UCOL_EQUAL, // 0 jpayne@69: GREATER = UCOL_GREATER // 1 jpayne@69: }; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: // Collator public destructor ----------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Destructor jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual ~Collator(); jpayne@69: jpayne@69: // Collator public methods -------------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Returns TRUE if "other" is the same as "this". jpayne@69: * jpayne@69: * The base class implementation returns TRUE if "other" has the same type/class as "this": jpayne@69: * `typeid(*this) == typeid(other)`. jpayne@69: * jpayne@69: * Subclass implementations should do something like the following: jpayne@69: * jpayne@69: * if (this == &other) { return TRUE; } jpayne@69: * if (!Collator::operator==(other)) { return FALSE; } // not the same class jpayne@69: * jpayne@69: * const MyCollator &o = (const MyCollator&)other; jpayne@69: * (compare this vs. o's subclass fields) jpayne@69: * jpayne@69: * @param other Collator object to be compared jpayne@69: * @return TRUE if other is the same as this. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual UBool operator==(const Collator& other) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns true if "other" is not the same as "this". jpayne@69: * Calls ! operator==(const Collator&) const which works for all subclasses. jpayne@69: * @param other Collator object to be compared jpayne@69: * @return TRUE if other is not the same as this. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual UBool operator!=(const Collator& other) const; jpayne@69: jpayne@69: /** jpayne@69: * Makes a copy of this object. jpayne@69: * @return a copy of this object, owned by the caller jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual Collator* clone() const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Creates the Collator object for the current default locale. jpayne@69: * The default locale is determined by Locale::getDefault. jpayne@69: * The UErrorCode& err parameter is used to return status information to the user. jpayne@69: * To check whether the construction succeeded or not, you should check the jpayne@69: * value of U_SUCCESS(err). If you wish more detailed information, you can jpayne@69: * check for informational error results which still indicate success. jpayne@69: * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For jpayne@69: * example, 'de_CH' was requested, but nothing was found there, so 'de' was jpayne@69: * used. U_USING_DEFAULT_ERROR indicates that the default locale data was jpayne@69: * used; neither the requested locale nor any of its fall back locales jpayne@69: * could be found. jpayne@69: * The caller owns the returned object and is responsible for deleting it. jpayne@69: * jpayne@69: * @param err the error code status. jpayne@69: * @return the collation object of the default locale.(for example, en_US) jpayne@69: * @see Locale#getDefault jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: static Collator* U_EXPORT2 createInstance(UErrorCode& err); jpayne@69: jpayne@69: /** jpayne@69: * Gets the collation object for the desired locale. The jpayne@69: * resource of the desired locale will be loaded. jpayne@69: * jpayne@69: * Locale::getRoot() is the base collation table and all other languages are jpayne@69: * built on top of it with additional language-specific modifications. jpayne@69: * jpayne@69: * For some languages, multiple collation types are available; jpayne@69: * for example, "de@collation=phonebook". jpayne@69: * Starting with ICU 54, collation attributes can be specified via locale keywords as well, jpayne@69: * in the old locale extension syntax ("el@colCaseFirst=upper") jpayne@69: * or in language tag syntax ("el-u-kf-upper"). jpayne@69: * See User Guide: Collation API. jpayne@69: * jpayne@69: * The UErrorCode& err parameter is used to return status information to the user. jpayne@69: * To check whether the construction succeeded or not, you should check jpayne@69: * the value of U_SUCCESS(err). If you wish more detailed information, you jpayne@69: * can check for informational error results which still indicate success. jpayne@69: * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For jpayne@69: * example, 'de_CH' was requested, but nothing was found there, so 'de' was jpayne@69: * used. U_USING_DEFAULT_ERROR indicates that the default locale data was jpayne@69: * used; neither the requested locale nor any of its fall back locales jpayne@69: * could be found. jpayne@69: * jpayne@69: * The caller owns the returned object and is responsible for deleting it. jpayne@69: * @param loc The locale ID for which to open a collator. jpayne@69: * @param err the error code status. jpayne@69: * @return the created table-based collation object based on the desired jpayne@69: * locale. jpayne@69: * @see Locale jpayne@69: * @see ResourceLoader jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err); jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * The comparison function compares the character data stored in two jpayne@69: * different strings. Returns information about whether a string is less jpayne@69: * than, greater than or equal to another string. jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @return Returns a byte value. GREATER if source is greater jpayne@69: * than target; EQUAL if source is equal to target; LESS if source is less jpayne@69: * than target jpayne@69: * @deprecated ICU 2.6 use the overload with UErrorCode & jpayne@69: */ jpayne@69: virtual EComparisonResult compare(const UnicodeString& source, jpayne@69: const UnicodeString& target) const; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * The comparison function compares the character data stored in two jpayne@69: * different strings. Returns information about whether a string is less jpayne@69: * than, greater than or equal to another string. jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param status possible error code jpayne@69: * @return Returns an enum value. UCOL_GREATER if source is greater jpayne@69: * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less jpayne@69: * than target jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual UCollationResult compare(const UnicodeString& source, jpayne@69: const UnicodeString& target, jpayne@69: UErrorCode &status) const = 0; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Does the same thing as compare but limits the comparison to a specified jpayne@69: * length jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param length the length the comparison is limited to jpayne@69: * @return Returns a byte value. GREATER if source (up to the specified jpayne@69: * length) is greater than target; EQUAL if source (up to specified jpayne@69: * length) is equal to target; LESS if source (up to the specified jpayne@69: * length) is less than target. jpayne@69: * @deprecated ICU 2.6 use the overload with UErrorCode & jpayne@69: */ jpayne@69: virtual EComparisonResult compare(const UnicodeString& source, jpayne@69: const UnicodeString& target, jpayne@69: int32_t length) const; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * Does the same thing as compare but limits the comparison to a specified jpayne@69: * length jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param length the length the comparison is limited to jpayne@69: * @param status possible error code jpayne@69: * @return Returns an enum value. UCOL_GREATER if source (up to the specified jpayne@69: * length) is greater than target; UCOL_EQUAL if source (up to specified jpayne@69: * length) is equal to target; UCOL_LESS if source (up to the specified jpayne@69: * length) is less than target. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual UCollationResult compare(const UnicodeString& source, jpayne@69: const UnicodeString& target, jpayne@69: int32_t length, jpayne@69: UErrorCode &status) const = 0; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * The comparison function compares the character data stored in two jpayne@69: * different string arrays. Returns information about whether a string array jpayne@69: * is less than, greater than or equal to another string array. jpayne@69: *

Example of use: jpayne@69: * 

jpayne@69:      * .       char16_t ABC[] = {0x41, 0x42, 0x43, 0};  // = "ABC"
jpayne@69:      * .       char16_t abc[] = {0x61, 0x62, 0x63, 0};  // = "abc"
jpayne@69:      * .       UErrorCode status = U_ZERO_ERROR;
jpayne@69:      * .       Collator *myCollation =
jpayne@69:      * .                         Collator::createInstance(Locale::getUS(), status);
jpayne@69:      * .       if (U_FAILURE(status)) return;
jpayne@69:      * .       myCollation->setStrength(Collator::PRIMARY);
jpayne@69:      * .       // result would be Collator::EQUAL ("abc" == "ABC")
jpayne@69:      * .       // (no primary difference between "abc" and "ABC")
jpayne@69:      * .       Collator::EComparisonResult result =
jpayne@69:      * .                             myCollation->compare(abc, 3, ABC, 3);
jpayne@69:      * .       myCollation->setStrength(Collator::TERTIARY);
jpayne@69:      * .       // result would be Collator::LESS ("abc" <<< "ABC")
jpayne@69:      * .       // (with tertiary difference between "abc" and "ABC")
jpayne@69:      * .       result = myCollation->compare(abc, 3, ABC, 3);
jpayne@69:      *
jpayne@69: * @param source the source string array to be compared with. jpayne@69: * @param sourceLength the length of the source string array. If this value jpayne@69: * is equal to -1, the string array is null-terminated. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param targetLength the length of the target string array. If this value jpayne@69: * is equal to -1, the string array is null-terminated. jpayne@69: * @return Returns a byte value. GREATER if source is greater than target; jpayne@69: * EQUAL if source is equal to target; LESS if source is less than jpayne@69: * target jpayne@69: * @deprecated ICU 2.6 use the overload with UErrorCode & jpayne@69: */ jpayne@69: virtual EComparisonResult compare(const char16_t* source, int32_t sourceLength, jpayne@69: const char16_t* target, int32_t targetLength) jpayne@69: const; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * The comparison function compares the character data stored in two jpayne@69: * different string arrays. Returns information about whether a string array jpayne@69: * is less than, greater than or equal to another string array. jpayne@69: * @param source the source string array to be compared with. jpayne@69: * @param sourceLength the length of the source string array. If this value jpayne@69: * is equal to -1, the string array is null-terminated. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param targetLength the length of the target string array. If this value jpayne@69: * is equal to -1, the string array is null-terminated. jpayne@69: * @param status possible error code jpayne@69: * @return Returns an enum value. UCOL_GREATER if source is greater jpayne@69: * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less jpayne@69: * than target jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual UCollationResult compare(const char16_t* source, int32_t sourceLength, jpayne@69: const char16_t* target, int32_t targetLength, jpayne@69: UErrorCode &status) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Compares two strings using the Collator. jpayne@69: * Returns whether the first one compares less than/equal to/greater than jpayne@69: * the second one. jpayne@69: * This version takes UCharIterator input. jpayne@69: * @param sIter the first ("source") string iterator jpayne@69: * @param tIter the second ("target") string iterator jpayne@69: * @param status ICU status jpayne@69: * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: virtual UCollationResult compare(UCharIterator &sIter, jpayne@69: UCharIterator &tIter, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Compares two UTF-8 strings using the Collator. jpayne@69: * Returns whether the first one compares less than/equal to/greater than jpayne@69: * the second one. jpayne@69: * This version takes UTF-8 input. jpayne@69: * Note that a StringPiece can be implicitly constructed jpayne@69: * from a std::string or a NUL-terminated const char * string. jpayne@69: * @param source the first UTF-8 string jpayne@69: * @param target the second UTF-8 string jpayne@69: * @param status ICU status jpayne@69: * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: virtual UCollationResult compareUTF8(const StringPiece &source, jpayne@69: const StringPiece &target, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Transforms the string into a series of characters that can be compared jpayne@69: * with CollationKey::compareTo. It is not possible to restore the original jpayne@69: * string from the chars in the sort key. jpayne@69: *

Use CollationKey::equals or CollationKey::compare to compare the jpayne@69: * generated sort keys. jpayne@69: * If the source string is null, a null collation key will be returned. jpayne@69: * jpayne@69: * Note that sort keys are often less efficient than simply doing comparison. jpayne@69: * For more details, see the ICU User Guide. jpayne@69: * jpayne@69: * @param source the source string to be transformed into a sort key. jpayne@69: * @param key the collation key to be filled in jpayne@69: * @param status the error code status. jpayne@69: * @return the collation key of the string based on the collation rules. jpayne@69: * @see CollationKey#compare jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual CollationKey& getCollationKey(const UnicodeString& source, jpayne@69: CollationKey& key, jpayne@69: UErrorCode& status) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Transforms the string into a series of characters that can be compared jpayne@69: * with CollationKey::compareTo. It is not possible to restore the original jpayne@69: * string from the chars in the sort key. jpayne@69: *

Use CollationKey::equals or CollationKey::compare to compare the jpayne@69: * generated sort keys. jpayne@69: *

If the source string is null, a null collation key will be returned. jpayne@69: * jpayne@69: * Note that sort keys are often less efficient than simply doing comparison. jpayne@69: * For more details, see the ICU User Guide. jpayne@69: * jpayne@69: * @param source the source string to be transformed into a sort key. jpayne@69: * @param sourceLength length of the collation key jpayne@69: * @param key the collation key to be filled in jpayne@69: * @param status the error code status. jpayne@69: * @return the collation key of the string based on the collation rules. jpayne@69: * @see CollationKey#compare jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual CollationKey& getCollationKey(const char16_t*source, jpayne@69: int32_t sourceLength, jpayne@69: CollationKey& key, jpayne@69: UErrorCode& status) const = 0; jpayne@69: /** jpayne@69: * Generates the hash code for the collation object jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual int32_t hashCode(void) const = 0; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Gets the locale of the Collator jpayne@69: * jpayne@69: * @param type can be either requested, valid or actual locale. For more jpayne@69: * information see the definition of ULocDataLocaleType in jpayne@69: * uloc.h jpayne@69: * @param status the error code status. jpayne@69: * @return locale where the collation data lives. If the collator jpayne@69: * was instantiated from rules, locale is empty. jpayne@69: * @deprecated ICU 2.8 This API is under consideration for revision jpayne@69: * in ICU 3.0. jpayne@69: */ jpayne@69: virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * Convenience method for comparing two strings based on the collation rules. jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the target string to be compared with. jpayne@69: * @return true if the first string is greater than the second one, jpayne@69: * according to the collation rules. false, otherwise. jpayne@69: * @see Collator#compare jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UBool greater(const UnicodeString& source, const UnicodeString& target) jpayne@69: const; jpayne@69: jpayne@69: /** jpayne@69: * Convenience method for comparing two strings based on the collation rules. jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the target string to be compared with. jpayne@69: * @return true if the first string is greater than or equal to the second jpayne@69: * one, according to the collation rules. false, otherwise. jpayne@69: * @see Collator#compare jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UBool greaterOrEqual(const UnicodeString& source, jpayne@69: const UnicodeString& target) const; jpayne@69: jpayne@69: /** jpayne@69: * Convenience method for comparing two strings based on the collation rules. jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the target string to be compared with. jpayne@69: * @return true if the strings are equal according to the collation rules. jpayne@69: * false, otherwise. jpayne@69: * @see Collator#compare jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UBool equals(const UnicodeString& source, const UnicodeString& target) const; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Determines the minimum strength that will be used in comparison or jpayne@69: * transformation. jpayne@69: *

E.g. with strength == SECONDARY, the tertiary difference is ignored jpayne@69: *

E.g. with strength == PRIMARY, the secondary and tertiary difference jpayne@69: * are ignored. jpayne@69: * @return the current comparison level. jpayne@69: * @see Collator#setStrength jpayne@69: * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead jpayne@69: */ jpayne@69: virtual ECollationStrength getStrength(void) const; jpayne@69: jpayne@69: /** jpayne@69: * Sets the minimum strength to be used in comparison or transformation. jpayne@69: *

Example of use: jpayne@69: * 

jpayne@69:      *  \code
jpayne@69:      *  UErrorCode status = U_ZERO_ERROR;
jpayne@69:      *  Collator*myCollation = Collator::createInstance(Locale::getUS(), status);
jpayne@69:      *  if (U_FAILURE(status)) return;
jpayne@69:      *  myCollation->setStrength(Collator::PRIMARY);
jpayne@69:      *  // result will be "abc" == "ABC"
jpayne@69:      *  // tertiary differences will be ignored
jpayne@69:      *  Collator::ComparisonResult result = myCollation->compare("abc", "ABC");
jpayne@69:      * \endcode
jpayne@69:      *
jpayne@69: * @see Collator#getStrength jpayne@69: * @param newStrength the new comparison level. jpayne@69: * @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead jpayne@69: */ jpayne@69: virtual void setStrength(ECollationStrength newStrength); jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * Retrieves the reordering codes for this collator. jpayne@69: * @param dest The array to fill with the script ordering. jpayne@69: * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function jpayne@69: * will only return the length of the result without writing any codes (pre-flighting). jpayne@69: * @param status A reference to an error code value, which must not indicate jpayne@69: * a failure before the function call. jpayne@69: * @return The length of the script ordering array. jpayne@69: * @see ucol_setReorderCodes jpayne@69: * @see Collator#getEquivalentReorderCodes jpayne@69: * @see Collator#setReorderCodes jpayne@69: * @see UScriptCode jpayne@69: * @see UColReorderCode jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: virtual int32_t getReorderCodes(int32_t *dest, jpayne@69: int32_t destCapacity, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Sets the ordering of scripts for this collator. jpayne@69: * jpayne@69: *

The reordering codes are a combination of script codes and reorder codes. jpayne@69: * @param reorderCodes An array of script codes in the new order. This can be NULL if the jpayne@69: * length is also set to 0. An empty array will clear any reordering codes on the collator. jpayne@69: * @param reorderCodesLength The length of reorderCodes. jpayne@69: * @param status error code jpayne@69: * @see ucol_setReorderCodes jpayne@69: * @see Collator#getReorderCodes jpayne@69: * @see Collator#getEquivalentReorderCodes jpayne@69: * @see UScriptCode jpayne@69: * @see UColReorderCode jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: virtual void setReorderCodes(const int32_t* reorderCodes, jpayne@69: int32_t reorderCodesLength, jpayne@69: UErrorCode& status) ; jpayne@69: jpayne@69: /** jpayne@69: * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder jpayne@69: * codes will be grouped and must reorder together. jpayne@69: * Beginning with ICU 55, scripts only reorder together if they are primary-equal, jpayne@69: * for example Hiragana and Katakana. jpayne@69: * jpayne@69: * @param reorderCode The reorder code to determine equivalence for. jpayne@69: * @param dest The array to fill with the script equivalence reordering codes. jpayne@69: * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the jpayne@69: * function will only return the length of the result without writing any codes (pre-flighting). jpayne@69: * @param status A reference to an error code value, which must not indicate jpayne@69: * a failure before the function call. jpayne@69: * @return The length of the of the reordering code equivalence array. jpayne@69: * @see ucol_setReorderCodes jpayne@69: * @see Collator#getReorderCodes jpayne@69: * @see Collator#setReorderCodes jpayne@69: * @see UScriptCode jpayne@69: * @see UColReorderCode jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode, jpayne@69: int32_t* dest, jpayne@69: int32_t destCapacity, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Get name of the object for the desired Locale, in the desired language jpayne@69: * @param objectLocale must be from getAvailableLocales jpayne@69: * @param displayLocale specifies the desired locale for output jpayne@69: * @param name the fill-in parameter of the return value jpayne@69: * @return display-able name of the object for the object locale in the jpayne@69: * desired language jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, jpayne@69: const Locale& displayLocale, jpayne@69: UnicodeString& name); jpayne@69: jpayne@69: /** jpayne@69: * Get name of the object for the desired Locale, in the language of the jpayne@69: * default locale. jpayne@69: * @param objectLocale must be from getAvailableLocales jpayne@69: * @param name the fill-in parameter of the return value jpayne@69: * @return name of the object for the desired locale in the default language jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, jpayne@69: UnicodeString& name); jpayne@69: jpayne@69: /** jpayne@69: * Get the set of Locales for which Collations are installed. jpayne@69: * jpayne@69: *

Note this does not include locales supported by registered collators. jpayne@69: * If collators might have been registered, use the overload of getAvailableLocales jpayne@69: * that returns a StringEnumeration.

jpayne@69: * jpayne@69: * @param count the output parameter of number of elements in the locale list jpayne@69: * @return the list of available locales for which collations are installed jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); jpayne@69: jpayne@69: /** jpayne@69: * Return a StringEnumeration over the locales available at the time of the call, jpayne@69: * including registered locales. If a severe error occurs (such as out of memory jpayne@69: * condition) this will return null. If there is no locale data, an empty enumeration jpayne@69: * will be returned. jpayne@69: * @return a StringEnumeration over the locales available at the time of the call jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: static StringEnumeration* U_EXPORT2 getAvailableLocales(void); jpayne@69: jpayne@69: /** jpayne@69: * Create a string enumerator of all possible keywords that are relevant to jpayne@69: * collation. At this point, the only recognized keyword for this jpayne@69: * service is "collation". jpayne@69: * @param status input-output error code jpayne@69: * @return a string enumeration over locale strings. The caller is jpayne@69: * responsible for closing the result. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Given a keyword, create a string enumeration of all values jpayne@69: * for that keyword that are currently in use. jpayne@69: * @param keyword a particular keyword as enumerated by jpayne@69: * ucol_getKeywords. If any other keyword is passed in, status is set jpayne@69: * to U_ILLEGAL_ARGUMENT_ERROR. jpayne@69: * @param status input-output error code jpayne@69: * @return a string enumeration over collation keyword values, or NULL jpayne@69: * upon error. The caller is responsible for deleting the result. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Given a key and a locale, returns an array of string values in a preferred jpayne@69: * order that would make a difference. These are all and only those values where jpayne@69: * the open (creation) of the service with the locale formed from the input locale jpayne@69: * plus input keyword and that value has different behavior than creation with the jpayne@69: * input locale alone. jpayne@69: * @param keyword one of the keys supported by this service. For now, only jpayne@69: * "collation" is supported. jpayne@69: * @param locale the locale jpayne@69: * @param commonlyUsed if set to true it will return only commonly used values jpayne@69: * with the given locale in preferred order. Otherwise, jpayne@69: * it will return all the available values for the locale. jpayne@69: * @param status ICU status jpayne@69: * @return a string enumeration over keyword values for the given key and the locale. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale, jpayne@69: UBool commonlyUsed, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Return the functionally equivalent locale for the given jpayne@69: * requested locale, with respect to given keyword, for the jpayne@69: * collation service. If two locales return the same result, then jpayne@69: * collators instantiated for these locales will behave jpayne@69: * equivalently. The converse is not always true; two collators jpayne@69: * may in fact be equivalent, but return different results, due to jpayne@69: * internal details. The return result has no other meaning than jpayne@69: * that stated above, and implies nothing as to the relationship jpayne@69: * between the two locales. This is intended for use by jpayne@69: * applications who wish to cache collators, or otherwise reuse jpayne@69: * collators when possible. The functional equivalent may change jpayne@69: * over time. For more information, please see the jpayne@69: * Locales and Services section of the ICU User Guide. jpayne@69: * @param keyword a particular keyword as enumerated by jpayne@69: * ucol_getKeywords. jpayne@69: * @param locale the requested locale jpayne@69: * @param isAvailable reference to a fillin parameter that jpayne@69: * indicates whether the requested locale was 'available' to the jpayne@69: * collation service. A locale is defined as 'available' if it jpayne@69: * physically exists within the collation locale data. jpayne@69: * @param status reference to input-output error code jpayne@69: * @return the functionally equivalent collation locale, or the root jpayne@69: * locale upon error. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale, jpayne@69: UBool& isAvailable, UErrorCode& status); jpayne@69: jpayne@69: #if !UCONFIG_NO_SERVICE jpayne@69: /** jpayne@69: * Register a new Collator. The collator will be adopted. jpayne@69: * Because ICU may choose to cache collators internally, this must be jpayne@69: * called at application startup, prior to any calls to jpayne@69: * Collator::createInstance to avoid undefined behavior. jpayne@69: * @param toAdopt the Collator instance to be adopted jpayne@69: * @param locale the locale with which the collator will be associated jpayne@69: * @param status the in/out status code, no special meanings are assigned jpayne@69: * @return a registry key that can be used to unregister this collator jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Register a new CollatorFactory. The factory will be adopted. jpayne@69: * Because ICU may choose to cache collators internally, this must be jpayne@69: * called at application startup, prior to any calls to jpayne@69: * Collator::createInstance to avoid undefined behavior. jpayne@69: * @param toAdopt the CollatorFactory instance to be adopted jpayne@69: * @param status the in/out status code, no special meanings are assigned jpayne@69: * @return a registry key that can be used to unregister this collator jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Unregister a previously-registered Collator or CollatorFactory jpayne@69: * using the key returned from the register call. Key becomes jpayne@69: * invalid after a successful call and should not be used again. jpayne@69: * The object corresponding to the key will be deleted. jpayne@69: * Because ICU may choose to cache collators internally, this should jpayne@69: * be called during application shutdown, after all calls to jpayne@69: * Collator::createInstance to avoid undefined behavior. jpayne@69: * @param key the registry key returned by a previous call to registerInstance jpayne@69: * @param status the in/out status code, no special meanings are assigned jpayne@69: * @return TRUE if the collator for the key was successfully unregistered jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status); jpayne@69: #endif /* UCONFIG_NO_SERVICE */ jpayne@69: jpayne@69: /** jpayne@69: * Gets the version information for a Collator. jpayne@69: * @param info the version # information, the result will be filled in jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void getVersion(UVersionInfo info) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. jpayne@69: * This method is to implement a simple version of RTTI, since not all C++ jpayne@69: * compilers support genuine RTTI. Polymorphic operator==() and clone() jpayne@69: * methods call this method. jpayne@69: * @return The class ID for this object. All objects of a given class have jpayne@69: * the same class ID. Objects of other classes have different class jpayne@69: * IDs. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual UClassID getDynamicClassID(void) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Universal attribute setter jpayne@69: * @param attr attribute type jpayne@69: * @param value attribute value jpayne@69: * @param status to indicate whether the operation went on smoothly or jpayne@69: * there were errors jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual void setAttribute(UColAttribute attr, UColAttributeValue value, jpayne@69: UErrorCode &status) = 0; jpayne@69: jpayne@69: /** jpayne@69: * Universal attribute getter jpayne@69: * @param attr attribute type jpayne@69: * @param status to indicate whether the operation went on smoothly or jpayne@69: * there were errors jpayne@69: * @return attribute value jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual UColAttributeValue getAttribute(UColAttribute attr, jpayne@69: UErrorCode &status) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Sets the variable top to the top of the specified reordering group. jpayne@69: * The variable top determines the highest-sorting character jpayne@69: * which is affected by UCOL_ALTERNATE_HANDLING. jpayne@69: * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect. jpayne@69: * jpayne@69: * The base class implementation sets U_UNSUPPORTED_ERROR. jpayne@69: * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, jpayne@69: * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; jpayne@69: * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return *this jpayne@69: * @see getMaxVariable jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. jpayne@69: * jpayne@69: * The base class implementation returns UCOL_REORDER_CODE_PUNCTUATION. jpayne@69: * @return the maximum variable reordering group. jpayne@69: * @see setMaxVariable jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: virtual UColReorderCode getMaxVariable() const; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Sets the variable top to the primary weight of the specified string. jpayne@69: * jpayne@69: * Beginning with ICU 53, the variable top is pinned to jpayne@69: * the top of one of the supported reordering groups, jpayne@69: * and it must not be beyond the last of those groups. jpayne@69: * See setMaxVariable(). jpayne@69: * @param varTop one or more (if contraction) char16_ts to which the variable top should be set jpayne@69: * @param len length of variable top string. If -1 it is considered to be zero terminated. jpayne@69: * @param status error code. If error code is set, the return value is undefined. Errors set by this function are:
jpayne@69: * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction
jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond jpayne@69: * the last reordering group supported by setMaxVariable() jpayne@69: * @return variable top primary weight jpayne@69: * @deprecated ICU 53 Call setMaxVariable() instead. jpayne@69: */ jpayne@69: virtual uint32_t setVariableTop(const char16_t *varTop, int32_t len, UErrorCode &status) = 0; jpayne@69: jpayne@69: /** jpayne@69: * Sets the variable top to the primary weight of the specified string. jpayne@69: * jpayne@69: * Beginning with ICU 53, the variable top is pinned to jpayne@69: * the top of one of the supported reordering groups, jpayne@69: * and it must not be beyond the last of those groups. jpayne@69: * See setMaxVariable(). jpayne@69: * @param varTop a UnicodeString size 1 or more (if contraction) of char16_ts to which the variable top should be set jpayne@69: * @param status error code. If error code is set, the return value is undefined. Errors set by this function are:
jpayne@69: * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction
jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond jpayne@69: * the last reordering group supported by setMaxVariable() jpayne@69: * @return variable top primary weight jpayne@69: * @deprecated ICU 53 Call setMaxVariable() instead. jpayne@69: */ jpayne@69: virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status) = 0; jpayne@69: jpayne@69: /** jpayne@69: * Sets the variable top to the specified primary weight. jpayne@69: * jpayne@69: * Beginning with ICU 53, the variable top is pinned to jpayne@69: * the top of one of the supported reordering groups, jpayne@69: * and it must not be beyond the last of those groups. jpayne@69: * See setMaxVariable(). jpayne@69: * @param varTop primary weight, as returned by setVariableTop or ucol_getVariableTop jpayne@69: * @param status error code jpayne@69: * @deprecated ICU 53 Call setMaxVariable() instead. jpayne@69: */ jpayne@69: virtual void setVariableTop(uint32_t varTop, UErrorCode &status) = 0; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * Gets the variable top value of a Collator. jpayne@69: * @param status error code (not changed by function). If error code is set, the return value is undefined. jpayne@69: * @return the variable top primary weight jpayne@69: * @see getMaxVariable jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual uint32_t getVariableTop(UErrorCode &status) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Get a UnicodeSet that contains all the characters and sequences jpayne@69: * tailored in this collator. jpayne@69: * @param status error code of the operation jpayne@69: * @return a pointer to a UnicodeSet object containing all the jpayne@69: * code points and sequences that may sort differently than jpayne@69: * in the root collator. The object must be disposed of by using delete jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual UnicodeSet *getTailoredSet(UErrorCode &status) const; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Same as clone(). jpayne@69: * The base class implementation simply calls clone(). jpayne@69: * @return a copy of this object, owned by the caller jpayne@69: * @see clone() jpayne@69: * @deprecated ICU 50 no need to have two methods for cloning jpayne@69: */ jpayne@69: virtual Collator* safeClone() const; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * Get the sort key as an array of bytes from a UnicodeString. jpayne@69: * Sort key byte arrays are zero-terminated and can be compared using jpayne@69: * strcmp(). jpayne@69: * jpayne@69: * Note that sort keys are often less efficient than simply doing comparison. jpayne@69: * For more details, see the ICU User Guide. jpayne@69: * jpayne@69: * @param source string to be processed. jpayne@69: * @param result buffer to store result in. If NULL, number of bytes needed jpayne@69: * will be returned. jpayne@69: * @param resultLength length of the result buffer. If if not enough the jpayne@69: * buffer will be filled to capacity. jpayne@69: * @return Number of bytes needed for storing the sort key jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual int32_t getSortKey(const UnicodeString& source, jpayne@69: uint8_t* result, jpayne@69: int32_t resultLength) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Get the sort key as an array of bytes from a char16_t buffer. jpayne@69: * Sort key byte arrays are zero-terminated and can be compared using jpayne@69: * strcmp(). jpayne@69: * jpayne@69: * Note that sort keys are often less efficient than simply doing comparison. jpayne@69: * For more details, see the ICU User Guide. jpayne@69: * jpayne@69: * @param source string to be processed. jpayne@69: * @param sourceLength length of string to be processed. jpayne@69: * If -1, the string is 0 terminated and length will be decided by the jpayne@69: * function. jpayne@69: * @param result buffer to store result in. If NULL, number of bytes needed jpayne@69: * will be returned. jpayne@69: * @param resultLength length of the result buffer. If if not enough the jpayne@69: * buffer will be filled to capacity. jpayne@69: * @return Number of bytes needed for storing the sort key jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual int32_t getSortKey(const char16_t*source, int32_t sourceLength, jpayne@69: uint8_t*result, int32_t resultLength) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Produce a bound for a given sortkey and a number of levels. jpayne@69: * Return value is always the number of bytes needed, regardless of jpayne@69: * whether the result buffer was big enough or even valid.
jpayne@69: * Resulting bounds can be used to produce a range of strings that are jpayne@69: * between upper and lower bounds. For example, if bounds are produced jpayne@69: * for a sortkey of string "smith", strings between upper and lower jpayne@69: * bounds with one level would include "Smith", "SMITH", "sMiTh".
jpayne@69: * There are two upper bounds that can be produced. If UCOL_BOUND_UPPER jpayne@69: * is produced, strings matched would be as above. However, if bound jpayne@69: * produced using UCOL_BOUND_UPPER_LONG is used, the above example will jpayne@69: * also match "Smithsonian" and similar.
jpayne@69: * For more on usage, see example in cintltst/capitst.c in procedure jpayne@69: * TestBounds. jpayne@69: * Sort keys may be compared using strcmp. jpayne@69: * @param source The source sortkey. jpayne@69: * @param sourceLength The length of source, or -1 if null-terminated. jpayne@69: * (If an unmodified sortkey is passed, it is always null jpayne@69: * terminated). jpayne@69: * @param boundType Type of bound required. It can be UCOL_BOUND_LOWER, which jpayne@69: * produces a lower inclusive bound, UCOL_BOUND_UPPER, that jpayne@69: * produces upper bound that matches strings of the same length jpayne@69: * or UCOL_BOUND_UPPER_LONG that matches strings that have the jpayne@69: * same starting substring as the source string. jpayne@69: * @param noOfLevels Number of levels required in the resulting bound (for most jpayne@69: * uses, the recommended value is 1). See users guide for jpayne@69: * explanation on number of levels a sortkey can have. jpayne@69: * @param result A pointer to a buffer to receive the resulting sortkey. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status Used for returning error code if something went wrong. If the jpayne@69: * number of levels requested is higher than the number of levels jpayne@69: * in the source key, a warning (U_SORT_KEY_TOO_SHORT_WARNING) is jpayne@69: * issued. jpayne@69: * @return The size needed to fully store the bound. jpayne@69: * @see ucol_keyHashCode jpayne@69: * @stable ICU 2.1 jpayne@69: */ jpayne@69: static int32_t U_EXPORT2 getBound(const uint8_t *source, jpayne@69: int32_t sourceLength, jpayne@69: UColBoundMode boundType, jpayne@69: uint32_t noOfLevels, jpayne@69: uint8_t *result, jpayne@69: int32_t resultLength, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: jpayne@69: protected: jpayne@69: jpayne@69: // Collator protected constructors ------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Default constructor. jpayne@69: * Constructor is different from the old default Collator constructor. jpayne@69: * The task for determing the default collation strength and normalization jpayne@69: * mode is left to the child class. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: Collator(); jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Constructor. jpayne@69: * Empty constructor, does not handle the arguments. jpayne@69: * This constructor is done for backward compatibility with 1.7 and 1.8. jpayne@69: * The task for handling the argument collation strength and normalization jpayne@69: * mode is left to the child class. jpayne@69: * @param collationStrength collation strength jpayne@69: * @param decompositionMode jpayne@69: * @deprecated ICU 2.4. Subclasses should use the default constructor jpayne@69: * instead and handle the strength and normalization mode themselves. jpayne@69: */ jpayne@69: Collator(UCollationStrength collationStrength, jpayne@69: UNormalizationMode decompositionMode); jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: /** jpayne@69: * Copy constructor. jpayne@69: * @param other Collator object to be copied from jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: Collator(const Collator& other); jpayne@69: jpayne@69: public: jpayne@69: /** jpayne@69: * Used internally by registration to define the requested and valid locales. jpayne@69: * @param requestedLocale the requested locale jpayne@69: * @param validLocale the valid locale jpayne@69: * @param actualLocale the actual locale jpayne@69: * @internal jpayne@69: */ jpayne@69: virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale); jpayne@69: jpayne@69: /** Get the short definition string for a collator. This internal API harvests the collator's jpayne@69: * locale and the attribute set and produces a string that can be used for opening jpayne@69: * a collator with the same attributes using the ucol_openFromShortString API. jpayne@69: * This string will be normalized. jpayne@69: * The structure and the syntax of the string is defined in the "Naming collators" jpayne@69: * section of the users guide: jpayne@69: * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme jpayne@69: * This function supports preflighting. jpayne@69: * jpayne@69: * This is internal, and intended to be used with delegate converters. jpayne@69: * jpayne@69: * @param locale a locale that will appear as a collators locale in the resulting jpayne@69: * short string definition. If NULL, the locale will be harvested jpayne@69: * from the collator. jpayne@69: * @param buffer space to hold the resulting string jpayne@69: * @param capacity capacity of the buffer jpayne@69: * @param status for returning errors. All the preflighting errors are featured jpayne@69: * @return length of the resulting string jpayne@69: * @see ucol_openFromShortString jpayne@69: * @see ucol_normalizeShortDefinitionString jpayne@69: * @see ucol_getShortDefinitionString jpayne@69: * @internal jpayne@69: */ jpayne@69: virtual int32_t internalGetShortDefinitionString(const char *locale, jpayne@69: char *buffer, jpayne@69: int32_t capacity, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Implements ucol_strcollUTF8(). jpayne@69: * @internal jpayne@69: */ jpayne@69: virtual UCollationResult internalCompareUTF8( jpayne@69: const char *left, int32_t leftLength, jpayne@69: const char *right, int32_t rightLength, jpayne@69: UErrorCode &errorCode) const; jpayne@69: jpayne@69: /** jpayne@69: * Implements ucol_nextSortKeyPart(). jpayne@69: * @internal jpayne@69: */ jpayne@69: virtual int32_t jpayne@69: internalNextSortKeyPart( jpayne@69: UCharIterator *iter, uint32_t state[2], jpayne@69: uint8_t *dest, int32_t count, UErrorCode &errorCode) const; jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** @internal */ jpayne@69: static inline Collator *fromUCollator(UCollator *uc) { jpayne@69: return reinterpret_cast(uc); jpayne@69: } jpayne@69: /** @internal */ jpayne@69: static inline const Collator *fromUCollator(const UCollator *uc) { jpayne@69: return reinterpret_cast(uc); jpayne@69: } jpayne@69: /** @internal */ jpayne@69: inline UCollator *toUCollator() { jpayne@69: return reinterpret_cast(this); jpayne@69: } jpayne@69: /** @internal */ jpayne@69: inline const UCollator *toUCollator() const { jpayne@69: return reinterpret_cast(this); jpayne@69: } jpayne@69: #endif // U_HIDE_INTERNAL_API jpayne@69: jpayne@69: private: jpayne@69: /** jpayne@69: * Assignment operator. Private for now. jpayne@69: */ jpayne@69: Collator& operator=(const Collator& other); jpayne@69: jpayne@69: friend class CFactory; jpayne@69: friend class SimpleCFactory; jpayne@69: friend class ICUCollatorFactory; jpayne@69: friend class ICUCollatorService; jpayne@69: static Collator* makeInstance(const Locale& desiredLocale, jpayne@69: UErrorCode& status); jpayne@69: }; jpayne@69: jpayne@69: #if !UCONFIG_NO_SERVICE jpayne@69: /** jpayne@69: * A factory, used with registerFactory, the creates multiple collators and provides jpayne@69: * display names for them. A factory supports some number of locales-- these are the jpayne@69: * locales for which it can create collators. The factory can be visible, in which jpayne@69: * case the supported locales will be enumerated by getAvailableLocales, or invisible, jpayne@69: * in which they are not. Invisible locales are still supported, they are just not jpayne@69: * listed by getAvailableLocales. jpayne@69: *

jpayne@69: * If standard locale display names are sufficient, Collator instances can jpayne@69: * be registered using registerInstance instead.

jpayne@69: *

jpayne@69: * Note: if the collators are to be used from C APIs, they must be instances jpayne@69: * of RuleBasedCollator.

jpayne@69: * jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: class U_I18N_API CollatorFactory : public UObject { jpayne@69: public: jpayne@69: jpayne@69: /** jpayne@69: * Destructor jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: virtual ~CollatorFactory(); jpayne@69: jpayne@69: /** jpayne@69: * Return true if this factory is visible. Default is true. jpayne@69: * If not visible, the locales supported by this factory will not jpayne@69: * be listed by getAvailableLocales. jpayne@69: * @return true if the factory is visible. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual UBool visible(void) const; jpayne@69: jpayne@69: /** jpayne@69: * Return a collator for the provided locale. If the locale jpayne@69: * is not supported, return NULL. jpayne@69: * @param loc the locale identifying the collator to be created. jpayne@69: * @return a new collator if the locale is supported, otherwise NULL. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual Collator* createCollator(const Locale& loc) = 0; jpayne@69: jpayne@69: /** jpayne@69: * Return the name of the collator for the objectLocale, localized for the displayLocale. jpayne@69: * If objectLocale is not supported, or the factory is not visible, set the result string jpayne@69: * to bogus. jpayne@69: * @param objectLocale the locale identifying the collator jpayne@69: * @param displayLocale the locale for which the display name of the collator should be localized jpayne@69: * @param result an output parameter for the display name, set to bogus if not supported. jpayne@69: * @return the display name jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual UnicodeString& getDisplayName(const Locale& objectLocale, jpayne@69: const Locale& displayLocale, jpayne@69: UnicodeString& result); jpayne@69: jpayne@69: /** jpayne@69: * Return an array of all the locale names directly supported by this factory. jpayne@69: * The number of names is returned in count. This array is owned by the factory. jpayne@69: * Its contents must never change. jpayne@69: * @param count output parameter for the number of locales supported by the factory jpayne@69: * @param status the in/out error code jpayne@69: * @return a pointer to an array of count UnicodeStrings. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0; jpayne@69: }; jpayne@69: #endif /* UCONFIG_NO_SERVICE */ jpayne@69: jpayne@69: // Collator inline methods ----------------------------------------------- jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_COLLATION */ jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif