Chapter 16
The java.text Package

RuleBasedCollator

Name

RuleBasedCollator

Synopsis

Class Name:

java.text.RuleBasedCollator

Superclass:

java.text.Collator

Immediate Subclasses:

None

Interfaces Implemented:

None

Availability:

New as of JDK 1.1

The RuleBasedCollator class is a concrete subclass of Collator that can compare strings using a table of rules. The rules for many locales already exist. To get a useful Collator for a given locale, use the getInstance(Locale) factory method of Collator.

If you need a special-purpose Collator or a Collator for a new locale, you can create your own RuleBasedCollator from a string that represents the rules. The rules are expressed in three primary forms:

[relation] [text]
[reset] [text]
[modifier]

The rules can be chained together. The only modifier is the @ character, which specifies that all diacriticals are sorted backwards, as in French.

The valid relations are:

>

Greater than as a primary difference

;

Greater than as a secondary difference or difference in accent

,

Greater than as a tertiary difference or difference in case

=

Equal

For example "<a<b" is two chained rules that state that 'a' is greater than all ignorable characters, and 'b' is greater than 'a'. To expand this rule to include capitals, use "<a,A<b,B".

A reset, specified by the & character, is used to insert rules in an existing list of chained rules. For example, we can add a rule to sort 'e' with an umlaut (Unicode 0308) after plain 'e'. The existing rules might look like "<a<b<c<d<e<f". We can add the following reset, "&e;e\u0308", so that the complete rule table looks like "<a<b<c<d<e<f&e;e\u0308".

Class Summary

public class java.text.RuleBasedCollator extends java.text.Collator {
  // Constructors
  public RuleBasedCollator(String rules);
  // Instance Methods
  public Object clone();
  public int compare(String source, String target); 
  public boolean equals(Object obj); 
  public CollationElementIterator 
         getCollationElementIterator( String source);
  public CollationKey getCollationKey(String source); 
  public String getRules();
  public int hashCode();
}

Constructors

RuleBasedCollator

public RuleBasedCollator(String rules) throws ParseException

Parameters

rules: A string that contains the rules.

Throws

ParseException: If the given rules are incorrectly formed.

Description

This constructor creates a RuleBasedCollator with the given rules.

Instance Methods

clone

public Object clone()

Returns

A copy of this RuledBasedCollator.

Overrides

Collator.clone()

Description

This method creates a copy of this RuledBasedCollator and returns it.

compare

public int compare(String source, String target)

Parameters

source

The source string.

target

The target string.

Returns

-1 if source is less than target, 0 if the strings are equal, or 1 if source is greater than target.

Overrides

Collator.compare()

Description

This method compares the given strings according to the rules for this RuleBasedCollator and returns a value that indicates their relationship. If either of the strings are compared more than once, a CollationKey should be used instead.

equals

public boolean equals(Object obj)

Parameters

obj: The object to be compared with this object.

Returns

true if the objects are equal; false if they are not.

Overrides

Collator.equals()

Description

This method returns true if obj is an instance of RuleBasedCollator and is equivalent to this RuleBasedCollator.

getCollationElementIterator

 public CollationElementIterator getCollationElementIterator( String source)

Parameters

source: The source string.

Returns

A CollationElementIterator for the given string.

Description

This method generates a CollationElementIterator for the given string.

getCollationKey

public CollationKey getCollationKey(String source)

Parameters

source: The source string.

Returns

A CollationKey for the given string.

Overrides

Collator.getCollationKey()

Description

This method generates a CollationKey for the given string. The returned object can be compared with other CollationKey objects using CollationKey.compareTo(). This comparison is faster than using RuleBasedCollator.compare(), so if the same string is used for many comparisons, you should use CollationKey objects.

getRules

public String getRules()

Returns

The rules string for this RuleBasedCollator.

Description

This method returns a string that contains the rules that this RuleBasedCollator is using.

hashCode

public int hashCode()

Returns

A hashcode for this object.

Overrides

Collator.hashCode()

Description

This method returns a hashcode for this RuleBasedCollator.

Inherited Methods

Method	Inherited From	Method	Inherited From
`equals(String, String)`	`Collator`	`finalize()`	`Object`
`getClass()`	`Object`	`getDecomposition()`	`Collator`
`getStrength()`	`Collator`	`notify()`	`Object`
`notifyAll()`	`Object`	`setDecomposition(int)`	`Collator`
`setStrength(int)`	`Collator`	`toString()`	`Object`
`wait()`	`Object`	`wait(long)`	`Object`
`wait(long, int)`	`Object`