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