public Class 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 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, Part 3.5 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:

• i to be the integer digits.
• f to be the visible decimal digits, as an integer.
• t to be the visible decimal digits—without trailing zeros—as an integer.
• v to be the number of visible fraction digits.
• j is defined to only match integers. That is j is 3 fails if v != 0 (eg for 3.1 or 3.0).

Examples are in the following table:

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