codekingpro/portable-devtools
115k
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
70U_NAMESPACE_BEGIN
71
72class StringEnumeration;
73
74#if !UCONFIG_NO_SERVICE
75/**
76 * @stable ICU 2.6
77 */
78class CollatorFactory;
79#endif
80
81/**
82* @stable ICU 2.0
83*/
84class 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
167class U_I18N_API Collator : public UObject {
168public:
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 /**
239 * Returns TRUE if "other" is the same as "this".
240 *
241 * The base class implementation returns TRUE if "other" has the same type/class as "this":
242 * `typeid(*this) == typeid(other)`.
243 *
244 * Subclass implementations should do something like the following:
245 *
246 * if (this == &other) { return TRUE; }
247 * if (!Collator::operator==(other)) { return FALSE; } // not the same class
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
253 * @return TRUE if other is the same as this.
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
262 * @return TRUE if other is not the same as this.
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").
307 * See <a href="http://userguide.icu-project.org/collation/api">User Guide: Collation API</a>.
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
791 * href="http://userguide.icu-project.org/locale#TOC-Locales-and-Services">
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
844 * @return TRUE if the collator for the key was successfully unregistered
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
1090protected:
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
1126public:
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:
1142 * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme
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