47 import sun.util.locale.provider.LocaleProviderAdapter; |
47 import sun.util.locale.provider.LocaleProviderAdapter; |
48 import sun.util.locale.provider.LocaleServiceProviderPool; |
48 import sun.util.locale.provider.LocaleServiceProviderPool; |
49 |
49 |
50 |
50 |
51 /** |
51 /** |
52 * The <code>Collator</code> class performs locale-sensitive |
52 * The {@code Collator} class performs locale-sensitive |
53 * <code>String</code> comparison. You use this class to build |
53 * {@code String} comparison. You use this class to build |
54 * searching and sorting routines for natural language text. |
54 * searching and sorting routines for natural language text. |
55 * |
55 * |
56 * <p> |
56 * <p> |
57 * <code>Collator</code> is an abstract base class. Subclasses |
57 * {@code Collator} is an abstract base class. Subclasses |
58 * implement specific collation strategies. One subclass, |
58 * implement specific collation strategies. One subclass, |
59 * <code>RuleBasedCollator</code>, is currently provided with |
59 * {@code RuleBasedCollator}, is currently provided with |
60 * the Java Platform and is applicable to a wide set of languages. Other |
60 * the Java Platform and is applicable to a wide set of languages. Other |
61 * subclasses may be created to handle more specialized needs. |
61 * subclasses may be created to handle more specialized needs. |
62 * |
62 * |
63 * <p> |
63 * <p> |
64 * Like other locale-sensitive classes, you can use the static |
64 * Like other locale-sensitive classes, you can use the static |
65 * factory method, <code>getInstance</code>, to obtain the appropriate |
65 * factory method, {@code getInstance}, to obtain the appropriate |
66 * <code>Collator</code> object for a given locale. You will only need |
66 * {@code Collator} object for a given locale. You will only need |
67 * to look at the subclasses of <code>Collator</code> if you need |
67 * to look at the subclasses of {@code Collator} if you need |
68 * to understand the details of a particular collation strategy or |
68 * to understand the details of a particular collation strategy or |
69 * if you need to modify that strategy. |
69 * if you need to modify that strategy. |
70 * |
70 * |
71 * <p> |
71 * <p> |
72 * The following example shows how to compare two strings using |
72 * The following example shows how to compare two strings using |
73 * the <code>Collator</code> for the default locale. |
73 * the {@code Collator} for the default locale. |
74 * <blockquote> |
74 * <blockquote> |
75 * <pre>{@code |
75 * <pre>{@code |
76 * // Compare two strings in the default locale |
76 * // Compare two strings in the default locale |
77 * Collator myCollator = Collator.getInstance(); |
77 * Collator myCollator = Collator.getInstance(); |
78 * if( myCollator.compare("abc", "ABC") < 0 ) |
78 * if( myCollator.compare("abc", "ABC") < 0 ) |
81 * System.out.println("abc is greater than or equal to ABC"); |
81 * System.out.println("abc is greater than or equal to ABC"); |
82 * }</pre> |
82 * }</pre> |
83 * </blockquote> |
83 * </blockquote> |
84 * |
84 * |
85 * <p> |
85 * <p> |
86 * You can set a <code>Collator</code>'s <em>strength</em> property |
86 * You can set a {@code Collator}'s <em>strength</em> property |
87 * to determine the level of difference considered significant in |
87 * to determine the level of difference considered significant in |
88 * comparisons. Four strengths are provided: <code>PRIMARY</code>, |
88 * comparisons. Four strengths are provided: {@code PRIMARY}, |
89 * <code>SECONDARY</code>, <code>TERTIARY</code>, and <code>IDENTICAL</code>. |
89 * {@code SECONDARY}, {@code TERTIARY}, and {@code IDENTICAL}. |
90 * The exact assignment of strengths to language features is |
90 * The exact assignment of strengths to language features is |
91 * locale dependent. For example, in Czech, "e" and "f" are considered |
91 * locale dependent. For example, in Czech, "e" and "f" are considered |
92 * primary differences, while "e" and "ě" are secondary differences, |
92 * primary differences, while "e" and "ě" are secondary differences, |
93 * "e" and "E" are tertiary differences and "e" and "e" are identical. |
93 * "e" and "E" are tertiary differences and "e" and "e" are identical. |
94 * The following shows how both case and accents could be ignored for |
94 * The following shows how both case and accents could be ignored for |
102 * System.out.println("Strings are equivalent"); |
102 * System.out.println("Strings are equivalent"); |
103 * } |
103 * } |
104 * </pre> |
104 * </pre> |
105 * </blockquote> |
105 * </blockquote> |
106 * <p> |
106 * <p> |
107 * For comparing <code>String</code>s exactly once, the <code>compare</code> |
107 * For comparing {@code String}s exactly once, the {@code compare} |
108 * method provides the best performance. When sorting a list of |
108 * method provides the best performance. When sorting a list of |
109 * <code>String</code>s however, it is generally necessary to compare each |
109 * {@code String}s however, it is generally necessary to compare each |
110 * <code>String</code> multiple times. In this case, <code>CollationKey</code>s |
110 * {@code String} multiple times. In this case, {@code CollationKey}s |
111 * provide better performance. The <code>CollationKey</code> class converts |
111 * provide better performance. The {@code CollationKey} class converts |
112 * a <code>String</code> to a series of bits that can be compared bitwise |
112 * a {@code String} to a series of bits that can be compared bitwise |
113 * against other <code>CollationKey</code>s. A <code>CollationKey</code> is |
113 * against other {@code CollationKey}s. A {@code CollationKey} is |
114 * created by a <code>Collator</code> object for a given <code>String</code>. |
114 * created by a {@code Collator} object for a given {@code String}. |
115 * <br> |
115 * <br> |
116 * <strong>Note:</strong> <code>CollationKey</code>s from different |
116 * <strong>Note:</strong> {@code CollationKey}s from different |
117 * <code>Collator</code>s can not be compared. See the class description |
117 * {@code Collator}s can not be compared. See the class description |
118 * for {@link CollationKey} |
118 * for {@link CollationKey} |
119 * for an example using <code>CollationKey</code>s. |
119 * for an example using {@code CollationKey}s. |
120 * |
120 * |
121 * @see RuleBasedCollator |
121 * @see RuleBasedCollator |
122 * @see CollationKey |
122 * @see CollationKey |
123 * @see CollationElementIterator |
123 * @see CollationElementIterator |
124 * @see Locale |
124 * @see Locale |
289 * Compares its two arguments for order. Returns a negative integer, |
289 * Compares its two arguments for order. Returns a negative integer, |
290 * zero, or a positive integer as the first argument is less than, equal |
290 * zero, or a positive integer as the first argument is less than, equal |
291 * to, or greater than the second. |
291 * to, or greater than the second. |
292 * <p> |
292 * <p> |
293 * This implementation merely returns |
293 * This implementation merely returns |
294 * <code> compare((String)o1, (String)o2) </code>. |
294 * {@code compare((String)o1, (String)o2) }. |
295 * |
295 * |
296 * @return a negative integer, zero, or a positive integer as the |
296 * @return a negative integer, zero, or a positive integer as the |
297 * first argument is less than, equal to, or greater than the |
297 * first argument is less than, equal to, or greater than the |
298 * second. |
298 * second. |
299 * @throws ClassCastException the arguments cannot be cast to Strings. |
299 * @throws ClassCastException the arguments cannot be cast to Strings. |
414 decmp = decompositionMode; |
414 decmp = decompositionMode; |
415 } |
415 } |
416 |
416 |
417 /** |
417 /** |
418 * Returns an array of all locales for which the |
418 * Returns an array of all locales for which the |
419 * <code>getInstance</code> methods of this class can return |
419 * {@code getInstance} methods of this class can return |
420 * localized instances. |
420 * localized instances. |
421 * The returned array represents the union of locales supported |
421 * The returned array represents the union of locales supported |
422 * by the Java runtime and by installed |
422 * by the Java runtime and by installed |
423 * {@link java.text.spi.CollatorProvider CollatorProvider} implementations. |
423 * {@link java.text.spi.CollatorProvider CollatorProvider} implementations. |
424 * It must contain at least a Locale instance equal to |
424 * It must contain at least a Locale instance equal to |
425 * {@link java.util.Locale#US Locale.US}. |
425 * {@link java.util.Locale#US Locale.US}. |
426 * |
426 * |
427 * @return An array of locales for which localized |
427 * @return An array of locales for which localized |
428 * <code>Collator</code> instances are available. |
428 * {@code Collator} instances are available. |
429 */ |
429 */ |
430 public static synchronized Locale[] getAvailableLocales() { |
430 public static synchronized Locale[] getAvailableLocales() { |
431 LocaleServiceProviderPool pool = |
431 LocaleServiceProviderPool pool = |
432 LocaleServiceProviderPool.getPool(CollatorProvider.class); |
432 LocaleServiceProviderPool.getPool(CollatorProvider.class); |
433 return pool.getAvailableLocales(); |
433 return pool.getAvailableLocales(); |