source/i18n/unicode/coll.h

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