com.ibm.icu.text.Collator Maven / Gradle / Ivy

/**
*******************************************************************************
* Copyright (C) 1996-2012, International Business Machines Corporation and    *
* others. All Rights Reserved.                                                *
*******************************************************************************
*/
package com.ibm.icu.text;

import java.text.RuleBasedCollator;
import java.util.Comparator;
import java.util.Locale;

import com.ibm.icu.util.ULocale;

/**
* {@icuenhanced java.text.Collator}.{@icu _usage_}
*
* Collator performs locale-sensitive string comparison. A concrete
* subclass, RuleBasedCollator, allows customization of the collation
* ordering by the use of rule sets.
*
* Following the Unicode
* Consortium's specifications for the
* Unicode Collation
* Algorithm (UCA), there are 5 different levels of strength used
* in comparisons:
*
* 

* PRIMARY strength: Typically, this is used to denote differences between
*     base characters (for example, "a" < "b").
*     It is the strongest difference. For example, dictionaries are divided
*     into different sections by base character.
* 
SECONDARY strength: Accents in the characters are considered secondary
*     differences (for example, "as" < "às" < "at"). Other
*     differences
*     between letters can also be considered secondary differences, depending
*     on the language. A secondary difference is ignored when there is a
*     primary difference anywhere in the strings.
* 
TERTIARY strength: Upper and lower case differences in characters are
*     distinguished at tertiary strength (for example, "ao" < "Ao" <
*     "aò"). In addition, a variant of a letter differs from the base
*     form on the tertiary strength (such as "A" and "Ⓐ"). Another
*     example is the
*     difference between large and small Kana. A tertiary difference is ignored
*     when there is a primary or secondary difference anywhere in the strings.
* 
QUATERNARY strength: When punctuation is ignored
*     
*     (see Ignoring Punctuations in the user guide) at PRIMARY to TERTIARY
*     strength, an additional strength level can
*     be used to distinguish words with and without punctuation (for example,
*     "ab" < "a-b" < "aB").
*     This difference is ignored when there is a PRIMARY, SECONDARY or TERTIARY
*     difference. The QUATERNARY strength should only be used if ignoring
*     punctuation is required.
* 
IDENTICAL strength:
*     When all other strengths are equal, the IDENTICAL strength is used as a
*     tiebreaker. The Unicode code point values of the NFD form of each string
*     are compared, just in case there is no difference.
*     For example, Hebrew cantellation marks are only distinguished at this
*     strength. This strength should be used sparingly, as only code point
*     value differences between two strings is an extremely rare occurrence.
*     Using this strength substantially decreases the performance for both
*     comparison and collation key generation APIs. This strength also
*     increases the size of the collation key.
* 
*
* Unlike the JDK, ICU4J's Collator deals only with 2 decomposition modes,
* the canonical decomposition mode and one that does not use any decomposition.
* The compatibility decomposition mode, java.text.Collator.FULL_DECOMPOSITION
* is not supported here. If the canonical
* decomposition mode is set, the Collator handles un-normalized text properly,
* producing the same results as if the text were normalized in NFD. If
* canonical decomposition is turned off, it is the user's responsibility to
* ensure that all text is already in the appropriate form before performing
* a comparison or before getting a CollationKey.
*
* For more information about the collation service see the
* users
* guide.
*
* Examples of use
* 
* // Get the Collator for US English and set its strength to PRIMARY
* Collator usCollator = Collator.getInstance(Locale.US);
* usCollator.setStrength(Collator.PRIMARY);
* if (usCollator.compare("abc", "ABC") == 0) {
*     System.out.println("Strings are equivalent");
* }
*
* The following example shows how to compare two strings using the
* Collator for the default locale.
*
* // Compare two strings in the default locale
* Collator myCollator = Collator.getInstance();
* myCollator.setDecomposition(NO_DECOMPOSITION);
* if (myCollator.compare("à\u0325", "a\u0325̀") != 0) {
*     System.out.println("à\u0325 is not equals to a\u0325̀ without decomposition");
*     myCollator.setDecomposition(CANONICAL_DECOMPOSITION);
*     if (myCollator.compare("à\u0325", "a\u0325̀") != 0) {
*         System.out.println("Error: à\u0325 should be equals to a\u0325̀ with decomposition");
*     }
*     else {
*         System.out.println("à\u0325 is equals to a\u0325̀ with decomposition");
*     }
* }
* else {
*     System.out.println("Error: à\u0325 should be not equals to a\u0325̀ without decomposition");
* }
* 
* 
* @see RuleBasedCollator
* @see CollationKey
* @author Syn Wee Quek
* @stable ICU 2.8
*/
public class Collator implements Comparator