javax.microedition.global
Class StringComparator

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

public final class StringComparator
extends Object

Since:

BlackBerry API 4.3.0

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(String locale)
Constructs an instance using the specified locale and the default collation level LEVEL1.

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

Method Summary
int	compare(String s1, String s2) Compares the two strings using the rules specific to the associated locale of this instance.
boolean	equals(String s1, 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.
String	getLocale() Gets the locale of this StringComparator.
static 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

Since:

BlackBerry API 4.3.0

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

Since:

BlackBerry API 4.3.0

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

Since:

BlackBerry API 4.3.0

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

Since:

BlackBerry API 4.3.0

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

Since:

BlackBerry API 4.3.0

StringComparator

public StringComparator(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 default locale is not supported by the StringComparator implementation

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

Since:

BlackBerry API 4.3.0

StringComparator

public StringComparator(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 default locale is not supported by the StringComparator implementation

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

Since:

BlackBerry API 4.3.0

Method Detail

compare

public int compare(String s1,
                   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:

NullPointerException - if either s1 or s2 is null

Since:

BlackBerry API 4.3.0

equals

public boolean equals(String s1,
                      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:

NullPointerException - if either s1 or s2 is null

Since:

BlackBerry API 4.3.0

getLevel

public int getLevel()

Gets the current comparison level.

Returns:

the comparison level

Since:

BlackBerry API 4.3.0

getLocale

public 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

Since:

BlackBerry API 4.3.0

getSupportedLocales

public static 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

Since:

BlackBerry API 4.3.0