OSDN Git Service

* java/text/SimpleDateFormat.java: Re-merged with Classpath.
[pf3gnuchains/gcc-fork.git] / libjava / java / text / Collator.java
1 /* Collator.java -- Perform locale dependent String comparisons.
2    Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
3
4 This file is part of GNU Classpath.
5
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10  
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING.  If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19 02111-1307 USA.
20
21 As a special exception, if you link this library with other files to
22 produce an executable, this library does not by itself cause the
23 resulting executable to be covered by the GNU General Public License.
24 This exception does not however invalidate any other reasons why the
25 executable file might be covered by the GNU General Public License. */
26
27
28 package java.text;
29
30 import java.util.Locale;
31 import java.util.MissingResourceException;
32 import java.util.ResourceBundle;
33 import java.util.Comparator;
34
35 /**
36  * This class is the abstract superclass of classes which perform 
37  * locale dependent <code>String</code> comparisons.  A caller requests
38  * an instance of <code>Collator</code> for a particular locale using
39  * the <code>getInstance()</code> static method in this class.  That method
40  * will return a locale specific subclass of <code>Collator</code> which
41  * can be used to perform <code>String</code> comparisons for that locale.
42  * If a subclass of <code>Collator</code> cannot be located for a particular
43  * locale, a default instance for the current locale will be returned.  
44  *
45  * In addition to setting the correct locale, there are two additional
46  * settings that can be adjusted to affect <code>String</code> comparisons:
47  * strength and decomposition.  The strength value determines the level
48  * of signficance of character differences required for them to sort
49  * differently.  (For example, whether or not capital letters are considered
50  * different from lower case letters).  The decomposition value affects how
51  * variants of the same character are treated for sorting purposes.  (For
52  * example, whether or not an accent is signficant or not).  These settings
53  * are described in detail in the documentation for the methods and values
54  * that are related to them.
55  *
56  * @author Tom Tromey <tromey@cygnus.com>
57  * @author Aaron M. Renn (arenn@urbanophile.com)
58  * @date March 18, 1999
59  */
60 /* Written using "Java Class Libraries", 2nd edition, plus online
61  * API docs for JDK 1.2 from http://www.javasoft.com.
62  * Status: Mostly complete, but parts stubbed out.  Look for FIXME.
63  */
64 public abstract class Collator implements Comparator, Cloneable
65 {
66   /**
67    * This constant is a strength value which indicates that only primary
68    * differences between characters will be considered signficant.  As an
69    * example, two completely different English letters such as 'a' and 'b'
70    * are considered to have a primary difference.
71    */
72   public static final int PRIMARY = 0;
73   
74   /**
75    * This constant is a strength value which indicates that only secondary
76    * or primary differences between characters will be considered
77    * significant.  An example of a secondary difference between characters
78    * are instances of the same letter with different accented forms.
79    */
80   public static final int SECONDARY = 1;
81   
82   /**
83    * This constant is a strength value which indicates that tertiary,
84    * secondary, and primary differences will be considered during sorting.
85    * An example of a tertiary difference is capitalization of a given letter.
86    * This is the default value for the strength setting.
87    */
88   public static final int TERTIARY = 2;
89   
90   /**
91    * This constant is a strength value which indicates that any difference
92    * at all between character values are considered significant.
93    */
94   public static final int IDENTICAL = 3;
95   
96   /**
97    * This constant indicates that accented characters won't be decomposed
98    * when performing comparisons.  This will yield the fastest results, but
99    * will only work correctly in call cases for languages which do not
100    * use accents such as English.
101    */
102   public static final int NO_DECOMPOSITION = 0;
103   
104   /**
105    * This constant indicates that only characters which are canonical variants
106    * in Unicode 2.0 will be decomposed prior to performing comparisons.  This
107    * will cause accented languages to be sorted correctly.  This is the
108    * default decomposition value.
109    */
110   public static final int CANONICAL_DECOMPOSITION = 1;
111   
112   /**
113    * This constant indicates that both canonical variants and compatibility
114    * variants in Unicode 2.0 will be decomposed prior to performing
115    * comparisons.  This is the slowest mode, but is required to get the
116    * correct sorting for certain languages with certain special formats.
117    */
118   public static final int FULL_DECOMPOSITION = 2;
119
120   /**
121    * This method initializes a new instance of <code>Collator</code> to have
122    * the default strength (TERTIARY) and decomposition 
123    * (CANONICAL_DECOMPOSITION) settings.  This constructor is protected and
124    * is for use by subclasses only.  Non-subclass callers should use the
125    * static <code>getInstance()</code> methods of this class to instantiate
126    * <code>Collation</code> objects for the desired locale.
127    */
128   protected Collator ()
129   {
130     strength = TERTIARY;
131     decmp = CANONICAL_DECOMPOSITION;
132   }
133
134   /**
135    * This method compares the two <code>String</code>'s and returns an
136    * integer indicating whether or not the first argument is less than,
137    * equal to, or greater than the second argument.  The comparison is
138    * performed according to the rules of the locale for this 
139    * <code>Collator</code> and the strength and decomposition rules in
140    * effect.
141    *
142    * @param str1 The first object to compare
143    * @param str2 The second object to compare
144    *
145    * @return A negative integer if str1 < str2, 0 if str1 == str2, or
146    * a positive integer if str1 > str2. 
147    */
148   public abstract int compare (String source, String target);
149
150   /**
151    * This method compares the two <code>Object</code>'s and returns an
152    * integer indicating whether or not the first argument is less than,
153    * equal to, or greater than the second argument.  These two objects
154    * must be <code>String</code>'s or an exception will be thrown.
155    *
156    * @param obj1 The first object to compare
157    * @param obj2 The second object to compare
158    *
159    * @return A negative integer if obj1 < obj2, 0 if obj1 == obj2, or
160    * a positive integer if obj1 > obj2. 
161    *
162    * @exception ClassCastException If the arguments are not instances
163    * of <code>String</code>. 
164    */
165   public int compare (Object o1, Object o2)
166   {
167     return compare ((String) o1, (String) o2);
168   }
169
170   /**
171    * This method tests the specified object for equality against this
172    * object.  This will be true if and only if the following conditions are
173    * met:
174    * <ul>
175    * <li>The specified object is not <code>null</code>.
176    * <li>The specified object is an instance of <code>Collator</code>.
177    * <li>The specified object has the same strength and decomposition
178    * settings as this object.
179    * </ul>
180    *
181    * @param obj The <code>Object</code> to test for equality against
182    *            this object. 
183    *
184    * @return <code>true</code> if the specified object is equal to
185    * this one, <code>false</code> otherwise.
186    */
187   public boolean equals (Object obj)
188   {
189     if (! (obj instanceof Collator))
190       return false;
191     Collator c = (Collator) obj;
192     return decmp == c.decmp && strength == c.strength;
193   }
194
195   /**
196    * This method tests whether the specified <code>String</code>'s are equal
197    * according to the collation rules for the locale of this object and
198    * the current strength and decomposition settings.
199    *
200    * @param str1 The first <code>String</code> to compare
201    * @param str2 The second <code>String</code> to compare
202    *
203    * @return <code>true</code> if the two strings are equal,
204    * <code>false</code> otherwise. 
205    */
206   public boolean equals (String source, String target)
207   {
208     return compare (source, target) == 0;
209   }
210
211   /**
212    * This method returns a copy of this <code>Collator</code> object.
213    *
214    * @return A duplicate of this object.
215    */
216   public Object clone ()
217   {
218     try
219       {
220         return super.clone ();
221       }
222     catch (CloneNotSupportedException _)
223       {
224         return null;
225       }
226   }
227
228   /**
229    * This method returns an array of <code>Locale</code> objects which is
230    * the list of locales for which <code>Collator</code> objects exist.
231    *
232    * @return The list of locales for which <code>Collator</code>'s exist.
233    */
234   public static synchronized Locale[] getAvailableLocales ()
235   {
236     // FIXME
237     Locale[] l = new Locale[1];
238     l[0] = Locale.US;
239     return l;
240   }
241
242   /**
243    * This method transforms the specified <code>String</code> into a
244    * <code>CollationKey</code> for faster comparisons.  This is useful when
245    * comparisons against a string might be performed multiple times, such
246    * as during a sort operation.
247    *
248    * @param str The <code>String</code> to convert.
249    *
250    * @return A <code>CollationKey</code> for the specified <code>String</code>.
251    */
252   public abstract CollationKey getCollationKey (String source);
253
254   /**
255    * This method returns the current decomposition setting for this
256    * object.  This * will be one of NO_DECOMPOSITION,
257    * CANONICAL_DECOMPOSITION, or * FULL_DECOMPOSITION.  See the
258    * documentation for those constants for an * explanation of this
259    * setting.
260    *
261    * @return The current decomposition setting.
262    */
263   public synchronized int getDecomposition ()
264   {
265     return decmp;
266   }
267
268   /**
269    * This method returns an instance of <code>Collator</code> for the
270    * default locale.
271    *
272    * @return A <code>Collator</code> for the default locale.
273    */
274   public static Collator getInstance ()
275   {
276     return getInstance (Locale.getDefault());
277   }
278
279   /**
280    * This method returns an instance of <code>Collator</code> for the
281    * specified locale.  If no <code>Collator</code> exists for the desired
282    * locale, a <code>Collator</code> for the default locale will be returned.
283    *
284    * @param locale The desired localed to load a <code>Collator</code> for.
285    *
286    * @return A <code>Collator</code> for the requested locale
287    */
288   public static Collator getInstance (Locale loc)
289   {
290     ResourceBundle res;
291     String pattern;
292     try
293       {
294         res = ResourceBundle.getBundle("gnu.java.locale.LocaleInformation",
295                                        loc);
296         pattern = res.getString("collation_rules");
297       }
298     catch (MissingResourceException x)
299       {
300         return null;
301       }
302     try
303       {
304         return new RuleBasedCollator (pattern);
305       }
306     catch (ParseException x)
307       {
308         return null;
309       }
310   }
311
312   /**
313    * This method returns the current strength setting for this object.  This
314    * will be one of PRIMARY, SECONDARY, TERTIARY, or IDENTICAL.  See the
315    * documentation for those constants for an explanation of this setting.
316    *
317    * @return The current strength setting.
318    */
319   public synchronized int getStrength ()
320   {
321     return strength;
322   }
323
324   /**
325    * This method returns a hash code value for this object.
326    *
327    * @return A hash value for this object.
328    */
329   public abstract int hashCode ();
330
331   /**
332    * This method sets the decomposition setting for this object to the
333    * specified value.  This must be one of NO_DECOMPOSITION,
334    * CANONICAL_DECOMPOSITION, or FULL_DECOMPOSITION.  Otherwise an
335    * exception will be thrown.  See the documentation for those
336    * contants for an explanation of this setting.
337    *
338    * @param decmp The new decomposition setting.
339    *
340    * @exception IllegalArgumentException If the requested
341    * decomposition setting is not valid.
342    */
343   public synchronized void setDecomposition (int mode)
344   {
345     if (mode != NO_DECOMPOSITION
346         && mode != CANONICAL_DECOMPOSITION
347         && mode != FULL_DECOMPOSITION)
348       throw new IllegalArgumentException ();
349     decmp = mode;
350   }
351
352   /**
353    * This method sets the strength setting for this object to the specified
354    * value.  This must be one of PRIMARY, SECONDARY, TERTIARY, or IDENTICAL.
355    * Otherwise an exception is thrown. See the documentation for these
356    * constants for an explanation of this setting.
357    * 
358    * @param strength The new strength setting.
359    *
360    * @exception IllegalArgumentException If the requested strength
361    * setting value is not valid.
362    */
363   public synchronized void setStrength (int strength)
364   {
365     if (strength != PRIMARY && strength != SECONDARY
366         && strength != TERTIARY && strength != IDENTICAL)
367       throw new IllegalArgumentException ();
368     this.strength = strength;
369   }
370
371   // Decompose a single character and append results to the buffer.
372   native final void decomposeCharacter (char c, StringBuffer buf);
373
374   /**
375    * This is the current collation decomposition setting.
376    */
377   int decmp;
378
379   /**
380    * This is the current collation strength setting.
381    */
382   int strength;
383 }