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).
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 |
Fields | |
---|---|
public
static
final
PluralRules |
DEFAULT
The default rules that accept any number and return
|
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 |
static
PluralRules
|
forLocale(Locale locale, PluralRules.PluralType type)
Provides access to the predefined |
static
PluralRules
|
forLocale(ULocale locale)
Provides access to the predefined cardinal-number |
static
PluralRules
|
forLocale(Locale locale)
Provides access to the predefined cardinal-number |
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 |
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 |
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
|
String KEYWORD_FEW
Common name for the 'paucal' or other special plural form.
Constant Value: "few"
String KEYWORD_MANY
Common name for the arabic (11 to 99) plural form.
Constant Value: "many"
String KEYWORD_ONE
Common name for the 'singular' plural form.
Constant Value: "one"
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"
String KEYWORD_TWO
Common name for the 'dual' plural form.
Constant Value: "two"
String KEYWORD_ZERO
Common name for the 'zero' plural form.
Constant Value: "zero"
double NO_UNIQUE_VALUE
Value returned by getUniqueKeywordValue(String)
when there is no
unique value to return.
Constant Value: -0.00123456777
PluralRules DEFAULT
The default rules that accept any number and return
KEYWORD_OTHER
.
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 |
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. |
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:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
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.
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. |
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.
|
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.
|
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.
|
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.
|
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. |
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. |
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. |
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. |
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. |
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. |
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. |