Most visited

Recently visited

Results for

Added in API level 24

Summary: Inherited Constants | Ctors | Methods | Inherited Methods | [Expand All]

RuleBasedCollator

public final class RuleBasedCollator
extends Collator

java.lang.Object
↳	android.icu.text.Collator
	↳	android.icu.text.RuleBasedCollator

RuleBasedCollator is a concrete subclass of Collator. It allows customization of the Collator via user-specified rule sets. RuleBasedCollator is designed to be fully compliant to the Unicode Collation Algorithm (UCA) and conforms to ISO 14651.

A Collator is thread-safe only when frozen. See {isFrozen() and Freezable.

Users are strongly encouraged to read the User Guide for more information about the collation service before using this class.

Create a RuleBasedCollator from a locale by calling the getInstance(Locale) factory method in the base class Collator. Collator.getInstance(Locale) creates a RuleBasedCollator object based on the collation rules defined by the argument locale. If a customized collation ordering or attributes is required, use the RuleBasedCollator(String) constructor with the appropriate rules. The customized RuleBasedCollator will base its ordering on the CLDR root collation, while re-adjusting the attributes and orders of the characters in the specified rule accordingly.

RuleBasedCollator provides correct collation orders for most locales supported in ICU. If specific data for a locale is not available, the orders eventually falls back to the CLDR root sort order.

For information about the collation rule syntax and details about customization, please refer to the Collation customization section of the User Guide.

Note that there are some differences between the Collation rule syntax used in Java and ICU4J:

According to the JDK documentation:
Modifier '!' : Turns on Thai/Lao vowel-consonant swapping. If this rule is in force when a Thai vowel of the range \U0E40-\U0E44 precedes a Thai consonant of the range \U0E01-\U0E2E OR a Lao vowel of the range \U0EC0-\U0EC4 precedes a Lao consonant of the range \U0E81-\U0EAE then the vowel is placed after the consonant for collation purposes.
If a rule is without the modifier '!', the Thai/Lao vowel-consonant swapping is not turned on.
ICU4J's RuleBasedCollator does not support turning off the Thai/Lao vowel-consonant swapping, since the UCA clearly states that it has to be supported to ensure a correct sorting order. If a '!' is encountered, it is ignored.
As mentioned in the documentation of the base class Collator, compatibility decomposition mode is not supported.

Examples

Creating Customized RuleBasedCollators:

 String simple = "& a < b < c < d";
 RuleBasedCollator simpleCollator = new RuleBasedCollator(simple);

 String norwegian = "& a , A < b , B < c , C < d , D < e , E "
                    + "< f , F < g , G < h , H < i , I < j , "
                    + "J < k , K < l , L < m , M < n , N < "
                    + "o , O < p , P < q , Q <r , R <s , S < "
                    + "t , T < u , U < v , V < w , W < x , X "
                    + "< y , Y < z , Z < \u00E5 = a\u030A "
                    + ", \u00C5 = A\u030A ; aa , AA < \u00E6 "
                    + ", \u00C6 < \u00F8 , \u00D8";
 RuleBasedCollator norwegianCollator = new RuleBasedCollator(norwegian);

Concatenating rules to combine Collators:

 // Create an en_US Collator object
 RuleBasedCollator en_USCollator = (RuleBasedCollator)
     Collator.getInstance(new Locale("en", "US", ""));
 // Create a da_DK Collator object
 RuleBasedCollator da_DKCollator = (RuleBasedCollator)
     Collator.getInstance(new Locale("da", "DK", ""));
 // Combine the two
 // First, get the collation rules from en_USCollator
 String en_USRules = en_USCollator.getRules();
 // Second, get the collation rules from da_DKCollator
 String da_DKRules = da_DKCollator.getRules();
 RuleBasedCollator newCollator =
                             new RuleBasedCollator(en_USRules + da_DKRules);
 // newCollator has the combined rules

Making changes to an existing RuleBasedCollator to create a new Collator object, by appending changes to the existing rule:

 // Create a new Collator object with additional rules
 String addRules = "& C < ch, cH, Ch, CH";
 RuleBasedCollator myCollator =
     new RuleBasedCollator(en_USCollator.getRules() + addRules);
 // myCollator contains the new rules

How to change the order of non-spacing accents:

 // old rule with main accents
 String oldRules = "= \u0301 ; \u0300 ; \u0302 ; \u0308 "
                 + "; \u0327 ; \u0303 ; \u0304 ; \u0305 "
                 + "; \u0306 ; \u0307 ; \u0309 ; \u030A "
                 + "; \u030B ; \u030C ; \u030D ; \u030E "
                 + "; \u030F ; \u0310 ; \u0311 ; \u0312 "
                 + "< a , A ; ae, AE ; \u00e6 , \u00c6 "
                 + "< b , B < c, C < e, E & C < d , D";
 // change the order of accent characters
 String addOn = "& \u0300 ; \u0308 ; \u0302";
 RuleBasedCollator myCollator = new RuleBasedCollator(oldRules + addOn);

Putting in a new primary ordering before the default setting, e.g. sort English characters before or after Japanese characters in the Japanese Collator:

 // get en_US Collator rules
 RuleBasedCollator en_USCollator
                        = (RuleBasedCollator)Collator.getInstance(Locale.US);
 // add a few Japanese characters to sort before English characters
 // suppose the last character before the first base letter 'a' in
 // the English collation rule is \u2212
 String jaString = "& \u2212 <\u3041, \u3042 <\u3043, "
                   + "\u3044";
 RuleBasedCollator myJapaneseCollator
              = new RuleBasedCollator(en_USCollator.getRules() + jaString);

This class is not subclassable

Summary

Inherited constants

From class


    android.icu.text.Collator

Public constructors
`RuleBasedCollator(String rules)` Constructor that takes the argument rules for customization.

Public constructors


      RuleBasedCollator(String rules)

Constructor that takes the argument rules for customization.

Public methods
`Object`	`clone()` Clones the RuleBasedCollator
`RuleBasedCollator`	`cloneAsThawed()` Provides for the clone operation.
`int`	`compare(String source, String target)` Compares the source text String to the target text String according to the collation rules, strength and decomposition mode for this RuleBasedCollator.
`boolean`	`equals(Object obj)` Compares the equality of two Collator objects.
`Collator`	`freeze()` Freezes the collator.
`CollationElementIterator`	`getCollationElementIterator(UCharacterIterator source)` Return a CollationElementIterator for the given UCharacterIterator.
`CollationElementIterator`	`getCollationElementIterator(String source)` Return a CollationElementIterator for the given String.
`CollationElementIterator`	`getCollationElementIterator(CharacterIterator source)` Return a CollationElementIterator for the given CharacterIterator.
`CollationKey`	`getCollationKey(String source)` Get a Collation key for the argument String source from this RuleBasedCollator.
`void`	`getContractionsAndExpansions(UnicodeSet contractions, UnicodeSet expansions, boolean addPrefixes)` Gets unicode sets containing contractions and/or expansions of a collator
`int`	`getDecomposition()` Returns the decomposition mode of this Collator.
`int`	`getMaxVariable()` [icu] Returns the maximum reordering group whose characters are affected by the alternate handling behavior.
`boolean`	`getNumericCollation()` Method to retrieve the numeric collation value.
`int[]`	`getReorderCodes()` Retrieves the reordering codes for this collator.
`String`	`getRules()` Gets the collation tailoring rules for this RuleBasedCollator.
`String`	`getRules(boolean fullrules)` Returns current rules.
`int`	`getStrength()` Returns this Collator's strength attribute.
`UnicodeSet`	`getTailoredSet()` Get a UnicodeSet that contains all the characters and sequences tailored in this collator.
`VersionInfo`	`getUCAVersion()` Get the UCA version of this collator object.
`int`	`getVariableTop()` [icu] Gets the variable top value of a Collator.
`VersionInfo`	`getVersion()` Get the version of this collator object.
`int`	`hashCode()` Generates a unique hash code for this RuleBasedCollator.
`boolean`	`isAlternateHandlingShifted()` Checks if the alternate handling behavior is the UCA defined SHIFTED or NON_IGNORABLE.
`boolean`	`isCaseLevel()` Checks if case level is set to true.
`boolean`	`isFrenchCollation()` Checks if French Collation is set to true.
`boolean`	`isFrozen()` Determines whether the object has been frozen or not.
`boolean`	`isLowerCaseFirst()` Return true if a lowercase character is sorted before the corresponding uppercase character.
`boolean`	`isUpperCaseFirst()` Return true if an uppercase character is sorted before the corresponding lowercase character.
`void`	`setAlternateHandlingDefault()` Sets the alternate handling mode to the initial mode set during construction of the RuleBasedCollator.
`void`	`setAlternateHandlingShifted(boolean shifted)` Sets the alternate handling for QUATERNARY strength to be either shifted or non-ignorable.
`final void`	`setCaseFirstDefault()` Sets the case first mode to the initial mode set during construction of the RuleBasedCollator.
`void`	`setCaseLevel(boolean flag)` When case level is set to true, an additional weight is formed between the SECONDARY and TERTIARY weight, known as the case level.
`void`	`setCaseLevelDefault()` Sets the case level mode to the initial mode set during construction of the RuleBasedCollator.
`void`	`setDecomposition(int decomposition)` Sets the decomposition mode of this Collator.
`void`	`setDecompositionDefault()` Sets the decomposition mode to the initial mode set during construction of the RuleBasedCollator.
`void`	`setFrenchCollation(boolean flag)` Sets the mode for the direction of SECONDARY weights to be used in French collation.
`void`	`setFrenchCollationDefault()` Sets the French collation mode to the initial mode set during construction of the RuleBasedCollator.
`void`	`setLowerCaseFirst(boolean lowerfirst)` Sets the orders of lower cased characters to sort before upper cased characters, in strength TERTIARY.
`RuleBasedCollator`	`setMaxVariable(int group)` [icu] Sets the variable top to the top of the specified reordering group.
`void`	`setNumericCollation(boolean flag)` [icu] When numeric collation is turned on, this Collator makes substrings of digits sort according to their numeric values.
`void`	`setNumericCollationDefault()` Method to set numeric collation to its default value.
`void`	`setReorderCodes(int... order)` Sets the reordering codes for this collator.
`void`	`setStrength(int newStrength)` Sets this Collator's strength attribute.
`void`	`setStrengthDefault()` Sets the collation strength to the initial mode set during the construction of the RuleBasedCollator.
`void`	`setUpperCaseFirst(boolean upperfirst)` Sets whether uppercase characters sort before lowercase characters or vice versa, in strength TERTIARY.

Inherited methods

From class


  
    android.icu.text.Collator

`Object`	`clone()` Clones the collator.
`Collator`	`cloneAsThawed()` Provides for the clone operation.
`int`	`compare(Object source, Object target)` Compares the source Object to the target Object.
`abstract int`	`compare(String source, String target)` Compares the source text String to the target text String according to this Collator's rules, strength and decomposition mode.
`boolean`	`equals(String source, String target)` Compares the equality of two text Strings using this Collator's rules, strength and decomposition mode.
`boolean`	`equals(Object obj)` Compares the equality of two Collator objects.
`Collator`	`freeze()` Freezes the collator.
`static Locale[]`	`getAvailableLocales()` Returns the set of locales, as Locale objects, for which collators are installed.
`static final ULocale[]`	`getAvailableULocales()` [icu] Returns the set of locales, as ULocale objects, for which collators are installed.
`abstract CollationKey`	`getCollationKey(String source)` Transforms the String into a CollationKey suitable for efficient repeated comparison.
`int`	`getDecomposition()` Returns the decomposition mode of this Collator.
`static String`	`getDisplayName(Locale objectLocale, Locale displayLocale)` [icu] Returns the name of the collator for the objectLocale, localized for the displayLocale.
`static String`	`getDisplayName(ULocale objectLocale)` [icu] Returns the name of the collator for the objectLocale, localized for the default `DISPLAY` locale.
`static String`	`getDisplayName(ULocale objectLocale, ULocale displayLocale)` [icu] Returns the name of the collator for the objectLocale, localized for the displayLocale.
`static String`	`getDisplayName(Locale objectLocale)` [icu] Returns the name of the collator for the objectLocale, localized for the default `DISPLAY` locale.
`static int[]`	`getEquivalentReorderCodes(int reorderCode)` Retrieves all the reorder codes that are grouped with the given reorder code.
`static final ULocale`	`getFunctionalEquivalent(String keyword, ULocale locID)` [icu] Returns the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service.
`static final ULocale`	`getFunctionalEquivalent(String keyword, ULocale locID, boolean[] isAvailable)` [icu] Returns the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service.
`static final Collator`	`getInstance()` Returns the Collator for the current default locale.
`static final Collator`	`getInstance(Locale locale)` Returns the Collator for the desired locale.
`static final Collator`	`getInstance(ULocale locale)` [icu] Returns the Collator for the desired locale.
`static final String[]`	`getKeywordValues(String keyword)` [icu] Given a keyword, returns an array of all values for that keyword that are currently in use.
`static final String[]`	`getKeywordValuesForLocale(String key, ULocale locale, boolean commonlyUsed)` [icu] Given a key and a locale, returns an array of string values in a preferred order that would make a difference.
`static final String[]`	`getKeywords()` [icu] Returns an array of all possible keywords that are relevant to collation.
`int`	`getMaxVariable()` [icu] Returns the maximum reordering group whose characters are affected by the alternate handling behavior.
`int[]`	`getReorderCodes()` Retrieves the reordering codes for this collator.
`int`	`getStrength()` Returns this Collator's strength attribute.
`UnicodeSet`	`getTailoredSet()` [icu] Returns a UnicodeSet that contains all the characters and sequences tailored in this collator.
`abstract VersionInfo`	`getUCAVersion()` [icu] Returns the UCA version of this collator object.
`abstract int`	`getVariableTop()` [icu] Gets the variable top value of a Collator.
`abstract VersionInfo`	`getVersion()` [icu] Returns the version of this collator object.
`boolean`	`isFrozen()` Determines whether the object has been frozen or not.
`void`	`setDecomposition(int decomposition)` Sets the decomposition mode of this Collator.
`Collator`	`setMaxVariable(int group)` [icu] Sets the variable top to the top of the specified reordering group.
`void`	`setReorderCodes(int... order)` Sets the reordering codes for this collator.
`void`	`setStrength(int newStrength)` Sets this Collator's strength attribute.

From class


  
    java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long millis, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void`	`wait(long millis)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void`	`wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

From interface


  
    java.util.Comparator

`abstract int`	`compare(Object o1, Object o2)` Compares its two arguments for order.
`static <T, U> Comparator<Object>`	`comparing(Function<? super T, ? extends U> keyExtractor, Comparator<? super U> keyComparator)` Accepts a function that extracts a sort key from a type `T`, and returns a `Comparator<T>` that compares by that sort key using the specified `Comparator`.
`static <T, U extends Comparable<? super U>> Comparator<Object>`	`comparing(Function<? super T, ? extends U> keyExtractor)` Accepts a function that extracts a `Comparable` sort key from a type `T`, and returns a `Comparator<T>` that compares by that sort key.
`static <T> Comparator<Object>`	`comparingDouble(ToDoubleFunction<? super T> keyExtractor)` Accepts a function that extracts a `double` sort key from a type `T`, and returns a `Comparator<T>` that compares by that sort key.
`static <T> Comparator<Object>`	`comparingInt(ToIntFunction<? super T> keyExtractor)` Accepts a function that extracts an `int` sort key from a type `T`, and returns a `Comparator<T>` that compares by that sort key.
`static <T> Comparator<Object>`	`comparingLong(ToLongFunction<? super T> keyExtractor)` Accepts a function that extracts a `long` sort key from a type `T`, and returns a `Comparator<T>` that compares by that sort key.
`abstract boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this comparator.
`static <T extends Comparable<? super T>> Comparator<T>`	`naturalOrder()` Returns a comparator that compares `Comparable` objects in natural order.
`static <T> Comparator<Object>`	`nullsFirst(Comparator<? super T> comparator)` Returns a null-friendly comparator that considers `null` to be less than non-null.
`static <T> Comparator<Object>`	`nullsLast(Comparator<? super T> comparator)` Returns a null-friendly comparator that considers `null` to be greater than non-null.
`static <T extends Comparable<? super T>> Comparator<T>`	`reverseOrder()` Returns a comparator that imposes the reverse of the natural ordering.
`default Comparator<Object>`	`reversed()` Returns a comparator that imposes the reverse ordering of this comparator.
`default <U extends Comparable<? super U>> Comparator<Object>`	`thenComparing(Function<? super T, ? extends U> keyExtractor)` Returns a lexicographic-order comparator with a function that extracts a `Comparable` sort key.
`default <U> Comparator<Object>`	`thenComparing(Function<? super T, ? extends U> keyExtractor, Comparator<? super U> keyComparator)` Returns a lexicographic-order comparator with a function that extracts a key to be compared with the given `Comparator`.
`default Comparator<Object>`	`thenComparing(Comparator<? super T> other)` Returns a lexicographic-order comparator with another comparator.
`default Comparator<Object>`	`thenComparingDouble(ToDoubleFunction<? super T> keyExtractor)` Returns a lexicographic-order comparator with a function that extracts a `double` sort key.
`default Comparator<Object>`	`thenComparingInt(ToIntFunction<? super T> keyExtractor)` Returns a lexicographic-order comparator with a function that extracts a `int` sort key.
`default Comparator<Object>`	`thenComparingLong(ToLongFunction<? super T> keyExtractor)` Returns a lexicographic-order comparator with a function that extracts a `long` sort key.

From interface


  
    android.icu.util.Freezable

Throws
`ParseException`	and IOException thrown. ParseException thrown when argument rules have an invalid syntax. IOException thrown when an error occurred while reading internal data.
`Exception`

Parameters
`source`	`String`: the source text String.
`target`	`String`: the target text String.

Parameters
`contractions`	`UnicodeSet`: if not null, set to contain contractions
`expansions`	`UnicodeSet`: if not null, set to contain expansions
`addPrefixes`	`boolean`: add the prefix contextual elements to contractions

Most visited

Recently visited

Results for

RuleBasedCollator

Summary

Inherited constants

Public constructors

Public methods

Inherited methods

Public constructors

RuleBasedCollator

Public methods

clone

cloneAsThawed

compare

equals

freeze

getCollationElementIterator

getCollationElementIterator

getCollationElementIterator

getCollationKey

getContractionsAndExpansions

getDecomposition

getMaxVariable

getNumericCollation

getReorderCodes

getRules

getRules

getStrength

getTailoredSet

getUCAVersion

getVariableTop

getVersion

hashCode

isAlternateHandlingShifted

isCaseLevel

isFrenchCollation

isFrozen

isLowerCaseFirst

isUpperCaseFirst

setAlternateHandlingDefault

setAlternateHandlingShifted

setCaseFirstDefault

setCaseLevel

setCaseLevelDefault

setDecomposition

setDecompositionDefault

setFrenchCollation

setFrenchCollationDefault

setLowerCaseFirst

setMaxVariable

setNumericCollation

setNumericCollationDefault

setReorderCodes

setStrength

setStrengthDefault

setUpperCaseFirst