Collator


1   /**
2   *******************************************************************************
3   * Copyright (C) 1996-2006, International Business Machines Corporation and    *
4   * others. All Rights Reserved.                                                *
5   *******************************************************************************
6   */
7   package com.ibm.icu.text;
8   
9   import java.util.Comparator  ;
10  import java.util.Locale  ;
11  import java.util.MissingResourceException  ;
12  import java.util.Set  ;
13  
14  import com.ibm.icu.impl.ICUDebug;
15  import com.ibm.icu.impl.ICUResourceBundle;
16  import com.ibm.icu.impl.LocaleUtility;
17  import com.ibm.icu.util.ULocale;
18  import com.ibm.icu.util.UResourceBundle;
19  import com.ibm.icu.util.VersionInfo;
20  
21  /**
22  * <p>Collator performs locale-sensitive string comparison. A concrete
23  * subclass, RuleBasedCollator, allows customization of the collation
24  * ordering by the use of rule sets.</p>
25  *
26  * <p>Following the <a HREF=http://www.unicode.org>Unicode
27  * Consortium</a>'s specifications for the
28  * <a HREF="http://www.unicode.org/unicode/reports/tr10/"> Unicode Collation
29  * Algorithm (UCA)</a>, there are 5 different levels of strength used
30  * in comparisons:
31  *
32  * <ul>
33  * <li>PRIMARY strength: Typically, this is used to denote differences between
34  *     base characters (for example, "a" &lt; "b").
35  *     It is the strongest difference. For example, dictionaries are divided
36  *     into different sections by base character.
37  * <li>SECONDARY strength: Accents in the characters are considered secondary
38  *     differences (for example, "as" &lt; "&agrave;s" &lt; "at"). Other
39  *     differences
40  *     between letters can also be considered secondary differences, depending
41  *     on the language. A secondary difference is ignored when there is a
42  *     primary difference anywhere in the strings.
43  * <li>TERTIARY strength: Upper and lower case differences in characters are
44  *     distinguished at tertiary strength (for example, "ao" &lt; "Ao" &lt;
45  *     "a&ograve;"). In addition, a variant of a letter differs from the base
46  *     form on the tertiary strength (such as "A" and "&#9398;"). Another
47  *     example is the
48  *     difference between large and small Kana. A tertiary difference is ignored
49  *     when there is a primary or secondary difference anywhere in the strings.
50  * <li>QUATERNARY strength: When punctuation is ignored
51  *     <a HREF="http://icu.sourceforge.net/userguide/Collate_Concepts.html#Ignoring_Punctuation">
52  *     (see Ignoring Punctuations in the user guide)</a> at PRIMARY to TERTIARY
53  *     strength, an additional strength level can
54  *     be used to distinguish words with and without punctuation (for example,
55  *     "ab" &lt; "a-b" &lt; "aB").
56  *     This difference is ignored when there is a PRIMARY, SECONDARY or TERTIARY
57  *     difference. The QUATERNARY strength should only be used if ignoring
58  *     punctuation is required.
59  * <li>IDENTICAL strength:
60  *     When all other strengths are equal, the IDENTICAL strength is used as a
61  *     tiebreaker. The Unicode code point values of the NFD form of each string
62  *     are compared, just in case there is no difference.
63  *     For example, Hebrew cantellation marks are only distinguished at this
64  *     strength. This strength should be used sparingly, as only code point
65  *     value differences between two strings is an extremely rare occurrence.
66  *     Using this strength substantially decreases the performance for both
67  *     comparison and collation key generation APIs. This strength also
68  *     increases the size of the collation key.
69  * </ul>
70  *
71  * Unlike the JDK, ICU4J's Collator deals only with 2 decomposition modes,
72  * the canonical decomposition mode and one that does not use any decomposition.
73  * The compatibility decomposition mode, java.text.Collator.FULL_DECOMPOSITION
74  * is not supported here. If the canonical
75  * decomposition mode is set, the Collator handles un-normalized text properly,
76  * producing the same results as if the text were normalized in NFD. If
77  * canonical decomposition is turned off, it is the user's responsibility to
78  * ensure that all text is already in the appropriate form before performing
79  * a comparison or before getting a CollationKey.</p>
80  *
81  * <p>For more information about the collation service see the
82  * <a HREF="http://icu.sourceforge.net/userguide/Collate_Intro.html">users
83  * guide</a>.</p>
84  *
85  * <p>Examples of use
86  * <pre>
87  * // Get the Collator for US English and set its strength to PRIMARY
88  * Collator usCollator = Collator.getInstance(Locale.US);
89  * usCollator.setStrength(Collator.PRIMARY);
90  * if (usCollator.compare("abc", "ABC") == 0) {
91  *     System.out.println("Strings are equivalent");
92  * }
93  *
94  * The following example shows how to compare two strings using the
95  * Collator for the default locale.
96  *
97  * // Compare two strings in the default locale
98  * Collator myCollator = Collator.getInstance();
99  * myCollator.setDecomposition(NO_DECOMPOSITION);
100 * if (myCollator.compare("&agrave;&#92;u0325", "a&#92;u0325&#768;") != 0) {
101 *     System.out.println("&agrave;&#92;u0325 is not equals to a&#92;u0325&#768; without decomposition");
102 *     myCollator.setDecomposition(CANONICAL_DECOMPOSITION);
103 *     if (myCollator.compare("&agrave;&#92;u0325", "a&#92;u0325&#768;") != 0) {
104 *         System.out.println("Error: &agrave;&#92;u0325 should be equals to a&#92;u0325&#768; with decomposition");
105 *     }
106 *     else {
107 *         System.out.println("&agrave;&#92;u0325 is equals to a&#92;u0325&#768; with decomposition");
108 *     }
109 * }
110 * else {
111 *     System.out.println("Error: &agrave;&#92;u0325 should be not equals to a&#92;u0325&#768; without decomposition");
112 * }
113 * </pre>
114 * </p>
115 * @see RuleBasedCollator
116 * @see CollationKey
117 * @author Syn Wee Quek
118 * @stable ICU 2.8
119 */
120 public abstract class Collator implements Comparator  , Cloneable  
121 {
122     // public data members ---------------------------------------------------
123 
124     /**
125      * Strongest collator strength value. Typically used to denote differences
126      * between base characters. See class documentation for more explanation.
127      * @see #setStrength
128      * @see #getStrength
129      * @stable ICU 2.8
130      */
131     public final static int PRIMARY = 0;
132 
133     /**
134      * Second level collator strength value.
135      * Accents in the characters are considered secondary differences.
136      * Other differences between letters can also be considered secondary
137      * differences, depending on the language.
138      * See class documentation for more explanation.
139      * @see #setStrength
140      * @see #getStrength
141      * @stable ICU 2.8
142      */
143     public final static int SECONDARY = 1;
144 
145     /**
146      * Third level collator strength value.
147      * Upper and lower case differences in characters are distinguished at this
148      * strength level. In addition, a variant of a letter differs from the base
149      * form on the tertiary level.
150      * See class documentation for more explanation.
151      * @see #setStrength
152      * @see #getStrength
153      * @stable ICU 2.8
154      */
155     public final static int TERTIARY = 2;
156 
157     /**
158      * Fourth level collator strength value.
159      * When punctuation is ignored
160      * <a HREF="http://icu.sourceforge.net/userguide/Collate_Concepts.html#Ignoring_Punctuation">
161      * (see Ignoring Punctuations in the user guide)</a> at PRIMARY to TERTIARY
162      * strength, an additional strength level can
163      * be used to distinguish words with and without punctuation.
164      * See class documentation for more explanation.
165      * @see #setStrength
166      * @see #getStrength
167      * @stable ICU 2.8
168      */
169     public final static int QUATERNARY = 3;
170 
171     /**
172      * <p>
173      * Smallest Collator strength value. When all other strengths are equal,
174      * the IDENTICAL strength is used as a tiebreaker. The Unicode code point
175      * values of the NFD form of each string are compared, just in case there
176      * is no difference.
177      * See class documentation for more explanation.
178      * </p>
179      * <p>
180      * Note this value is different from JDK's
181      * </p>
182      * @stable ICU 2.8
183      */
184     public final static int IDENTICAL = 15;
185 
186     /**
187      * This is for backwards compatibility with Java APIs only.  It
188      * should not be used, IDENTICAL should be used instead.  ICU's
189      * collation does not support Java's FULL_DECOMPOSITION mode.
190      * @draft ICU 3.4
191      * @provisional This API might change or be removed in a future release.
192      */
193     public final static int FULL_DECOMPOSITION = IDENTICAL;
194 
195     /**
196      * <p>Decomposition mode value. With NO_DECOMPOSITION set, Strings
197      * will not be decomposed for collation. This is the default
198      * decomposition setting unless otherwise specified by the locale
199      * used to create the Collator.</p>
200      *
201      * <p><strong>Note</strong> this value is different from the JDK's.</p>
202      * @see #CANONICAL_DECOMPOSITION
203      * @see #getDecomposition
204      * @see #setDecomposition
205      * @stable ICU 2.8
206      */
207     public final static int NO_DECOMPOSITION = 16;
208 
209     /**
210      * <p>Decomposition mode value. With CANONICAL_DECOMPOSITION set,
211      * characters that are canonical variants according to the Unicode standard
212      * will be decomposed for collation.</p>
213      *
214      * <p>CANONICAL_DECOMPOSITION corresponds to Normalization Form D as
215      * described in <a HREF="http://www.unicode.org/unicode/reports/tr15/">
216      * Unicode Technical Report #15</a>.
217      * </p>
218      * @see #NO_DECOMPOSITION
219      * @see #getDecomposition
220      * @see #setDecomposition
221      * @stable ICU 2.8
222      */
223     public final static int CANONICAL_DECOMPOSITION = 17;
224 
225     // public methods --------------------------------------------------------
226 
227     // public setters --------------------------------------------------------
228 
229     /**
230      * <p>Sets this Collator's strength property. The strength property
231      * determines the minimum level of difference considered significant
232      * during comparison.</p>
233      *
234      * <p>The default strength for the Collator is TERTIARY, unless specified
235      * otherwise by the locale used to create the Collator.</p>
236      *
237      * <p>See the Collator class description for an example of use.</p>
238      * @param newStrength the new strength value.
239      * @see #getStrength
240      * @see #PRIMARY
241      * @see #SECONDARY
242      * @see #TERTIARY
243      * @see #QUATERNARY
244      * @see #IDENTICAL
245      * @exception IllegalArgumentException if the new strength value is not one
246      *                of PRIMARY, SECONDARY, TERTIARY, QUATERNARY or IDENTICAL.
247      * @stable ICU 2.8
248      */
249     public void setStrength(int newStrength)
250     {
251         if ((newStrength != PRIMARY) &&
252             (newStrength != SECONDARY) &&
253             (newStrength != TERTIARY) &&
254             (newStrength != QUATERNARY) &&
255             (newStrength != IDENTICAL)) {
256             throw new IllegalArgumentException  ("Incorrect comparison level.");
257         }
258         m_strength_ = newStrength;
259     }
260 
261     /**
262      * <p>Set the decomposition mode of this Collator.  Setting this
263      * decomposition property with CANONICAL_DECOMPOSITION allows the
264      * Collator to handle un-normalized text properly, producing the
265      * same results as if the text were normalized. If
266      * NO_DECOMPOSITION is set, it is the user's responsibility to
267      * insure that all text is already in the appropriate form before
268      * a comparison or before getting a CollationKey. Adjusting
269      * decomposition mode allows the user to select between faster and
270      * more complete collation behavior.</p>
271      *
272      * <p>Since a great many of the world's languages do not require
273      * text normalization, most locales set NO_DECOMPOSITION as the
274      * default decomposition mode.</p>
275      *
276      * The default decompositon mode for the Collator is
277      * NO_DECOMPOSITON, unless specified otherwise by the locale used
278      * to create the Collator.</p>
279      *
280      * <p>See getDecomposition for a description of decomposition
281      * mode.</p>
282      *
283      * @param decomposition the new decomposition mode
284      * @see #getDecomposition
285      * @see #NO_DECOMPOSITION
286      * @see #CANONICAL_DECOMPOSITION
287      * @exception IllegalArgumentException If the given value is not a valid
288      *            decomposition mode.
289      * @stable ICU 2.8
290      */
291     public void setDecomposition(int decomposition)
292     {
293         if ((decomposition != NO_DECOMPOSITION) &&
294             (decomposition != CANONICAL_DECOMPOSITION)) {
295             throw new IllegalArgumentException  ("Wrong decomposition mode.");
296         }
297         m_decomposition_ = decomposition;
298     }
299 
300     // public getters --------------------------------------------------------
301 
302     /**
303      * Gets the Collator for the current default locale.
304      * The default locale is determined by java.util.Locale.getDefault().
305      * @return the Collator for the default locale (for example, en_US) if it
306      *         is created successfully. Otherwise if there is no Collator
307      *         associated with the current locale, the default UCA collator
308      *         will be returned.
309      * @see java.util.Locale#getDefault()
310      * @see #getInstance(Locale)
311      * @stable ICU 2.8
312      */
313     public static final Collator getInstance()
314     {
315         return getInstance(ULocale.getDefault());
316     }
317 
318     /**
319      * Clone the collator.
320      * @stable ICU 2.6
321      * @return a clone of this collator.
322      */
323     public Object   clone() throws CloneNotSupportedException   {
324         return super.clone();
325     }
326 
327     // begin registry stuff
328 
329     /**
330      * A factory used with registerFactory to register multiple collators and provide
331      * display names for them.  If standard locale display names are sufficient, 
332      * Collator instances may be registered instead.
333      * <p><b>Note:</b> as of ICU4J 3.2, the default API for CollatorFactory uses
334      * ULocale instead of Locale.  Instead of overriding createCollator(Locale),
335      * new implementations should override createCollator(ULocale).  Note that
336      * one of these two methods <b>MUST</b> be overridden or else an infinite
337      * loop will occur.
338      * @stable ICU 2.6
339      */
340     public static abstract class CollatorFactory {
341         /**
342          * Return true if this factory will be visible.  Default is true.
343          * If not visible, the locales supported by this factory will not
344          * be listed by getAvailableLocales.
345          *
346          * @return true if this factory is visible
347          * @stable ICU 2.6
348          */
349         public boolean visible() {
350             return true;
351         }
352 
353         /**
354          * Return an instance of the appropriate collator.  If the locale
355          * is not supported, return null.
356          * <b>Note:</b> as of ICU4J 3.2, implementations should override
357          * this method instead of createCollator(Locale).
358          * @param loc the locale for which this collator is to be created.
359          * @return the newly created collator.
360          * @draft ICU 3.2
361          * @provisional This API might change or be removed in a future release.
362          */
363         public Collator createCollator(ULocale loc) {
364             return createCollator(loc.toLocale());
365         }
366 
367         /**
368          * Return an instance of the appropriate collator.  If the locale
369          * is not supported, return null.
370          * <p><b>Note:</b> as of ICU4J 3.2, implementations should override
371          * createCollator(ULocale) instead of this method, and inherit this
372          * method's implementation.  This method is no longer abstract
373          * and instead delegates to createCollator(ULocale).
374          * @param loc the locale for which this collator is to be created.
375          * @return the newly created collator.
376          * @stable ICU 2.6
377          */
378          public Collator createCollator(Locale   loc) {
379             return createCollator(ULocale.forLocale(loc));
380         }
381 
382         /**
383          * Return the name of the collator for the objectLocale, localized for the displayLocale.
384          * If objectLocale is not visible or not defined by the factory, return null.
385          * @param objectLocale the locale identifying the collator
386          * @param displayLocale the locale for which the display name of the collator should be localized
387          * @return the display name
388          * @stable ICU 2.6
389          */
390         public String   getDisplayName(Locale   objectLocale, Locale   displayLocale) {
391             return getDisplayName(ULocale.forLocale(objectLocale), ULocale.forLocale(displayLocale));
392         }
393 
394         /**
395          * Return the name of the collator for the objectLocale, localized for the displayLocale.
396          * If objectLocale is not visible or not defined by the factory, return null.
397          * @param objectLocale the locale identifying the collator
398          * @param displayLocale the locale for which the display name of the collator should be localized
399          * @return the display name
400          * @draft ICU 3.2
401          * @provisional This API might change or be removed in a future release.
402          */
403         public String   getDisplayName(ULocale objectLocale, ULocale displayLocale) {
404             if (visible()) {
405                 Set   supported = getSupportedLocaleIDs();
406                 String   name = objectLocale.getBaseName();
407                 if (supported.contains(name)) {
408                     return objectLocale.getDisplayName(displayLocale);
409                 }
410             }
411             return null;
412         }
413 
414         /**
415          * Return an unmodifiable collection of the locale names directly 
416          * supported by this factory.
417          *
418          * @return the set of supported locale IDs.
419          * @stable ICU 2.6
420          */
421         public abstract Set   getSupportedLocaleIDs();
422 
423         /**
424          * Empty default constructor.
425          * @stable ICU 2.6
426          */
427         protected CollatorFactory() {
428         }
429     }
430 
431     static abstract class ServiceShim {
432         abstract Collator getInstance(ULocale l);
433         abstract Object   registerInstance(Collator c, ULocale l);
434         abstract Object   registerFactory(CollatorFactory f);
435         abstract boolean unregister(Object   k);
436         abstract Locale  [] getAvailableLocales(); // TODO remove
437         abstract ULocale[] getAvailableULocales();
438         abstract String   getDisplayName(ULocale ol, ULocale dl);
439     }
440     
441     private static ServiceShim shim;
442     private static ServiceShim getShim() {
443         // Note: this instantiation is safe on loose-memory-model configurations
444         // despite lack of synchronization, since the shim instance has no state--
445         // it's all in the class init.  The worst problem is we might instantiate
446         // two shim instances, but they'll share the same state so that's ok.
447         if (shim == null) {
448             try {
449                 Class   cls = Class.forName("com.ibm.icu.text.CollatorServiceShim");
450                 shim = (ServiceShim)cls.newInstance();
451             }
452             catch (MissingResourceException   e)
453             {
454                 throw e;
455             }
456             catch (Exception   e) {
457                 ///CLOVER:OFF
458                 if(DEBUG){
459                     e.printStackTrace();
460                 }
461                 throw new RuntimeException  (e.getMessage());
462                 ///CLOVER:ON
463             }
464         }
465         return shim;
466     }
467 
468     /**
469      * Gets the Collator for the desired locale.
470      * @param locale the desired locale.
471      * @return Collator for the desired locale if it is created successfully.
472      *         Otherwise if there is no Collator
473      *         associated with the current locale, a default UCA collator will
474      *         be returned.
475      * @see java.util.Locale
476      * @see java.util.ResourceBundle
477      * @see #getInstance(Locale)
478      * @see #getInstance()
479      * @stable ICU 3.0
480      */
481     public static final Collator getInstance(ULocale locale) {
482         // fetching from service cache is faster than instantiation
483         return getShim().getInstance(locale);
484     }
485 
486     /**
487      * Gets the Collator for the desired locale.
488      * @param locale the desired locale.
489      * @return Collator for the desired locale if it is created successfully.
490      *         Otherwise if there is no Collator
491      *         associated with the current locale, a default UCA collator will
492      *         be returned.
493      * @see java.util.Locale
494      * @see java.util.ResourceBundle
495      * @see #getInstance(ULocale)
496      * @see #getInstance()
497      * @stable ICU 2.8
498      */
499     public static final Collator getInstance(Locale   locale) {
500         return getInstance(ULocale.forLocale(locale));
501     }
502 
503     /**
504      * Register a collator as the default collator for the provided locale.  The
505      * collator should not be modified after it is registered.
506      *
507      * @param collator the collator to register
508      * @param locale the locale for which this is the default collator
509      * @return an object that can be used to unregister the registered collator.
510      *
511      * @draft ICU 3.2
512      * @provisional This API might change or be removed in a future release.
513      */
514     public static final Object   registerInstance(Collator collator, ULocale locale) {
515         return getShim().registerInstance(collator, locale);
516     }
517 
518     /**
519      * Register a collator factory.
520      *
521      * @param factory the factory to register
522      * @return an object that can be used to unregister the registered factory.
523      *
524      * @stable ICU 2.6
525      */
526     public static final Object   registerFactory(CollatorFactory factory) {
527         return getShim().registerFactory(factory);
528     }
529 
530     /**
531      * Unregister a collator previously registered using registerInstance.
532      * @param registryKey the object previously returned by registerInstance.
533      * @return true if the collator was successfully unregistered.
534      * @stable ICU 2.6
535      */
536     public static final boolean unregister(Object   registryKey) {
537         if (shim == null) {
538             return false;
539         }
540         return shim.unregister(registryKey);
541     }
542 
543     /**
544      * Get the set of locales, as Locale objects, for which collators
545      * are installed.  Note that Locale objects do not support RFC 3066.
546      * @return the list of locales in which collators are installed.
547      * This list includes any that have been registered, in addition to
548      * those that are installed with ICU4J.
549      * @stable ICU 2.4
550      */
551     public static Locale  [] getAvailableLocales() {
552         // TODO make this wrap getAvailableULocales later
553         if (shim == null) {
554             return ICUResourceBundle.getAvailableLocales(ICUResourceBundle.ICU_COLLATION_BASE_NAME);
555         }
556         return shim.getAvailableLocales();
557     }
558 
559     /**
560      * Get the set of locales, as ULocale objects, for which collators
561      * are installed.  ULocale objects support RFC 3066.
562      * @return the list of locales in which collators are installed.
563      * This list includes any that have been registered, in addition to
564      * those that are installed with ICU4J.
565      * @stable ICU 3.0
566      */
567     public static final ULocale[] getAvailableULocales() {
568         if (shim == null) {
569             return ICUResourceBundle.getAvailableULocales(ICUResourceBundle.ICU_COLLATION_BASE_NAME);
570         }
571         return shim.getAvailableULocales();
572     }
573     
574     /**
575      * The list of keywords for this service.  This must be kept in sync with
576      * the resource data.
577      * @since ICU 3.0
578      */
579     private static final String  [] KEYWORDS = { "collation" };
580 
581     /**
582      * The resource name for this service.  Note that this is not the same as
583      * the keyword for this service.
584      * @since ICU 3.0
585      */
586     private static final String   RESOURCE = "collations";
587 
588     /**
589      * The resource bundle base name for this service.
590      * *since ICU 3.0
591      */
592     private static final String   BASE = ICUResourceBundle.ICU_COLLATION_BASE_NAME;
593 
594     /**
595      * Return an array of all possible keywords that are relevant to
596      * collation. At this point, the only recognized keyword for this
597      * service is "collation".
598      * @return an array of valid collation keywords.
599      * @see #getKeywordValues
600      * @stable ICU 3.0
601      */
602     public static final String  [] getKeywords() {
603         return KEYWORDS;
604     }
605     
606     /**
607      * Given a keyword, return an array of all values for
608      * that keyword that are currently in use.
609      * @param keyword one of the keywords returned by getKeywords.
610      * @see #getKeywords
611      * @stable ICU 3.0
612      */
613     public static final String  [] getKeywordValues(String   keyword) {
614         if (!keyword.equals(KEYWORDS[0])) {
615             throw new IllegalArgumentException  ("Invalid keyword: " + keyword);
616         }
617         return ICUResourceBundle.getKeywordValues(BASE, RESOURCE);
618     }
619 
620     /**
621      * Return the functionally equivalent locale for the given
622      * requested locale, with respect to given keyword, for the
623      * collation service.  If two locales return the same result, then
624      * collators instantiated for these locales will behave
625      * equivalently.  The converse is not always true; two collators
626      * may in fact be equivalent, but return different results, due to
627      * internal details.  The return result has no other meaning than
628      * that stated above, and implies nothing as to the relationship
629      * between the two locales.  This is intended for use by
630      * applications who wish to cache collators, or otherwise reuse
631      * collators when possible.  The functional equivalent may change
632      * over time.  For more information, please see the <a
633      * HREF="http://icu.sourceforge.net/userguide/locale.html#services">
634      * Locales and Services</a> section of the ICU User Guide.
635      * @param keyword a particular keyword as enumerated by
636      * getKeywords.
637      * @param locID The requested locale
638      * @param isAvailable If non-null, isAvailable[0] will receive and
639      * output boolean that indicates whether the requested locale was
640      * 'available' to the collation service. The locale is defined as
641      * 'available' if it physically exists within the collation locale
642      * data.  If non-null, isAvailable must have length >= 1.
643      * @return the locale
644      * @stable ICU 3.0
645      */
646     public static final ULocale getFunctionalEquivalent(String   keyword,
647                                                         ULocale locID,
648                                                         boolean isAvailable[]) {
649         return ICUResourceBundle.getFunctionalEquivalent(
650                                                          BASE, RESOURCE, keyword, locID, isAvailable);
651     }
652     
653     /**
654      * Return the functionally equivalent locale for the given
655      * requested locale, with respect to given keyword, for the
656      * collation service.
657      * @param keyword a particular keyword as enumerated by
658      * getKeywords.
659      * @param locID The requested locale
660      * @return the locale
661      * @see #getFunctionalEquivalent(String,ULocale,boolean[])
662      * @stable ICU 3.0
663      */
664     public static final ULocale getFunctionalEquivalent(String   keyword,
665                                                         ULocale locID) {
666         return getFunctionalEquivalent(keyword, locID, null);
667     }
668     
669     /**
670      * Get the name of the collator for the objectLocale, localized for the displayLocale.
671      * @param objectLocale the locale of the collator
672      * @param displayLocale the locale for the collator's display name
673      * @return the display name
674      * @stable ICU 2.6
675      */
676     static public String   getDisplayName(Locale   objectLocale, Locale   displayLocale) {
677         return getShim().getDisplayName(ULocale.forLocale(objectLocale), 
678                                         ULocale.forLocale(displayLocale));
679     }
680 
681     /**
682      * Get the name of the collator for the objectLocale, localized for the displayLocale.
683      * @param objectLocale the locale of the collator
684      * @param displayLocale the locale for the collator's display name
685      * @return the display name
686      * @draft ICU 3.2
687      * @provisional This API might change or be removed in a future release.
688      */
689     static public String   getDisplayName(ULocale objectLocale, ULocale displayLocale) {
690         return getShim().getDisplayName(objectLocale, displayLocale);
691     }
692 
693     /**
694      * Get the name of the collator for the objectLocale, localized for the current locale.
695      * @param objectLocale the locale of the collator
696      * @return the display name
697      * @stable ICU 2.6
698      */
699     static public String   getDisplayName(Locale   objectLocale) {
700         return getShim().getDisplayName(ULocale.forLocale(objectLocale), ULocale.getDefault());
701     }
702 
703     /**
704      * Get the name of the collator for the objectLocale, localized for the current locale.
705      * @param objectLocale the locale of the collator
706      * @return the display name
707      * @draft ICU 3.2
708      * @provisional This API might change or be removed in a future release.
709      */
710     static public String   getDisplayName(ULocale objectLocale) {
711         return getShim().getDisplayName(objectLocale, ULocale.getDefault());
712     }
713 
714     /**
715      * <p>Returns this Collator's strength property. The strength property
716      * determines the minimum level of difference considered significant.
717      * </p>
718      * <p>
719      * See the Collator class description for more details.
720      * </p>
721      * @return this Collator's current strength property.
722      * @see #setStrength
723      * @see #PRIMARY
724      * @see #SECONDARY
725      * @see #TERTIARY
726      * @see #QUATERNARY
727      * @see #IDENTICAL
728      * @stable ICU 2.8
729      */
730     public int getStrength()
731     {
732         return m_strength_;
733     }
734 
735     /**
736      * <p>
737      * Get the decomposition mode of this Collator. Decomposition mode
738      * determines how Unicode composed characters are handled.
739      * </p>
740      * <p>
741      * See the Collator class description for more details.
742      * </p>
743      * @return the decomposition mode
744      * @see #setDecomposition
745      * @see #NO_DECOMPOSITION
746      * @see #CANONICAL_DECOMPOSITION
747      * @stable ICU 2.8
748      */
749     public int getDecomposition()
750     {
751         return m_decomposition_;
752     }
753 
754     /**
755      * <p>
756      * Compares the source text String to the target text String according to
757      * this Collator's rules, strength and decomposition mode.
758      * Returns an integer less than,
759      * equal to or greater than zero depending on whether the source String is
760      * less than, equal to or greater than the target String. See the Collator
761      * class description for an example of use.
762      * </p>
763      * @param source the source String.
764      * @param target the target String.
765      * @return Returns an integer value. Value is less than zero if source is
766      *         less than target, value is zero if source and target are equal,
767      *         value is greater than zero if source is greater than target.
768      * @see CollationKey
769      * @see #getCollationKey
770      * @exception NullPointerException thrown if either arguments is null.
771      *            IllegalArgumentException thrown if either source or target is
772      *            not of the class String.
773      * @stable ICU 2.8
774      */
775     public int compare(Object   source, Object   target)
776     {
777         if (!(source instanceof String  ) || !(target instanceof String  )) {
778             throw new IllegalArgumentException  ("Arguments have to be of type String");
779         }
780         return compare((String  )source, (String  )target);
781     }
782 
783     // public other methods -------------------------------------------------
784 
785     /**
786      * Convenience method for comparing the equality of two text Strings using
787      * this Collator's rules, strength and decomposition mode.
788      * @param source the source string to be compared.
789      * @param target the target string to be compared.
790      * @return true if the strings are equal according to the collation
791      *         rules, otherwise false.
792      * @see #compare
793      * @exception NullPointerException thrown if either arguments is null.
794      * @stable ICU 2.8
795      */
796     public boolean equals(String   source, String   target)
797     {
798         return (compare(source, target) == 0);
799     }
800 
801     /**
802      * Get an UnicodeSet that contains all the characters and sequences
803      * tailored in this collator.
804      * @return a pointer to a UnicodeSet object containing all the
805      *         code points and sequences that may sort differently than
806      *         in the UCA.
807      * @stable ICU 2.4
808      */
809     public UnicodeSet getTailoredSet()
810     {
811         return new UnicodeSet(0, 0x10FFFF);
812     }
813 
814     /**
815      * <p>
816      * Compares the source text String to the target text String according to
817      * this Collator's rules, strength and decomposition mode.
818      * Returns an integer less than,
819      * equal to or greater than zero depending on whether the source String is
820      * less than, equal to or greater than the target String. See the Collator
821      * class description for an example of use.
822      * </p>
823      * @param source the source String.
824      * @param target the target String.
825      * @return Returns an integer value. Value is less than zero if source is
826      *         less than target, value is zero if source and target are equal,
827      *         value is greater than zero if source is greater than target.
828      * @see CollationKey
829      * @see #getCollationKey
830      * @exception NullPointerException thrown if either arguments is null.
831      * @stable ICU 2.8
832      */
833     public abstract int compare(String   source, String   target);
834 
835     /**
836      * <p>
837      * Transforms the String into a CollationKey suitable for efficient
838      * repeated comparison.  The resulting key depends on the collator's
839      * rules, strength and decomposition mode.
840      * </p>
841      * <p>See the CollationKey class documentation for more information.</p>
842      * @param source the string to be transformed into a CollationKey.
843      * @return the CollationKey for the given String based on this Collator's
844      *         collation rules. If the source String is null, a null
845      *         CollationKey is returned.
846      * @see CollationKey
847      * @see #compare(String, String)
848      * @see #getRawCollationKey
849      * @stable ICU 2.8
850      */
851     public abstract CollationKey getCollationKey(String   source);
852     
853     /**
854      * Gets the simpler form of a CollationKey for the String source following
855      * the rules of this Collator and stores the result into the user provided 
856      * argument key. 
857      * If key has a internal byte array of length that's too small for the 
858      * result, the internal byte array will be grown to the exact required 
859      * size.
860      * @param source the text String to be transformed into a RawCollationKey  
861      * @return If key is null, a new instance of RawCollationKey will be 
862      *         created and returned, otherwise the user provided key will be 
863      *         returned.
864      * @see #compare(String, String)
865      * @see #getCollationKey 
866      * @see RawCollationKey
867      * @stable ICU 2.8
868      */
869     public abstract RawCollationKey getRawCollationKey(String   source, 
870                                                        RawCollationKey key);
871 
872     /** 
873      * <p>
874      * Variable top is a two byte primary value which causes all the codepoints 
875      * with primary values that are less or equal than the variable top to be 
876      * shifted when alternate handling is set to SHIFTED.
877      * </p>
878      * <p>
879      * Sets the variable top to a collation element value of a string supplied.
880      * </p> 
881      * @param varTop one or more (if contraction) characters to which the 
882      *               variable top should be set
883      * @return a int value containing the value of the variable top in upper 16
884      *         bits. Lower 16 bits are undefined.
885      * @exception IllegalArgumentException is thrown if varTop argument is not 
886      *            a valid variable top element. A variable top element is 
887      *            invalid when it is a contraction that does not exist in the
888      *            Collation order or when the PRIMARY strength collation 
889      *            element for the variable top has more than two bytes
890      * @see #getVariableTop
891      * @see RuleBasedCollator#setAlternateHandlingShifted
892      * @stable ICU 2.6
893      */
894     public abstract int setVariableTop(String   varTop);
895     
896     /** 
897      * Gets the variable top value of a Collator. 
898      * Lower 16 bits are undefined and should be ignored.
899      * @return the variable top value of a Collator.
900      * @see #setVariableTop
901      * @stable ICU 2.6
902      */
903     public abstract int getVariableTop();
904     
905     /** 
906      * Sets the variable top to a collation element value supplied.
907      * Variable top is set to the upper 16 bits. 
908      * Lower 16 bits are ignored.
909      * @param varTop Collation element value, as returned by setVariableTop or 
910      *               getVariableTop
911      * @see #getVariableTop
912      * @see #setVariableTop
913      * @stable ICU 2.6
914      */
915     public abstract void setVariableTop(int varTop);
916 
917     /** 
918      * Get the version of this collator object.
919      * @return the version object associated with this collator
920      * @stable ICU 2.8
921      */
922     public abstract VersionInfo getVersion();
923         
924     /** 
925      * Get the UCA version of this collator object.
926      * @return the version object associated with this collator
927      * @stable ICU 2.8
928      */
929     public abstract VersionInfo getUCAVersion();
930         
931     // protected constructor -------------------------------------------------
932 
933     /**
934      * Empty default constructor to make javadocs happy
935      * @stable ICU 2.4
936      */
937     protected Collator()
938     {
939     }
940     
941     // package private methods -----------------------------------------------
942 
943     // private data members --------------------------------------------------
944 
945     /**
946      * Collation strength
947      */
948     private int m_strength_ = TERTIARY;
949 
950     /**
951      * Decomposition mode
952      */
953     private int m_decomposition_ = CANONICAL_DECOMPOSITION;
954     
955     private static final boolean DEBUG = ICUDebug.enabled("collator");
956     
957     // private methods -------------------------------------------------------
958     
959     // end registry stuff
960 
961     // -------- BEGIN ULocale boilerplate --------
962 
963     /**
964      * Return the locale that was used to create this object, or null.
965      * This may may differ from the locale requested at the time of
966      * this object's creation.  For example, if an object is created
967      * for locale <tt>en_US_CALIFORNIA</tt>, the actual data may be
968      * drawn from <tt>en</tt> (the <i>actual</i> locale), and
969      * <tt>en_US</tt> may be the most specific locale that exists (the
970      * <i>valid</i> locale).
971      *
972      * <p>Note: This method will be implemented in ICU 3.0; ICU 2.8
973      * contains a partial preview implementation.  The * <i>actual</i>
974      * locale is returned correctly, but the <i>valid</i> locale is
975      * not, in most cases.
976      * @param type type of information requested, either {@link
977      * com.ibm.icu.util.ULocale#VALID_LOCALE} or {@link
978      * com.ibm.icu.util.ULocale#ACTUAL_LOCALE}.
979      * @return the information specified by <i>type</i>, or null if
980      * this object was not constructed from locale data.
981      * @see com.ibm.icu.util.ULocale
982      * @see com.ibm.icu.util.ULocale#VALID_LOCALE
983      * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE
984      * @draft ICU 2.8 (retain)
985      * @provisional This API might change or be removed in a future release.
986      */
987     public final ULocale getLocale(ULocale.Type type) {
988         return type == ULocale.ACTUAL_LOCALE ?
989             this.actualLocale : this.validLocale;
990     }
991 
992     /**
993      * Set information about the locales that were used to create this
994      * object.  If the object was not constructed from locale data,
995      * both arguments should be set to null.  Otherwise, neither
996      * should be null.  The actual locale must be at the same level or
997      * less specific than the valid locale.  This method is intended
998      * for use by factories or other entities that create objects of
999      * this class.
1000     * @param valid the most specific locale containing any resource
1001     * data, or null
1002     * @param actual the locale containing data used to construct this
1003     * object, or null
1004     * @see com.ibm.icu.util.ULocale
1005     * @see com.ibm.icu.util.ULocale#VALID_LOCALE
1006     * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE
1007     * @internal
1008     */
1009    final void setLocale(ULocale valid, ULocale actual) {
1010        // Change the following to an assertion later
1011        if ((valid == null) != (actual == null)) {
1012            ///CLOVER:OFF
1013            throw new IllegalArgumentException  ();
1014            ///CLOVER:ON
1015        }
1016        // Another check we could do is that the actual locale is at
1017        // the same level or less specific than the valid locale.
1018        this.validLocale = valid;
1019        this.actualLocale = actual;
1020    }
1021
1022    /**
1023     * The most specific locale containing any resource data, or null.
1024     * @see com.ibm.icu.util.ULocale
1025     * @internal
1026     */
1027    private ULocale validLocale;
1028
1029    /**
1030     * The locale containing data used to construct this object, or
1031     * null.
1032     * @see com.ibm.icu.util.ULocale
1033     * @internal
1034     */
1035    private ULocale actualLocale;
1036
1037    // -------- END ULocale boilerplate --------
1038}
1039
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags