com.ibm.icu.text
Class PluralRules

java.lang.Object
  com.ibm.icu.text.PluralRules

All Implemented Interfaces:

Serializable

public class PluralRules
extends Object
implements Serializable

Defines rules for mapping non-negative numeric values onto a small set of keywords. Serializable so can be used in formatters, which are serializable. Rules are constructed from a text description, consisting of a series of keywords and conditions. The select(double) method examines each condition in order and returns the keyword for the first condition that matches the number. If none match, KEYWORD_OTHER is returned.

For more information, details, and tips for writing rules, see the LDML spec, C.11 Language Plural Rules

Examples:

   "one: n is 1; few: n in 2..4"

This defines two rules, for 'one' and 'few'. The condition for 'one' is "n is 1" which means that the number must be equal to 1 for this condition to pass. The condition for 'few' is "n in 2..4" which means that the number must be between 2 and 4 inclusive - and be an integer - for this condition to pass. All other numbers are assigned the keyword "other" by the default rule.

   "zero: n is 0; one: n is 1; zero: n mod 100 in 1..19"

This illustrates that the same keyword can be defined multiple times. Each rule is examined in order, and the first keyword whose condition passes is the one returned. Also notes that a modulus is applied to n in the last rule. Thus its condition holds for 119, 219, 319...

   "one: n is 1; few: n mod 10 in 2..4 and n mod 100 not in 12..14"

This illustrates conjunction and negation. The condition for 'few' has two parts, both of which must be met: "n mod 10 in 2..4" and "n mod 100 not in 12..14". The first part applies a modulus to n before the test as in the previous example. The second part applies a different modulus and also uses negation, thus it matches all numbers _not_ in 12, 13, 14, 112, 113, 114, 212, 213, 214...

Syntax:

 rules         = rule (';' rule)*
 rule          = keyword ':' condition
 keyword       = <identifier>
 condition     = and_condition ('or' and_condition)*
 and_condition = relation ('and' relation)*
 relation      = is_relation | in_relation | within_relation | 'n' 
 is_relation   = expr 'is' ('not')? value
 in_relation   = expr ('not')? 'in' range_list
 within_relation = expr ('not')? 'within' range_list
 expr          = 'n' ('mod' value)?
 range_list    = (range | value) (',' range_list)*
 value         = digit+
 digit         = 0|1|2|3|4|5|6|7|8|9
 range         = value'..'value
 

An "identifier" is a sequence of characters that do not have the Unicode Pattern_Syntax or Pattern_White_Space properties.

The difference between 'in' and 'within' is that 'in' only includes integers in the specified range, while 'within' includes all values. Using 'within' with a range_list consisting entirely of values is the same as using 'in' (it's not an error).

See Also:

Serialized Form

Status:

Stable ICU 3.8.

Field Summary

static PluralRules	DEFAULT The default rules that accept any number and return KEYWORD_OTHER.
static String	KEYWORD_FEW Common name for the 'paucal' or other special plural form.
static String	KEYWORD_MANY Common name for the arabic (11 to 99) plural form.
static String	KEYWORD_ONE Common name for the 'singular' plural form.
static String	KEYWORD_OTHER Common name for the default plural form.
static String	KEYWORD_TWO Common name for the 'dual' plural form.
static String	KEYWORD_ZERO Common name for the 'zero' plural form.
static double	NO_UNIQUE_VALUE Value returned by getUniqueKeywordValue(java.lang.String) when there is no unique value to return.

Method Summary

static PluralRules	createRules(String description) Creates a PluralRules from a description if it is parsable, otherwise returns null.
boolean	equals(Object rhs)
boolean	equals(PluralRules rhs) Return tif rhs is equal to this.
static PluralRules	forLocale(ULocale locale) Provides access to the predefined PluralRules for a given locale.
Collection<Double>	getAllKeywordValues(String keyword) Returns all the values that trigger this keyword, or null if the number of such values is unlimited.
static ULocale[]	getAvailableULocales() Returns the set of locales for which PluralRules are known.
static ULocale	getFunctionalEquivalent(ULocale locale, boolean[] isAvailable) Returns the 'functionally equivalent' locale with respect to plural rules.
Set<String>	getKeywords() Returns a set of all rule keywords used in this PluralRules object.
Collection<Double>	getSamples(String keyword) Returns a list of values for which select() would return that keyword, or null if the keyword is not defined.
double	getUniqueKeywordValue(String keyword) Returns the unique value that this keyword matches, or NO_UNIQUE_VALUE if the keyword matches multiple values or is not defined for this PluralRules.
int	hashCode()
static PluralRules	parseDescription(String description) Parses a plural rules description and returns a PluralRules.
String	select(double number) Given a number, returns the keyword of the first rule that applies to the number.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

KEYWORD_ZERO

public static final String KEYWORD_ZERO

Common name for the 'zero' plural form.

See Also:

Constant Field Values

Status:

Stable ICU 3.8.

KEYWORD_ONE

public static final String KEYWORD_ONE

Common name for the 'singular' plural form.

See Also:

Constant Field Values

Status:

Stable ICU 3.8.

KEYWORD_TWO

public static final String KEYWORD_TWO

Common name for the 'dual' plural form.

See Also:

Constant Field Values

Status:

Stable ICU 3.8.

KEYWORD_FEW

public static final String KEYWORD_FEW

Common name for the 'paucal' or other special plural form.

See Also:

Constant Field Values

Status:

Stable ICU 3.8.

KEYWORD_MANY

public static final String KEYWORD_MANY

Common name for the arabic (11 to 99) plural form.

See Also:

Constant Field Values

Status:

Stable ICU 3.8.

KEYWORD_OTHER

public static final String KEYWORD_OTHER

Common name for the default plural form. This name is returned for values to which no other form in the rule applies. It can additionally be assigned rules of its own.

See Also:

Constant Field Values

Status:

Stable ICU 3.8.

NO_UNIQUE_VALUE

public static final double NO_UNIQUE_VALUE

Value returned by getUniqueKeywordValue(java.lang.String) when there is no unique value to return.

See Also:

Constant Field Values

Status:

Draft ICU 4.8.

DEFAULT

public static final PluralRules DEFAULT

The default rules that accept any number and return KEYWORD_OTHER.

Status:

Stable ICU 3.8.

Method Detail

parseDescription

public static PluralRules parseDescription(String description)
                                    throws ParseException

Parses a plural rules description and returns a PluralRules.

Parameters:

description - the rule description.

Throws:

ParseException - if the description cannot be parsed. The exception index is typically not set, it will be -1.

Status:

Stable ICU 3.8.

createRules

public static PluralRules createRules(String description)

Creates a PluralRules from a description if it is parsable, otherwise returns null.

Parameters:

description - the rule description.

Returns:

the PluralRules

Status:

Stable ICU 3.8.

forLocale

public static PluralRules forLocale(ULocale locale)

Provides access to the predefined PluralRules for a given locale. ICU defines plural rules for many locales based on CLDR Language Plural Rules. For these predefined rules, see CLDR page at http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html

Parameters:

locale - The locale for which a PluralRules object is returned.

Returns:

The predefined PluralRules object for this locale. If there's no predefined rules for this locale, the rules for the closest parent in the locale hierarchy that has one will be returned. The final fallback always returns the default rules.

Status:

Stable ICU 3.8.

select

public String select(double number)

Given a number, returns the keyword of the first rule that applies to the number.

Parameters:

number - The number for which the rule has to be determined.

Returns:

The keyword of the selected rule.

Status:

Stable ICU 4.0.

getKeywords

public Set<String> getKeywords()

Returns a set of all rule keywords used in this PluralRules object. The rule "other" is always present by default.

Returns:

The set of keywords.

Status:

Stable ICU 3.8.

getUniqueKeywordValue

public double getUniqueKeywordValue(String keyword)

Returns the unique value that this keyword matches, or NO_UNIQUE_VALUE if the keyword matches multiple values or is not defined for this PluralRules.

Parameters:

keyword - the keyword to check for a unique value

Returns:

The unique value for the keyword, or NO_UNIQUE_VALUE.

Status:

Draft ICU 4.8.

getAllKeywordValues

public Collection<Double> getAllKeywordValues(String keyword)

Returns all the values that trigger this keyword, or null if the number of such values is unlimited.

Parameters:

keyword - the keyword

Returns:

the values that trigger this keyword, or null. The returned collection is immutable. It will be empty if the keyword is not defined.

Status:

Draft ICU 4.8.

getSamples

public Collection<Double> getSamples(String keyword)

Returns a list of values for which select() would return that keyword, or null if the keyword is not defined. The returned collection is unmodifiable. The returned list is not complete, and there might be additional values that would return the keyword.

Parameters:

keyword - the keyword to test

Returns:

a list of values matching the keyword.

Status:

Draft ICU 4.8.

getAvailableULocales

public static ULocale[] getAvailableULocales()

Returns the set of locales for which PluralRules are known.

Returns:

the set of locales for which PluralRules are known, as a list

Status:

Draft ICU 4.2.

getFunctionalEquivalent

public static ULocale getFunctionalEquivalent(ULocale locale,
                                              boolean[] isAvailable)

Returns the 'functionally equivalent' locale with respect to plural rules. Calling PluralRules.forLocale with the functionally equivalent locale, and with the provided locale, returns rules that behave the same.
All locales with the same functionally equivalent locale have plural rules that behave the same. This is not exaustive; there may be other locales whose plural rules behave the same that do not have the same equivalent locale.

Parameters:

locale - the locale to check

isAvailable - if not null and of length > 0, this will hold 'true' at index 0 if locale is directly defined (without fallback) as having plural rules

Returns:

the functionally-equivalent locale

Status:

Draft ICU 4.2.

toString

public String toString()

Overrides:

toString in class Object

Status:

Stable ICU 3.8.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

Status:

Stable ICU 3.8.

equals

public boolean equals(Object rhs)

Overrides:

equals in class Object

Status:

Stable ICU 3.8.

equals

public boolean equals(PluralRules rhs)

Return tif rhs is equal to this.

Parameters:

rhs - the PluralRules to compare to.

Returns:

true if this and rhs are equal.

Status:

Stable ICU 3.8.