Java Doc for RuleBasedCollator.java in  » Internationalization-Localization » icu4j » com » ibm » icu » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

Users are strongly encouraged to read the users 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 ar attributes is required, use the RuleBasedCollator(String) constructor with the appropriate rules. The customized RuleBasedCollator will base its ordering on UCA, 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 UCA collation order .

For information about the collation rule syntax and details about customization, please refer to the Collation customization section of the user's 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);
 

 // 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
 

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

 // 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);
 

 // 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

Constructor that takes the argument rules for customization.

Private contructor for use by subclasses.

Get a Collation key for the argument String source from this RuleBasedCollator.

General recommendation:
If comparison are to be done to the same String multiple times, it would be more efficient to generate CollationKeys for the Strings and use CollationKey.compareTo(CollationKey) for the comparisons. If the each Strings are compared to only once, using the method RuleBasedCollator.compare(String, String) will have a better performance.

See the class documentation for an explanation about CollationKeys.

When case level is set to true, an additional weight is formed between the SECONDARY and TERTIARY weight, known as the case level. The case level is used to distinguish large and small Japanese Kana characters.

Sets this Collator's strength property.

Variable top is a two byte primary value which causes all the codepoints with primary values that are less or equal than the variable top to be shifted when alternate handling is set to SHIFTED.

Sets the variable top to a collation element value of a string supplied.

Constructor that takes the argument rules for customization. The collator will be based on UCA, with the attributes and re-ordering of the characters specified in the argument rules.

See the user guide's section on Collation Customization for details on the rule syntax.

Private contructor for use by subclasses. Public access to creating Collators is handled by the API Collator.getInstance() or RuleBasedCollator(String rules).

This constructor constructs the UCA collator internally

General recommendation:
If comparison are to be done to the same String multiple times, it would be more efficient to generate CollationKeys for the Strings and use CollationKey.compareTo(CollationKey) for the comparisons. If speed performance is critical and object instantiation is to be reduced, further optimization may be achieved by generating a simpler key of the form RawCollationKey and reusing this RawCollationKey object with the method RuleBasedCollator.getRawCollationKey. Internal byte representation can be directly accessed via RawCollationKey and stored for future use. Like CollationKey, RawCollationKey provides a method RawCollationKey.compareTo for key comparisons. If the each Strings are compared to only once, using the method RuleBasedCollator.compare(String, String) will have a better performance.

Get a Collation key for the argument String source from this RuleBasedCollator.

General recommendation:
If comparison are to be done to the same String multiple times, it would be more efficient to generate CollationKeys for the Strings and use CollationKey.compareTo(CollationKey) for the comparisons. If the each Strings are compared to only once, using the method RuleBasedCollator.compare(String, String) will have a better performance.

See the class documentation for an explanation about CollationKeys.

When case level is set to true, an additional weight is formed between the SECONDARY and TERTIARY weight, known as the case level. The case level is used to distinguish large and small Japanese Kana characters. Case level could also be used in other situations. For example to distinguish certain Pinyin characters. The default value is false, which means the case level is not generated. The contents of the case level are affected by the case first mode. A simple way to ignore accent differences in a string is to set the strength to PRIMARY and enable case level.

See the section on case level for more information.

Sets this Collator's strength property. The strength property determines the minimum level of difference considered significant during comparison.

See the Collator class description for an example of use.

Variable top is a two byte primary value which causes all the codepoints with primary values that are less or equal than the variable top to be shifted when alternate handling is set to SHIFTED.

Sets the variable top to a collation element value of a string supplied.

• it is a contraction that does not exist in theCollation order
• when the PRIMARY strength collation element for the variable top has more than two bytes
• when the varTop argument is null or zero in length.