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