javax.microedition.global
Class StringComparator

java.lang.Object
  javax.microedition.global.StringComparator

public final class StringComparator

extends java.lang.Object

Compares two strings using locale-specific rules. The comparison is performed by the compare method according to the Unicode Collation Algorithm (Unicode Technical Standard #10). Canonical character decomposition is always used.

Selected locale

The locale used by the StringComparator determines the rules used for string comparisons. The selected locale is either the value of the microedition.locale system property or the locale passed as a string parameter to the constructor.

If the selected locale is null or the empty string, the StringComparator uses the generic collation algorithm, which is not appropriate for all locales and applications. If the selected locale is non-null and non-empty, but the StringComparator implementation does not support it, the constructors throw an UnsupportedLocaleException. If the selected locale is supported, the collation MUST be tailored according to the locale. The tailored collation rules are implementation-specific and are not exposed to application programmers.

The generic collation data SHOULD match the common data in the Common Locale Data Repository (see http://www.unicode.org/cldr/ for details).

Collation levels

The Unicode Collation Algorithm (UCA) requires three distinct collation levels. The constants LEVEL1, LEVEL2 and LEVEL3 are used to refer to these levels. The StringComparator class also supports a fourth level, called IDENTICAL.

The default StringComparator constructor uses the LEVEL1 collation level.

References

See: Mark Davis and Ken Whistler, Unicode Technical Standard #10: Unicode Collation Algorithm, version 4.0 (2004-01-08). The Unicode Consortium. Available at http://www.unicode.org/reports/tr10/.

Field Summary

static int	IDENTICAL Constant for the comparison level that takes all differences between characters into account.
static int	LEVEL1 Constant for the primary collation level.
static int	LEVEL2 Constant for the secondary collation level.
static int	LEVEL3 Constant for the tertiary collation level.

Constructor Summary

StringComparator()
Constructs an instance using the default locale indicated by the microedition.locale system property, using the default collation level LEVEL1.

StringComparator(java.lang.String locale)
Constructs an instance using the specified locale and the default collation level LEVEL1.

StringComparator(java.lang.String locale, int level)
Constructs an instance using the specified locale and collation level.

Method Summary

int	compare(java.lang.String s1, java.lang.String s2) Compares the two strings using the rules specific to the associated locale of this instance.
boolean	equals(java.lang.String s1, java.lang.String s2) Tests if the two strings are equal according to the rules specific to the associated locale of this instance.
int	getLevel() Gets the current comparison level.
java.lang.String	getLocale() Gets the locale of this StringComparator.
static java.lang.String[]	getSupportedLocales() Gets the locales for which a StringComparator is available in this implementation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IDENTICAL

public static final int IDENTICAL

Constant for the comparison level that takes all differences between characters into account.

See Also:

Constant Field Values

LEVEL1

public static final int LEVEL1

Constant for the primary collation level. For European languages this level honours differences between alphabetical characters at the language level.

See Also:

Constant Field Values

LEVEL2

public static final int LEVEL2

Constant for the secondary collation level. For European languages this level honours differences in normal and accented versions of the same character.

See Also:

Constant Field Values

LEVEL3

public static final int LEVEL3

Constant for the tertiary collation level. For European languages this level honours differences in character case.

See Also:

Constant Field Values

Constructor Detail

StringComparator

public StringComparator()

Constructs an instance using the default locale indicated by the microedition.locale system property, using the default collation level LEVEL1. If the default locale is null, the generic collation algorithm is used.

Throws:

UnsupportedLocaleException - if the default locale is not supported by the StringComparator implementation

See Also:

LEVEL1

StringComparator

public StringComparator(java.lang.String locale)

Constructs an instance using the specified locale and the default collation level LEVEL1. If the specified locale is null or the empty string, the generic collation algorithm is used.

Parameters:

locale - the locale to use, or null to use the generic collation algorithm

Throws:

UnsupportedLocaleException - if the specified locale is not supported by the StringComparator implementation

java.lang.IllegalArgumentException - if the specified locale is non-null but not valid according to the MIDP 2.0 specification

See Also:

LEVEL1

StringComparator

public StringComparator(java.lang.String locale,
                        int level)

Constructs an instance using the specified locale and collation level.

If the specified locale is null or the empty string, this class uses the generic collation algorithm.

Parameters:

locale - the locale to use, or null to use the generic collation algorithm

level - the collation level to use

Throws:

UnsupportedLocaleException - if the specified locale is not supported by the StringComparator implementation

java.lang.IllegalArgumentException - if the specified locale is non-null but is not valid according to the MIDP 2.0 specification, or if level is not one of the constants defined in this class

See Also:

LEVEL1, LEVEL2, LEVEL3, IDENTICAL

Method Detail

compare

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

Compares the two strings using the rules specific to the associated locale of this instance. Use the equals method to more conveniently test for equality.

Parameters:

s1 - first string to compare

s2 - second string to compare

Returns:

negative if s1 belongs before s2, zero if the strings are equal, positive if s1 belongs after s2

Throws:

java.lang.NullPointerException - if either s1 or s2 is null

See Also:

equals(String, String)

equals

public boolean equals(java.lang.String s1,
                      java.lang.String s2)

Tests if the two strings are equal according to the rules specific to the associated locale of this instance.

Parameters:

s1 - first string to compare

s2 - second string to compare

Returns:

true if the strings are equal, false if not

Throws:

java.lang.NullPointerException - if either s1 or s2 is null

getLevel

public int getLevel()

Gets the current comparison level.

Returns:

the comparison level

getLocale

public java.lang.String getLocale()

Gets the locale of this StringComparator. The return value is the locale identifier string or null if this StringComparator is using the generic collation algorithm.

Returns:

the locale, or null if using the generic collation algorithm

getSupportedLocales

public static java.lang.String[] getSupportedLocales()

Gets the locales for which a StringComparator is available in this implementation. If no locales are supported, the returned array must be empty, not null. As the value null is not technically a valid locale, but a special value to trigger the generic collation algorithm, it must not appear in the array.

Returns:

an array of valid microedition.locale values