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