Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.text

Class RuleBasedCollator

java.lang.Object
|
+--java.text.Collator
   |
   +--java.text.RuleBasedCollator


public class RuleBasedCollator

extends Collator

This class is a concrete subclass of Collator suitable for string collation in a wide variety of languages. An instance of this class is normally returned by the getInstance method of Collator with rules predefined for the requested locale. However, an instance of this class can be created manually with any desired rules.

Rules take the form of a String with the following syntax

The modifier character indicates that accents sort backward as is the case with French. The relational operators specify how the text argument relates to the previous term. The relation characters have the following meanings:

As for the text argument itself, this is any sequence of Unicode characters not in the following ranges: 0x0009-0x000D, 0x0020-0x002F, 0x003A-0x0040, 0x005B-0x0060, and 0x007B-0x007E. If these characters are desired, they must be enclosed in single quotes. If any whitespace is encountered, it is ignored. (For example, "a b" is equal to "ab").

The reset operation inserts the following rule at the point where the text argument to it exists in the previously declared rule string. This makes it easy to add new rules to an existing string by simply including them in a reset sequence at the end. Note that the text argument, or at least the first character of it, must be present somewhere in the previously declared rules in order to be inserted properly. If this is not satisfied, a ParseException will be thrown.

This system of configuring RuleBasedCollator is needlessly complex and the people at Taligent who developed it (along with the folks at Sun who accepted it into the Java standard library) deserve a slow and agonizing death.

Here are a couple of example of rule strings:

"< a < b < c" - This string says that a is greater than b which is greater than c, with all differences being primary differences.

"< a,A < b,B < c,C" - This string says that 'A' is greater than 'a' with a tertiary strength comparison. Both 'b' and 'B' are greater than 'a' and 'A' during a primary strength comparison. But 'B' is greater than 'b' under a tertiary strength comparison.

"< a < c & a < b " - This sequence is identical in function to the "< a < b < c" rule string above. The '&' reset symbol indicates that the rule "< b" is to be inserted after the text argument "a" in the previous rule string segment.

"< a < b & y < z" - This is an error. The character 'y' does not appear anywhere in the previous rule string segment so the rule following the reset rule cannot be inserted.

For a description of the various comparison strength types, see the documentation for the Collator class.

As an additional complication to this already overly complex rule scheme, if any characters precede the first rule, these characters are considered ignorable. They will be treated as if they did not exist during comparisons. For example, "- < a < b ..." would make '-' an ignorable character such that the strings "high-tech" and "hightech" would be considered identical.

A ParseException will be thrown for any of the following conditions:

Author:

Constructor Summary

RuleBasedCollator(java.lang.String rules)

This method initializes a new instance of RuleBasedCollator with the specified collation rules.

Method Summary

java.lang.Objectclone()

This method creates a copy of this object.
intcompare(java.lang.String s1, java.lang.String s2)

This method returns an integer which indicates whether the first specified String is less than, greater than, or equal to the second.
booleanequals(java.lang.Object obj)

This method tests this object for equality against the specified object.
java.text.CollationElementIteratorgetCollationElementIterator(java.lang.String str)

This method returns an instance for CollationElementIterator for the specified String under the collation rules for this object.
java.text.CollationElementIteratorgetCollationElementIterator(java.text.CharacterIterator ci)

This method returns an instance of CollationElementIterator for the String represented by the specified CharacterIterator.
java.text.CollationKeygetCollationKey(java.lang.String str)

This method returns an instance of CollationKey for the specified String.
java.lang.StringgetRules()

This method returns a String containing the collation rules for this object.
inthashCode()

This method returns a hash value for this object.

Constructor Details

RuleBasedCollator

public RuleBasedCollator(java.lang.String rules)

This method initializes a new instance of RuleBasedCollator with the specified collation rules. Note that an application normally obtains an instance of RuleBasedCollator by calling the getInstance method of Collator. That method automatically loads the proper set of rules for the desired locale.

Parameters:

Throws:


Method Details

clone

public Object clone()

This method creates a copy of this object.

Returns:


compare

public int compare(java.lang.String s1, java.lang.String s2)

This method returns an integer which indicates whether the first specified String is less than, greater than, or equal to the second. The value depends not only on the collation rules in effect, but also the strength and decomposition settings of this object.

Parameters:

Returns:


equals

public boolean equals(java.lang.Object obj)

This method tests this object for equality against the specified object. This will be true if and only if the specified object is another reference to this object.

Parameters:

Returns:


getCollationElementIterator

public CollationElementIterator getCollationElementIterator(java.lang.String str)

This method returns an instance for CollationElementIterator for the specified String under the collation rules for this object.

Parameters:

Returns:


getCollationElementIterator

public CollationElementIterator getCollationElementIterator(java.text.CharacterIterator ci)

This method returns an instance of CollationElementIterator for the String represented by the specified CharacterIterator.

Parameters:

Returns:


getCollationKey

public CollationKey getCollationKey(java.lang.String str)

This method returns an instance of CollationKey for the specified String. The object returned will have a more efficient mechanism for its comparison function that could provide speed benefits if multiple comparisons are performed, such as during a sort.

Parameters:

Returns:


getRules

public String getRules()

This method returns a String containing the collation rules for this object.

Returns:


hashCode

public int hashCode()

This method returns a hash value for this object.

Returns: