Home | History | Annotate | Download | only in unicode
      1 /*
      2 ******************************************************************************
      3 *   Copyright (C) 1996-2011, International Business Machines                 *
      4 *   Corporation and others.  All Rights Reserved.                            *
      5 ******************************************************************************
      6 */
      7 
      8 /**
      9  * \file
     10  * \brief C++ API: Collation Service.
     11  */
     12 
     13 /**
     14 * File coll.h
     15 *
     16 * Created by: Helena Shih
     17 *
     18 * Modification History:
     19 *
     20 *  Date        Name        Description
     21 * 02/5/97      aliu        Modified createDefault to load collation data from
     22 *                          binary files when possible.  Added related methods
     23 *                          createCollationFromFile, chopLocale, createPathName.
     24 * 02/11/97     aliu        Added members addToCache, findInCache, and fgCache.
     25 * 02/12/97     aliu        Modified to create objects from RuleBasedCollator cache.
     26 *                          Moved cache out of Collation class.
     27 * 02/13/97     aliu        Moved several methods out of this class and into
     28 *                          RuleBasedCollator, with modifications.  Modified
     29 *                          createDefault() to call new RuleBasedCollator(Locale&)
     30 *                          constructor.  General clean up and documentation.
     31 * 02/20/97     helena      Added clone, operator==, operator!=, operator=, copy
     32 *                          constructor and getDynamicClassID.
     33 * 03/25/97     helena      Updated with platform independent data types.
     34 * 05/06/97     helena      Added memory allocation error detection.
     35 * 06/20/97     helena      Java class name change.
     36 * 09/03/97     helena      Added createCollationKeyValues().
     37 * 02/10/98     damiba      Added compare() with length as parameter.
     38 * 04/23/99     stephen     Removed EDecompositionMode, merged with
     39 *                          Normalizer::EMode.
     40 * 11/02/99     helena      Collator performance enhancements.  Eliminates the
     41 *                          UnicodeString construction and special case for NO_OP.
     42 * 11/23/99     srl         More performance enhancements. Inlining of
     43 *                          critical accessors.
     44 * 05/15/00     helena      Added version information API.
     45 * 01/29/01     synwee      Modified into a C++ wrapper which calls C apis
     46 *                          (ucoll.h).
     47 */
     48 
     49 #ifndef COLL_H
     50 #define COLL_H
     51 
     52 #include "unicode/utypes.h"
     53 
     54 #if !UCONFIG_NO_COLLATION
     55 
     56 #include "unicode/uobject.h"
     57 #include "unicode/ucol.h"
     58 #include "unicode/normlzr.h"
     59 #include "unicode/locid.h"
     60 #include "unicode/uniset.h"
     61 #include "unicode/umisc.h"
     62 #include "unicode/uiter.h"
     63 #include "unicode/stringpiece.h"
     64 
     65 U_NAMESPACE_BEGIN
     66 
     67 class StringEnumeration;
     68 
     69 #if !UCONFIG_NO_SERVICE
     70 /**
     71  * @stable ICU 2.6
     72  */
     73 class CollatorFactory;
     74 #endif
     75 
     76 /**
     77 * @stable ICU 2.0
     78 */
     79 class CollationKey;
     80 
     81 /**
     82 * The <code>Collator</code> class performs locale-sensitive string
     83 * comparison.<br>
     84 * You use this class to build searching and sorting routines for natural
     85 * language text.<br>
     86 * <em>Important: </em>The ICU collation service has been reimplemented
     87 * in order to achieve better performance and UCA compliance.
     88 * For details, see the
     89 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collation/ICU_collation_design.htm">
     90 * collation design document</a>.
     91 * <p>
     92 * <code>Collator</code> is an abstract base class. Subclasses implement
     93 * specific collation strategies. One subclass,
     94 * <code>RuleBasedCollator</code>, is currently provided and is applicable
     95 * to a wide set of languages. Other subclasses may be created to handle more
     96 * specialized needs.
     97 * <p>
     98 * Like other locale-sensitive classes, you can use the static factory method,
     99 * <code>createInstance</code>, to obtain the appropriate
    100 * <code>Collator</code> object for a given locale. You will only need to
    101 * look at the subclasses of <code>Collator</code> if you need to
    102 * understand the details of a particular collation strategy or if you need to
    103 * modify that strategy.
    104 * <p>
    105 * The following example shows how to compare two strings using the
    106 * <code>Collator</code> for the default locale.
    107 * \htmlonly<blockquote>\endhtmlonly
    108 * <pre>
    109 * \code
    110 * // Compare two strings in the default locale
    111 * UErrorCode success = U_ZERO_ERROR;
    112 * Collator* myCollator = Collator::createInstance(success);
    113 * if (myCollator->compare("abc", "ABC") < 0)
    114 *   cout << "abc is less than ABC" << endl;
    115 * else
    116 *   cout << "abc is greater than or equal to ABC" << endl;
    117 * \endcode
    118 * </pre>
    119 * \htmlonly</blockquote>\endhtmlonly
    120 * <p>
    121 * You can set a <code>Collator</code>'s <em>strength</em> property to
    122 * determine the level of difference considered significant in comparisons.
    123 * Five strengths are provided: <code>PRIMARY</code>, <code>SECONDARY</code>,
    124 * <code>TERTIARY</code>, <code>QUATERNARY</code> and <code>IDENTICAL</code>.
    125 * The exact assignment of strengths to language features is locale dependant.
    126 * For example, in Czech, "e" and "f" are considered primary differences,
    127 * while "e" and "\u00EA" are secondary differences, "e" and "E" are tertiary
    128 * differences and "e" and "e" are identical. The following shows how both case
    129 * and accents could be ignored for US English.
    130 * \htmlonly<blockquote>\endhtmlonly
    131 * <pre>
    132 * \code
    133 * //Get the Collator for US English and set its strength to PRIMARY
    134 * UErrorCode success = U_ZERO_ERROR;
    135 * Collator* usCollator = Collator::createInstance(Locale::US, success);
    136 * usCollator->setStrength(Collator::PRIMARY);
    137 * if (usCollator->compare("abc", "ABC") == 0)
    138 *     cout << "'abc' and 'ABC' strings are equivalent with strength PRIMARY" << endl;
    139 * \endcode
    140 * </pre>
    141 * \htmlonly</blockquote>\endhtmlonly
    142 * <p>
    143 * For comparing strings exactly once, the <code>compare</code> method
    144 * provides the best performance. When sorting a list of strings however, it
    145 * is generally necessary to compare each string multiple times. In this case,
    146 * sort keys provide better performance. The <code>getSortKey</code> methods
    147 * convert a string to a series of bytes that can be compared bitwise against
    148 * other sort keys using <code>strcmp()</code>. Sort keys are written as
    149 * zero-terminated byte strings. They consist of several substrings, one for
    150 * each collation strength level, that are delimited by 0x01 bytes.
    151 * If the string code points are appended for UCOL_IDENTICAL, then they are
    152 * processed for correct code point order comparison and may contain 0x01
    153 * bytes but not zero bytes.
    154 * </p>
    155 * <p>
    156 * An older set of APIs returns a <code>CollationKey</code> object that wraps
    157 * the sort key bytes instead of returning the bytes themselves.
    158 * Its use is deprecated, but it is still available for compatibility with
    159 * Java.
    160 * </p>
    161 * <p>
    162 * <strong>Note:</strong> <code>Collator</code>s with different Locale,
    163 * and CollationStrength settings will return different sort
    164 * orders for the same set of strings. Locales have specific collation rules,
    165 * and the way in which secondary and tertiary differences are taken into
    166 * account, for example, will result in a different sorting order for same
    167 * strings.
    168 * </p>
    169 * @see         RuleBasedCollator
    170 * @see         CollationKey
    171 * @see         CollationElementIterator
    172 * @see         Locale
    173 * @see         Normalizer
    174 * @version     2.0 11/15/01
    175 */
    176 
    177 class U_I18N_API Collator : public UObject {
    178 public:
    179 
    180     // Collator public enums -----------------------------------------------
    181 
    182     /**
    183      * Base letter represents a primary difference. Set comparison level to
    184      * PRIMARY to ignore secondary and tertiary differences.<br>
    185      * Use this to set the strength of a Collator object.<br>
    186      * Example of primary difference, "abc" &lt; "abd"
    187      *
    188      * Diacritical differences on the same base letter represent a secondary
    189      * difference. Set comparison level to SECONDARY to ignore tertiary
    190      * differences. Use this to set the strength of a Collator object.<br>
    191      * Example of secondary difference, "&auml;" >> "a".
    192      *
    193      * Uppercase and lowercase versions of the same character represents a
    194      * tertiary difference.  Set comparison level to TERTIARY to include all
    195      * comparison differences. Use this to set the strength of a Collator
    196      * object.<br>
    197      * Example of tertiary difference, "abc" &lt;&lt;&lt; "ABC".
    198      *
    199      * Two characters are considered "identical" when they have the same unicode
    200      * spellings.<br>
    201      * For example, "&auml;" == "&auml;".
    202      *
    203      * UCollationStrength is also used to determine the strength of sort keys
    204      * generated from Collator objects.
    205      * @stable ICU 2.0
    206      */
    207     enum ECollationStrength
    208     {
    209         PRIMARY    = 0,
    210         SECONDARY  = 1,
    211         TERTIARY   = 2,
    212         QUATERNARY = 3,
    213         IDENTICAL  = 15
    214     };
    215 
    216     /**
    217      * LESS is returned if source string is compared to be less than target
    218      * string in the compare() method.
    219      * EQUAL is returned if source string is compared to be equal to target
    220      * string in the compare() method.
    221      * GREATER is returned if source string is compared to be greater than
    222      * target string in the compare() method.
    223      * @see Collator#compare
    224      * @deprecated ICU 2.6. Use C enum UCollationResult defined in ucol.h
    225      */
    226     enum EComparisonResult
    227     {
    228         LESS = -1,
    229         EQUAL = 0,
    230         GREATER = 1
    231     };
    232 
    233     // Collator public destructor -----------------------------------------
    234 
    235     /**
    236      * Destructor
    237      * @stable ICU 2.0
    238      */
    239     virtual ~Collator();
    240 
    241     // Collator public methods --------------------------------------------
    242 
    243     /**
    244      * Returns true if "other" is the same as "this"
    245      * @param other Collator object to be compared
    246      * @return true if other is the same as this.
    247      * @stable ICU 2.0
    248      */
    249     virtual UBool operator==(const Collator& other) const;
    250 
    251     /**
    252      * Returns true if "other" is not the same as "this".
    253      * @param other Collator object to be compared
    254      * @return true if other is not the same as this.
    255      * @stable ICU 2.0
    256      */
    257     virtual UBool operator!=(const Collator& other) const;
    258 
    259     /**
    260      * Makes a shallow copy of the current object.
    261      * @return a copy of this object
    262      * @stable ICU 2.0
    263      */
    264     virtual Collator* clone(void) const = 0;
    265 
    266     /**
    267      * Creates the Collator object for the current default locale.
    268      * The default locale is determined by Locale::getDefault.
    269      * The UErrorCode& err parameter is used to return status information to the user.
    270      * To check whether the construction succeeded or not, you should check the
    271      * value of U_SUCCESS(err).  If you wish more detailed information, you can
    272      * check for informational error results which still indicate success.
    273      * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For
    274      * example, 'de_CH' was requested, but nothing was found there, so 'de' was
    275      * used. U_USING_DEFAULT_ERROR indicates that the default locale data was
    276      * used; neither the requested locale nor any of its fall back locales
    277      * could be found.
    278      * The caller owns the returned object and is responsible for deleting it.
    279      *
    280      * @param err    the error code status.
    281      * @return       the collation object of the default locale.(for example, en_US)
    282      * @see Locale#getDefault
    283      * @stable ICU 2.0
    284      */
    285     static Collator* U_EXPORT2 createInstance(UErrorCode&  err);
    286 
    287     /**
    288      * Gets the table-based collation object for the desired locale. The
    289      * resource of the desired locale will be loaded by ResourceLoader.
    290      * Locale::ENGLISH is the base collation table and all other languages are
    291      * built on top of it with additional language-specific modifications.
    292      * The UErrorCode& err parameter is used to return status information to the user.
    293      * To check whether the construction succeeded or not, you should check
    294      * the value of U_SUCCESS(err).  If you wish more detailed information, you
    295      * can check for informational error results which still indicate success.
    296      * U_USING_FALLBACK_ERROR indicates that a fall back locale was used.  For
    297      * example, 'de_CH' was requested, but nothing was found there, so 'de' was
    298      * used.  U_USING_DEFAULT_ERROR indicates that the default locale data was
    299      * used; neither the requested locale nor any of its fall back locales
    300      * could be found.
    301      * The caller owns the returned object and is responsible for deleting it.
    302      * @param loc    The locale ID for which to open a collator.
    303      * @param err    the error code status.
    304      * @return       the created table-based collation object based on the desired
    305      *               locale.
    306      * @see Locale
    307      * @see ResourceLoader
    308      * @stable ICU 2.2
    309      */
    310     static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err);
    311 
    312 #ifdef U_USE_COLLATION_OBSOLETE_2_6
    313     /**
    314      * Create a Collator with a specific version.
    315      * This is the same as createInstance(loc, err) except that getVersion() of
    316      * the returned object is guaranteed to be the same as the version
    317      * parameter.
    318      * This is designed to be used to open the same collator for a given
    319      * locale even when ICU is updated.
    320      * The same locale and version guarantees the same sort keys and
    321      * comparison results.
    322      * <p>
    323      * Note: this API will be removed in a future release.  Use
    324      * <tt>createInstance(const Locale&, UErrorCode&) instead.</tt></p>
    325      *
    326      * @param loc The locale ID for which to open a collator.
    327      * @param version The requested collator version.
    328      * @param err A reference to a UErrorCode,
    329      *            must not indicate a failure before calling this function.
    330      * @return A pointer to a Collator, or 0 if an error occurred
    331      *         or a collator with the requested version is not available.
    332      *
    333      * @see getVersion
    334      * @obsolete ICU 2.6
    335      */
    336     static Collator *createInstance(const Locale &loc, UVersionInfo version, UErrorCode &err);
    337 #endif
    338 
    339     /**
    340      * The comparison function compares the character data stored in two
    341      * different strings. Returns information about whether a string is less
    342      * than, greater than or equal to another string.
    343      * @param source the source string to be compared with.
    344      * @param target the string that is to be compared with the source string.
    345      * @return Returns a byte value. GREATER if source is greater
    346      * than target; EQUAL if source is equal to target; LESS if source is less
    347      * than target
    348      * @deprecated ICU 2.6 use the overload with UErrorCode &
    349      */
    350     virtual EComparisonResult compare(const UnicodeString& source,
    351                                       const UnicodeString& target) const;
    352 
    353     /**
    354      * The comparison function compares the character data stored in two
    355      * different strings. Returns information about whether a string is less
    356      * than, greater than or equal to another string.
    357      * @param source the source string to be compared with.
    358      * @param target the string that is to be compared with the source string.
    359      * @param status possible error code
    360      * @return Returns an enum value. UCOL_GREATER if source is greater
    361      * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less
    362      * than target
    363      * @stable ICU 2.6
    364      */
    365     virtual UCollationResult compare(const UnicodeString& source,
    366                                       const UnicodeString& target,
    367                                       UErrorCode &status) const = 0;
    368 
    369     /**
    370      * Does the same thing as compare but limits the comparison to a specified
    371      * length
    372      * @param source the source string to be compared with.
    373      * @param target the string that is to be compared with the source string.
    374      * @param length the length the comparison is limited to
    375      * @return Returns a byte value. GREATER if source (up to the specified
    376      *         length) is greater than target; EQUAL if source (up to specified
    377      *         length) is equal to target; LESS if source (up to the specified
    378      *         length) is less  than target.
    379      * @deprecated ICU 2.6 use the overload with UErrorCode &
    380      */
    381     virtual EComparisonResult compare(const UnicodeString& source,
    382                                       const UnicodeString& target,
    383                                       int32_t length) const;
    384 
    385     /**
    386      * Does the same thing as compare but limits the comparison to a specified
    387      * length
    388      * @param source the source string to be compared with.
    389      * @param target the string that is to be compared with the source string.
    390      * @param length the length the comparison is limited to
    391      * @param status possible error code
    392      * @return Returns an enum value. UCOL_GREATER if source (up to the specified
    393      *         length) is greater than target; UCOL_EQUAL if source (up to specified
    394      *         length) is equal to target; UCOL_LESS if source (up to the specified
    395      *         length) is less  than target.
    396      * @stable ICU 2.6
    397      */
    398     virtual UCollationResult compare(const UnicodeString& source,
    399                                       const UnicodeString& target,
    400                                       int32_t length,
    401                                       UErrorCode &status) const = 0;
    402 
    403     /**
    404      * The comparison function compares the character data stored in two
    405      * different string arrays. Returns information about whether a string array
    406      * is less than, greater than or equal to another string array.
    407      * @param source the source string array to be compared with.
    408      * @param sourceLength the length of the source string array.  If this value
    409      *        is equal to -1, the string array is null-terminated.
    410      * @param target the string that is to be compared with the source string.
    411      * @param targetLength the length of the target string array.  If this value
    412      *        is equal to -1, the string array is null-terminated.
    413      * @return Returns a byte value. GREATER if source is greater than target;
    414      *         EQUAL if source is equal to target; LESS if source is less than
    415      *         target
    416      * @deprecated ICU 2.6 use the overload with UErrorCode &
    417      */
    418     virtual EComparisonResult compare(const UChar* source, int32_t sourceLength,
    419                                       const UChar* target, int32_t targetLength)
    420                                       const;
    421 
    422     /**
    423      * The comparison function compares the character data stored in two
    424      * different string arrays. Returns information about whether a string array
    425      * is less than, greater than or equal to another string array.
    426      * @param source the source string array to be compared with.
    427      * @param sourceLength the length of the source string array.  If this value
    428      *        is equal to -1, the string array is null-terminated.
    429      * @param target the string that is to be compared with the source string.
    430      * @param targetLength the length of the target string array.  If this value
    431      *        is equal to -1, the string array is null-terminated.
    432      * @param status possible error code
    433      * @return Returns an enum value. UCOL_GREATER if source is greater
    434      * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less
    435      * than target
    436      * @stable ICU 2.6
    437      */
    438     virtual UCollationResult compare(const UChar* source, int32_t sourceLength,
    439                                       const UChar* target, int32_t targetLength,
    440                                       UErrorCode &status) const = 0;
    441 
    442     /**
    443      * Compares two strings using the Collator.
    444      * Returns whether the first one compares less than/equal to/greater than
    445      * the second one.
    446      * This version takes UCharIterator input.
    447      * @param sIter the first ("source") string iterator
    448      * @param tIter the second ("target") string iterator
    449      * @param status ICU status
    450      * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
    451      * @stable ICU 4.2
    452      */
    453     virtual UCollationResult compare(UCharIterator &sIter,
    454                                      UCharIterator &tIter,
    455                                      UErrorCode &status) const;
    456 
    457     /**
    458      * Compares two UTF-8 strings using the Collator.
    459      * Returns whether the first one compares less than/equal to/greater than
    460      * the second one.
    461      * This version takes UTF-8 input.
    462      * Note that a StringPiece can be implicitly constructed
    463      * from a std::string or a NUL-terminated const char * string.
    464      * @param source the first UTF-8 string
    465      * @param target the second UTF-8 string
    466      * @param status ICU status
    467      * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
    468      * @stable ICU 4.2
    469      */
    470     virtual UCollationResult compareUTF8(const StringPiece &source,
    471                                          const StringPiece &target,
    472                                          UErrorCode &status) const;
    473 
    474     /**
    475      * Transforms the string into a series of characters that can be compared
    476      * with CollationKey::compareTo. It is not possible to restore the original
    477      * string from the chars in the sort key.  The generated sort key handles
    478      * only a limited number of ignorable characters.
    479      * <p>Use CollationKey::equals or CollationKey::compare to compare the
    480      * generated sort keys.
    481      * If the source string is null, a null collation key will be returned.
    482      * @param source the source string to be transformed into a sort key.
    483      * @param key the collation key to be filled in
    484      * @param status the error code status.
    485      * @return the collation key of the string based on the collation rules.
    486      * @see CollationKey#compare
    487      * @deprecated ICU 2.8 Use getSortKey(...) instead
    488      */
    489     virtual CollationKey& getCollationKey(const UnicodeString&  source,
    490                                           CollationKey& key,
    491                                           UErrorCode& status) const = 0;
    492 
    493     /**
    494      * Transforms the string into a series of characters that can be compared
    495      * with CollationKey::compareTo. It is not possible to restore the original
    496      * string from the chars in the sort key.  The generated sort key handles
    497      * only a limited number of ignorable characters.
    498      * <p>Use CollationKey::equals or CollationKey::compare to compare the
    499      * generated sort keys.
    500      * <p>If the source string is null, a null collation key will be returned.
    501      * @param source the source string to be transformed into a sort key.
    502      * @param sourceLength length of the collation key
    503      * @param key the collation key to be filled in
    504      * @param status the error code status.
    505      * @return the collation key of the string based on the collation rules.
    506      * @see CollationKey#compare
    507      * @deprecated ICU 2.8 Use getSortKey(...) instead
    508      */
    509     virtual CollationKey& getCollationKey(const UChar*source,
    510                                           int32_t sourceLength,
    511                                           CollationKey& key,
    512                                           UErrorCode& status) const = 0;
    513     /**
    514      * Generates the hash code for the collation object
    515      * @stable ICU 2.0
    516      */
    517     virtual int32_t hashCode(void) const = 0;
    518 
    519     /**
    520      * Gets the locale of the Collator
    521      *
    522      * @param type can be either requested, valid or actual locale. For more
    523      *             information see the definition of ULocDataLocaleType in
    524      *             uloc.h
    525      * @param status the error code status.
    526      * @return locale where the collation data lives. If the collator
    527      *         was instantiated from rules, locale is empty.
    528      * @deprecated ICU 2.8 This API is under consideration for revision
    529      * in ICU 3.0.
    530      */
    531     virtual const Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0;
    532 
    533     /**
    534      * Convenience method for comparing two strings based on the collation rules.
    535      * @param source the source string to be compared with.
    536      * @param target the target string to be compared with.
    537      * @return true if the first string is greater than the second one,
    538      *         according to the collation rules. false, otherwise.
    539      * @see Collator#compare
    540      * @stable ICU 2.0
    541      */
    542     UBool greater(const UnicodeString& source, const UnicodeString& target)
    543                   const;
    544 
    545     /**
    546      * Convenience method for comparing two strings based on the collation rules.
    547      * @param source the source string to be compared with.
    548      * @param target the target string to be compared with.
    549      * @return true if the first string is greater than or equal to the second
    550      *         one, according to the collation rules. false, otherwise.
    551      * @see Collator#compare
    552      * @stable ICU 2.0
    553      */
    554     UBool greaterOrEqual(const UnicodeString& source,
    555                          const UnicodeString& target) const;
    556 
    557     /**
    558      * Convenience method for comparing two strings based on the collation rules.
    559      * @param source the source string to be compared with.
    560      * @param target the target string to be compared with.
    561      * @return true if the strings are equal according to the collation rules.
    562      *         false, otherwise.
    563      * @see Collator#compare
    564      * @stable ICU 2.0
    565      */
    566     UBool equals(const UnicodeString& source, const UnicodeString& target) const;
    567 
    568     /**
    569      * Determines the minimum strength that will be use in comparison or
    570      * transformation.
    571      * <p>E.g. with strength == SECONDARY, the tertiary difference is ignored
    572      * <p>E.g. with strength == PRIMARY, the secondary and tertiary difference
    573      * are ignored.
    574      * @return the current comparison level.
    575      * @see Collator#setStrength
    576      * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead
    577      */
    578     virtual ECollationStrength getStrength(void) const = 0;
    579 
    580     /**
    581      * Sets the minimum strength to be used in comparison or transformation.
    582      * <p>Example of use:
    583      * <pre>
    584      *  \code
    585      *  UErrorCode status = U_ZERO_ERROR;
    586      *  Collator*myCollation = Collator::createInstance(Locale::US, status);
    587      *  if (U_FAILURE(status)) return;
    588      *  myCollation->setStrength(Collator::PRIMARY);
    589      *  // result will be "abc" == "ABC"
    590      *  // tertiary differences will be ignored
    591      *  Collator::ComparisonResult result = myCollation->compare("abc", "ABC");
    592      * \endcode
    593      * </pre>
    594      * @see Collator#getStrength
    595      * @param newStrength the new comparison level.
    596      * @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead
    597      */
    598     virtual void setStrength(ECollationStrength newStrength) = 0;
    599 
    600     /**
    601      * Retrieves the reordering codes for this collator.
    602      * @param dest The array to fill with the script ordering.
    603      * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function
    604      *  will only return the length of the result without writing any of the result string (pre-flighting).
    605      * @param status A reference to an error code value, which must not indicate
    606      * a failure before the function call.
    607      * @return The length of the script ordering array.
    608      * @see ucol_setReorderCodes
    609      * @see Collator#getEquivalentReorderCodes
    610      * @see Collator#setReorderCodes
    611      * @draft ICU 4.8
    612      */
    613      virtual int32_t U_EXPORT2 getReorderCodes(int32_t *dest,
    614                                     int32_t destCapacity,
    615                                     UErrorCode& status) const;
    616 
    617     /**
    618      * Sets the ordering of scripts for this collator.
    619      * @param reorderCodes An array of script codes in the new order. This can be NULL if the
    620      * length is also set to 0. An empty array will clear any reordering codes on the collator.
    621      * @param reorderCodesLength The length of reorderCodes.
    622      * @see Collator#getReorderCodes
    623      * @see Collator#getEquivalentReorderCodes
    624      * @param status error code
    625      * @draft ICU 4.8
    626      */
    627      virtual void U_EXPORT2 setReorderCodes(const int32_t* reorderCodes,
    628                                 int32_t reorderCodesLength,
    629                                 UErrorCode& status) ;
    630 
    631     /**
    632      * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder
    633      * codes will be grouped and must reorder together.
    634      * @param reorderCode The reorder code to determine equivalence for.
    635      * @param dest The array to fill with the script equivalene reordering codes.
    636      * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the
    637      * function will only return the length of the result without writing any of the result
    638      * string (pre-flighting).
    639      * @param status A reference to an error code value, which must not indicate
    640      * a failure before the function call.
    641      * @return The length of the of the reordering code equivalence array.
    642      * @see ucol_setReorderCodes
    643      * @see Collator#getReorderCodes
    644      * @see Collator#setReorderCodes
    645      * @draft ICU 4.8
    646      */
    647     static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode,
    648                                 int32_t* dest,
    649                                 int32_t destCapacity,
    650                                 UErrorCode& status);
    651 
    652     /**
    653      * Get name of the object for the desired Locale, in the desired langauge
    654      * @param objectLocale must be from getAvailableLocales
    655      * @param displayLocale specifies the desired locale for output
    656      * @param name the fill-in parameter of the return value
    657      * @return display-able name of the object for the object locale in the
    658      *         desired language
    659      * @stable ICU 2.0
    660      */
    661     static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
    662                                          const Locale& displayLocale,
    663                                          UnicodeString& name);
    664 
    665     /**
    666     * Get name of the object for the desired Locale, in the langauge of the
    667     * default locale.
    668     * @param objectLocale must be from getAvailableLocales
    669     * @param name the fill-in parameter of the return value
    670     * @return name of the object for the desired locale in the default language
    671     * @stable ICU 2.0
    672     */
    673     static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
    674                                          UnicodeString& name);
    675 
    676     /**
    677      * Get the set of Locales for which Collations are installed.
    678      *
    679      * <p>Note this does not include locales supported by registered collators.
    680      * If collators might have been registered, use the overload of getAvailableLocales
    681      * that returns a StringEnumeration.</p>
    682      *
    683      * @param count the output parameter of number of elements in the locale list
    684      * @return the list of available locales for which collations are installed
    685      * @stable ICU 2.0
    686      */
    687     static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
    688 
    689     /**
    690      * Return a StringEnumeration over the locales available at the time of the call,
    691      * including registered locales.  If a severe error occurs (such as out of memory
    692      * condition) this will return null. If there is no locale data, an empty enumeration
    693      * will be returned.
    694      * @return a StringEnumeration over the locales available at the time of the call
    695      * @stable ICU 2.6
    696      */
    697     static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
    698 
    699     /**
    700      * Create a string enumerator of all possible keywords that are relevant to
    701      * collation. At this point, the only recognized keyword for this
    702      * service is "collation".
    703      * @param status input-output error code
    704      * @return a string enumeration over locale strings. The caller is
    705      * responsible for closing the result.
    706      * @stable ICU 3.0
    707      */
    708     static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status);
    709 
    710     /**
    711      * Given a keyword, create a string enumeration of all values
    712      * for that keyword that are currently in use.
    713      * @param keyword a particular keyword as enumerated by
    714      * ucol_getKeywords. If any other keyword is passed in, status is set
    715      * to U_ILLEGAL_ARGUMENT_ERROR.
    716      * @param status input-output error code
    717      * @return a string enumeration over collation keyword values, or NULL
    718      * upon error. The caller is responsible for deleting the result.
    719      * @stable ICU 3.0
    720      */
    721     static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status);
    722 
    723     /**
    724      * Given a key and a locale, returns an array of string values in a preferred
    725      * order that would make a difference. These are all and only those values where
    726      * the open (creation) of the service with the locale formed from the input locale
    727      * plus input keyword and that value has different behavior than creation with the
    728      * input locale alone.
    729      * @param keyword        one of the keys supported by this service.  For now, only
    730      *                      "collation" is supported.
    731      * @param locale        the locale
    732      * @param commonlyUsed  if set to true it will return only commonly used values
    733      *                      with the given locale in preferred order.  Otherwise,
    734      *                      it will return all the available values for the locale.
    735      * @param status ICU status
    736      * @return a string enumeration over keyword values for the given key and the locale.
    737      * @stable ICU 4.2
    738      */
    739     static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale,
    740                                                                     UBool commonlyUsed, UErrorCode& status);
    741 
    742     /**
    743      * Return the functionally equivalent locale for the given
    744      * requested locale, with respect to given keyword, for the
    745      * collation service.  If two locales return the same result, then
    746      * collators instantiated for these locales will behave
    747      * equivalently.  The converse is not always true; two collators
    748      * may in fact be equivalent, but return different results, due to
    749      * internal details.  The return result has no other meaning than
    750      * that stated above, and implies nothing as to the relationship
    751      * between the two locales.  This is intended for use by
    752      * applications who wish to cache collators, or otherwise reuse
    753      * collators when possible.  The functional equivalent may change
    754      * over time.  For more information, please see the <a
    755      * href="http://icu-project.org/userguide/locale.html#services">
    756      * Locales and Services</a> section of the ICU User Guide.
    757      * @param keyword a particular keyword as enumerated by
    758      * ucol_getKeywords.
    759      * @param locale the requested locale
    760      * @param isAvailable reference to a fillin parameter that
    761      * indicates whether the requested locale was 'available' to the
    762      * collation service. A locale is defined as 'available' if it
    763      * physically exists within the collation locale data.
    764      * @param status reference to input-output error code
    765      * @return the functionally equivalent collation locale, or the root
    766      * locale upon error.
    767      * @stable ICU 3.0
    768      */
    769     static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale,
    770                                           UBool& isAvailable, UErrorCode& status);
    771 
    772 #if !UCONFIG_NO_SERVICE
    773     /**
    774      * Register a new Collator.  The collator will be adopted.
    775      * @param toAdopt the Collator instance to be adopted
    776      * @param locale the locale with which the collator will be associated
    777      * @param status the in/out status code, no special meanings are assigned
    778      * @return a registry key that can be used to unregister this collator
    779      * @stable ICU 2.6
    780      */
    781     static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status);
    782 
    783     /**
    784      * Register a new CollatorFactory.  The factory will be adopted.
    785      * @param toAdopt the CollatorFactory instance to be adopted
    786      * @param status the in/out status code, no special meanings are assigned
    787      * @return a registry key that can be used to unregister this collator
    788      * @stable ICU 2.6
    789      */
    790     static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status);
    791 
    792     /**
    793      * Unregister a previously-registered Collator or CollatorFactory
    794      * using the key returned from the register call.  Key becomes
    795      * invalid after a successful call and should not be used again.
    796      * The object corresponding to the key will be deleted.
    797      * @param key the registry key returned by a previous call to registerInstance
    798      * @param status the in/out status code, no special meanings are assigned
    799      * @return TRUE if the collator for the key was successfully unregistered
    800      * @stable ICU 2.6
    801      */
    802     static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
    803 #endif /* UCONFIG_NO_SERVICE */
    804 
    805     /**
    806      * Gets the version information for a Collator.
    807      * @param info the version # information, the result will be filled in
    808      * @stable ICU 2.0
    809      */
    810     virtual void getVersion(UVersionInfo info) const = 0;
    811 
    812     /**
    813      * Returns a unique class ID POLYMORPHICALLY. Pure virtual method.
    814      * This method is to implement a simple version of RTTI, since not all C++
    815      * compilers support genuine RTTI. Polymorphic operator==() and clone()
    816      * methods call this method.
    817      * @return The class ID for this object. All objects of a given class have
    818      *         the same class ID.  Objects of other classes have different class
    819      *         IDs.
    820      * @stable ICU 2.0
    821      */
    822     virtual UClassID getDynamicClassID(void) const = 0;
    823 
    824     /**
    825      * Universal attribute setter
    826      * @param attr attribute type
    827      * @param value attribute value
    828      * @param status to indicate whether the operation went on smoothly or
    829      *        there were errors
    830      * @stable ICU 2.2
    831      */
    832     virtual void setAttribute(UColAttribute attr, UColAttributeValue value,
    833                               UErrorCode &status) = 0;
    834 
    835     /**
    836      * Universal attribute getter
    837      * @param attr attribute type
    838      * @param status to indicate whether the operation went on smoothly or
    839      *        there were errors
    840      * @return attribute value
    841      * @stable ICU 2.2
    842      */
    843     virtual UColAttributeValue getAttribute(UColAttribute attr,
    844                                             UErrorCode &status) = 0;
    845 
    846     /**
    847      * Sets the variable top to a collation element value of a string supplied.
    848      * @param varTop one or more (if contraction) UChars to which the variable top should be set
    849      * @param len length of variable top string. If -1 it is considered to be zero terminated.
    850      * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br>
    851      *    U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction<br>
    852      *    U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes
    853      * @return a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined
    854      * @stable ICU 2.0
    855      */
    856     virtual uint32_t setVariableTop(const UChar *varTop, int32_t len, UErrorCode &status) = 0;
    857 
    858     /**
    859      * Sets the variable top to a collation element value of a string supplied.
    860      * @param varTop an UnicodeString size 1 or more (if contraction) of UChars to which the variable top should be set
    861      * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br>
    862      *    U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction<br>
    863      *    U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes
    864      * @return a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined
    865      * @stable ICU 2.0
    866      */
    867     virtual uint32_t setVariableTop(const UnicodeString varTop, UErrorCode &status) = 0;
    868 
    869     /**
    870      * Sets the variable top to a collation element value supplied. Variable top is set to the upper 16 bits.
    871      * Lower 16 bits are ignored.
    872      * @param varTop CE value, as returned by setVariableTop or ucol)getVariableTop
    873      * @param status error code (not changed by function)
    874      * @stable ICU 2.0
    875      */
    876     virtual void setVariableTop(const uint32_t varTop, UErrorCode &status) = 0;
    877 
    878     /**
    879      * Gets the variable top value of a Collator.
    880      * Lower 16 bits are undefined and should be ignored.
    881      * @param status error code (not changed by function). If error code is set, the return value is undefined.
    882      * @stable ICU 2.0
    883      */
    884     virtual uint32_t getVariableTop(UErrorCode &status) const = 0;
    885 
    886     /**
    887      * Get an UnicodeSet that contains all the characters and sequences
    888      * tailored in this collator.
    889      * @param status      error code of the operation
    890      * @return a pointer to a UnicodeSet object containing all the
    891      *         code points and sequences that may sort differently than
    892      *         in the UCA. The object must be disposed of by using delete
    893      * @stable ICU 2.4
    894      */
    895     virtual UnicodeSet *getTailoredSet(UErrorCode &status) const;
    896 
    897 
    898     /**
    899      * Thread safe cloning operation
    900      * @return pointer to the new clone, user should remove it.
    901      * @stable ICU 2.2
    902      */
    903     virtual Collator* safeClone(void) = 0;
    904 
    905     /**
    906      * Get the sort key as an array of bytes from an UnicodeString.
    907      * Sort key byte arrays are zero-terminated and can be compared using
    908      * strcmp().
    909      * @param source string to be processed.
    910      * @param result buffer to store result in. If NULL, number of bytes needed
    911      *        will be returned.
    912      * @param resultLength length of the result buffer. If if not enough the
    913      *        buffer will be filled to capacity.
    914      * @return Number of bytes needed for storing the sort key
    915      * @stable ICU 2.2
    916      */
    917     virtual int32_t getSortKey(const UnicodeString& source,
    918                               uint8_t* result,
    919                               int32_t resultLength) const = 0;
    920 
    921     /**
    922      * Get the sort key as an array of bytes from an UChar buffer.
    923      * Sort key byte arrays are zero-terminated and can be compared using
    924      * strcmp().
    925      * @param source string to be processed.
    926      * @param sourceLength length of string to be processed.
    927      *        If -1, the string is 0 terminated and length will be decided by the
    928      *        function.
    929      * @param result buffer to store result in. If NULL, number of bytes needed
    930      *        will be returned.
    931      * @param resultLength length of the result buffer. If if not enough the
    932      *        buffer will be filled to capacity.
    933      * @return Number of bytes needed for storing the sort key
    934      * @stable ICU 2.2
    935      */
    936     virtual int32_t getSortKey(const UChar*source, int32_t sourceLength,
    937                                uint8_t*result, int32_t resultLength) const = 0;
    938 
    939     /**
    940      * Produce a bound for a given sortkey and a number of levels.
    941      * Return value is always the number of bytes needed, regardless of
    942      * whether the result buffer was big enough or even valid.<br>
    943      * Resulting bounds can be used to produce a range of strings that are
    944      * between upper and lower bounds. For example, if bounds are produced
    945      * for a sortkey of string "smith", strings between upper and lower
    946      * bounds with one level would include "Smith", "SMITH", "sMiTh".<br>
    947      * There are two upper bounds that can be produced. If UCOL_BOUND_UPPER
    948      * is produced, strings matched would be as above. However, if bound
    949      * produced using UCOL_BOUND_UPPER_LONG is used, the above example will
    950      * also match "Smithsonian" and similar.<br>
    951      * For more on usage, see example in cintltst/capitst.c in procedure
    952      * TestBounds.
    953      * Sort keys may be compared using <TT>strcmp</TT>.
    954      * @param source The source sortkey.
    955      * @param sourceLength The length of source, or -1 if null-terminated.
    956      *                     (If an unmodified sortkey is passed, it is always null
    957      *                      terminated).
    958      * @param boundType Type of bound required. It can be UCOL_BOUND_LOWER, which
    959      *                  produces a lower inclusive bound, UCOL_BOUND_UPPER, that
    960      *                  produces upper bound that matches strings of the same length
    961      *                  or UCOL_BOUND_UPPER_LONG that matches strings that have the
    962      *                  same starting substring as the source string.
    963      * @param noOfLevels  Number of levels required in the resulting bound (for most
    964      *                    uses, the recommended value is 1). See users guide for
    965      *                    explanation on number of levels a sortkey can have.
    966      * @param result A pointer to a buffer to receive the resulting sortkey.
    967      * @param resultLength The maximum size of result.
    968      * @param status Used for returning error code if something went wrong. If the
    969      *               number of levels requested is higher than the number of levels
    970      *               in the source key, a warning (U_SORT_KEY_TOO_SHORT_WARNING) is
    971      *               issued.
    972      * @return The size needed to fully store the bound.
    973      * @see ucol_keyHashCode
    974      * @stable ICU 2.1
    975      */
    976     static int32_t U_EXPORT2 getBound(const uint8_t       *source,
    977             int32_t             sourceLength,
    978             UColBoundMode       boundType,
    979             uint32_t            noOfLevels,
    980             uint8_t             *result,
    981             int32_t             resultLength,
    982             UErrorCode          &status);
    983 
    984 
    985 protected:
    986 
    987     // Collator protected constructors -------------------------------------
    988 
    989     /**
    990     * Default constructor.
    991     * Constructor is different from the old default Collator constructor.
    992     * The task for determing the default collation strength and normalization
    993     * mode is left to the child class.
    994     * @stable ICU 2.0
    995     */
    996     Collator();
    997 
    998     /**
    999     * Constructor.
   1000     * Empty constructor, does not handle the arguments.
   1001     * This constructor is done for backward compatibility with 1.7 and 1.8.
   1002     * The task for handling the argument collation strength and normalization
   1003     * mode is left to the child class.
   1004     * @param collationStrength collation strength
   1005     * @param decompositionMode
   1006     * @deprecated ICU 2.4. Subclasses should use the default constructor
   1007     * instead and handle the strength and normalization mode themselves.
   1008     */
   1009     Collator(UCollationStrength collationStrength,
   1010              UNormalizationMode decompositionMode);
   1011 
   1012     /**
   1013     * Copy constructor.
   1014     * @param other Collator object to be copied from
   1015     * @stable ICU 2.0
   1016     */
   1017     Collator(const Collator& other);
   1018 
   1019     // Collator protected methods -----------------------------------------
   1020 
   1021 
   1022    /**
   1023     * Used internally by registraton to define the requested and valid locales.
   1024     * @param requestedLocale the requested locale
   1025     * @param validLocale the valid locale
   1026     * @param actualLocale the actual locale
   1027     * @internal
   1028     */
   1029     virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale);
   1030 
   1031 public:
   1032 #if !UCONFIG_NO_SERVICE
   1033     /**
   1034      * used only by ucol_open, not for public use
   1035      * @internal
   1036      */
   1037     static UCollator* createUCollator(const char* loc, UErrorCode* status);
   1038 #endif
   1039 private:
   1040     /**
   1041      * Assignment operator. Private for now.
   1042      * @internal
   1043      */
   1044     Collator& operator=(const Collator& other);
   1045 
   1046     friend class CFactory;
   1047     friend class SimpleCFactory;
   1048     friend class ICUCollatorFactory;
   1049     friend class ICUCollatorService;
   1050     static Collator* makeInstance(const Locale& desiredLocale,
   1051                                   UErrorCode& status);
   1052 
   1053     // Collator private data members ---------------------------------------
   1054 
   1055     /*
   1056     synwee : removed as attributes to be handled by child class
   1057     UCollationStrength  strength;
   1058     Normalizer::EMode  decmp;
   1059     */
   1060     /* This is useless information */
   1061 /*  static const UVersionInfo fVersion;*/
   1062 };
   1063 
   1064 #if !UCONFIG_NO_SERVICE
   1065 /**
   1066  * A factory, used with registerFactory, the creates multiple collators and provides
   1067  * display names for them.  A factory supports some number of locales-- these are the
   1068  * locales for which it can create collators.  The factory can be visible, in which
   1069  * case the supported locales will be enumerated by getAvailableLocales, or invisible,
   1070  * in which they are not.  Invisible locales are still supported, they are just not
   1071  * listed by getAvailableLocales.
   1072  * <p>
   1073  * If standard locale display names are sufficient, Collator instances can
   1074  * be registered using registerInstance instead.</p>
   1075  * <p>
   1076  * Note: if the collators are to be used from C APIs, they must be instances
   1077  * of RuleBasedCollator.</p>
   1078  *
   1079  * @stable ICU 2.6
   1080  */
   1081 class U_I18N_API CollatorFactory : public UObject {
   1082 public:
   1083 
   1084     /**
   1085      * Destructor
   1086      * @stable ICU 3.0
   1087      */
   1088     virtual ~CollatorFactory();
   1089 
   1090     /**
   1091      * Return true if this factory is visible.  Default is true.
   1092      * If not visible, the locales supported by this factory will not
   1093      * be listed by getAvailableLocales.
   1094      * @return true if the factory is visible.
   1095      * @stable ICU 2.6
   1096      */
   1097     virtual UBool visible(void) const;
   1098 
   1099     /**
   1100      * Return a collator for the provided locale.  If the locale
   1101      * is not supported, return NULL.
   1102      * @param loc the locale identifying the collator to be created.
   1103      * @return a new collator if the locale is supported, otherwise NULL.
   1104      * @stable ICU 2.6
   1105      */
   1106     virtual Collator* createCollator(const Locale& loc) = 0;
   1107 
   1108     /**
   1109      * Return the name of the collator for the objectLocale, localized for the displayLocale.
   1110      * If objectLocale is not supported, or the factory is not visible, set the result string
   1111      * to bogus.
   1112      * @param objectLocale the locale identifying the collator
   1113      * @param displayLocale the locale for which the display name of the collator should be localized
   1114      * @param result an output parameter for the display name, set to bogus if not supported.
   1115      * @return the display name
   1116      * @stable ICU 2.6
   1117      */
   1118     virtual  UnicodeString& getDisplayName(const Locale& objectLocale,
   1119                                            const Locale& displayLocale,
   1120                                            UnicodeString& result);
   1121 
   1122     /**
   1123      * Return an array of all the locale names directly supported by this factory.
   1124      * The number of names is returned in count.  This array is owned by the factory.
   1125      * Its contents must never change.
   1126      * @param count output parameter for the number of locales supported by the factory
   1127      * @param status the in/out error code
   1128      * @return a pointer to an array of count UnicodeStrings.
   1129      * @stable ICU 2.6
   1130      */
   1131     virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0;
   1132 };
   1133 #endif /* UCONFIG_NO_SERVICE */
   1134 
   1135 // Collator inline methods -----------------------------------------------
   1136 
   1137 U_NAMESPACE_END
   1138 
   1139 #endif /* #if !UCONFIG_NO_COLLATION */
   1140 
   1141 #endif
   1142