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