Most visited

Recently visited

Added in API level 24

PluralRules

public class PluralRules
extends Object implements Serializable

java.lang.Object
   ↳ android.icu.text.PluralRules


Defines rules for mapping non-negative numeric values onto a small set of keywords.

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.

A PluralRules object is immutable. It contains caches for sample values, but those are synchronized.

PluralRules is Serializable so that it can be used in formatters, which are serializable.

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      = not? expr not? rel not? range_list
 expr          = ('n' | 'i' | 'f' | 'v' | 't') (mod value)?
 not           = 'not' | '!'
 rel           = 'in' | 'is' | '=' | '≠' | 'within'
 mod           = 'mod' | '%'
 range_list    = (range | value) (',' range_list)*
 value         = digit+
 digit         = 0|1|2|3|4|5|6|7|8|9
 range         = value'..'value
 

Each not term inverts the meaning; however, there should not be more than one of them.

The i, f, t, and v values are defined as follows:

Examples are in the following table:

n i f v
1.0 1 0 1
1.00 1 0 2
1.3 1 3 1
1.03 1 3 2
1.23 1 23 2

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).

Summary

Nested classes

enum PluralRules.PluralType

Type of plurals and PluralRules. 

Constants

String KEYWORD_FEW

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

String KEYWORD_MANY

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

String KEYWORD_ONE

Common name for the 'singular' plural form.

String KEYWORD_OTHER

Common name for the default plural form.

String KEYWORD_TWO

Common name for the 'dual' plural form.

String KEYWORD_ZERO

Common name for the 'zero' plural form.

double NO_UNIQUE_VALUE

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

Fields

public static final PluralRules DEFAULT

The default rules that accept any number and return KEYWORD_OTHER.

Public methods

static PluralRules createRules(String description)

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

boolean equals(PluralRules rhs)

Returns true if rhs is equal to this.

boolean equals(Object rhs)

Indicates whether some other object is "equal to" this one.

static PluralRules forLocale(ULocale locale, PluralRules.PluralType type)

Provides access to the predefined PluralRules for a given locale and the plural type.

static PluralRules forLocale(Locale locale, PluralRules.PluralType type)

Provides access to the predefined PluralRules for a given Locale and the plural type.

static PluralRules forLocale(ULocale locale)

Provides access to the predefined cardinal-number PluralRules for a given locale.

static PluralRules forLocale(Locale locale)

Provides access to the predefined cardinal-number 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.

Set<String> getKeywords()

Returns a set of all rule keywords used in this PluralRules object.

Collection<Double> getSamples(String keyword)

Returns a list of integer 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.

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()

Returns a string representation of the object.

Inherited methods

From class java.lang.Object

Constants

KEYWORD_FEW

Added in API level 24
String KEYWORD_FEW

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

Constant Value: "few"

KEYWORD_MANY

Added in API level 24
String KEYWORD_MANY

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

Constant Value: "many"

KEYWORD_ONE

Added in API level 24
String KEYWORD_ONE

Common name for the 'singular' plural form.

Constant Value: "one"

KEYWORD_OTHER

Added in API level 24
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.

Constant Value: "other"

KEYWORD_TWO

Added in API level 24
String KEYWORD_TWO

Common name for the 'dual' plural form.

Constant Value: "two"

KEYWORD_ZERO

Added in API level 24
String KEYWORD_ZERO

Common name for the 'zero' plural form.

Constant Value: "zero"

NO_UNIQUE_VALUE

Added in API level 24
double NO_UNIQUE_VALUE

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

Constant Value: -0.00123456777

Fields

DEFAULT

Added in API level 24
PluralRules DEFAULT

The default rules that accept any number and return KEYWORD_OTHER.

Public methods

createRules

Added in API level 24
PluralRules createRules (String description)

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

Parameters
description String: the rule description.
Returns
PluralRules the PluralRules

equals

Added in API level 24
boolean equals (PluralRules rhs)

Returns true if rhs is equal to this.

Parameters
rhs PluralRules: the PluralRules to compare to.
Returns
boolean true if this and rhs are equal.

equals

Added in API level 24
boolean equals (Object rhs)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Parameters
rhs Object: the reference object with which to compare.
Returns
boolean true if this object is the same as the obj argument; false otherwise.

forLocale

Added in API level 24
PluralRules forLocale (ULocale locale, 
                PluralRules.PluralType type)

Provides access to the predefined PluralRules for a given locale and the plural type.

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 ULocale: The locale for which a PluralRules object is returned.
type PluralRules.PluralType: The plural type (e.g., cardinal or ordinal).
Returns
PluralRules 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.

forLocale

Added in API level 24
PluralRules forLocale (Locale locale, 
                PluralRules.PluralType type)

Provides access to the predefined PluralRules for a given Locale and the plural type.

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 Locale: The locale for which a PluralRules object is returned.
type PluralRules.PluralType: The plural type (e.g., cardinal or ordinal).
Returns
PluralRules 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.

forLocale

Added in API level 24
PluralRules forLocale (ULocale locale)

Provides access to the predefined cardinal-number PluralRules for a given locale. Same as forLocale(locale, PluralType.CARDINAL).

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 ULocale: The locale for which a PluralRules object is returned.
Returns
PluralRules 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.

forLocale

Added in API level 24
PluralRules forLocale (Locale locale)

Provides access to the predefined cardinal-number PluralRules for a given Locale. Same as forLocale(locale, PluralType.CARDINAL).

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 Locale: The locale for which a PluralRules object is returned.
Returns
PluralRules 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.

getAllKeywordValues

Added in API level 24
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 String: the keyword
Returns
Collection<Double> the values that trigger this keyword, or null. The returned collection is immutable. It will be empty if the keyword is not defined.

getKeywords

Added in API level 24
Set<String> getKeywords ()

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

Returns
Set<String> The set of keywords.

getSamples

Added in API level 24
Collection<Double> getSamples (String keyword)

Returns a list of integer 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 String: the keyword to test
Returns
Collection<Double> a list of values matching the keyword.

getUniqueKeywordValue

Added in API level 24
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 String: the keyword to check for a unique value
Returns
double The unique value for the keyword, or NO_UNIQUE_VALUE.

parseDescription

Added in API level 24
PluralRules parseDescription (String description)

Parses a plural rules description and returns a PluralRules.

Parameters
description String: the rule description.
Returns
PluralRules
Throws
ParseException if the description cannot be parsed. The exception index is typically not set, it will be -1.

select

Added in API level 24
String select (double number)

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

Parameters
number double: The number for which the rule has to be determined.
Returns
String The keyword of the selected rule.

toString

Added in API level 24
String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns
String a string representation of the object.

Hooray!