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