PluralRules

Kotlin |Java

open class PluralRules : Serializable

kotlin.Any
↳	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 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:

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
	`PluralType` Type of plurals and PluralRules.

Constants
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` when there is no unique value to return.

Public methods
open static PluralRules!	`createRules(description: String!)` Creates a PluralRules from a description if it is parsable, otherwise returns null.
open Boolean	`equals(rhs: PluralRules!)` Returns true if rhs is equal to this.
open Boolean	`equals(other: Any?)` Indicates whether some other object is "equal to" this one.
open static PluralRules!	`forLocale(locale: ULocale!)` Provides access to the predefined cardinal-number `PluralRules` for a given locale.
open static PluralRules!	`forLocale(locale: ULocale!, type: PluralRules.PluralType!)` Provides access to the predefined `PluralRules` for a given locale and the plural type.
open static PluralRules!	`forLocale(locale: Locale!)` Provides access to the predefined cardinal-number `PluralRules` for a given `java.util.Locale`.
open static PluralRules!	`forLocale(locale: Locale!, type: PluralRules.PluralType!)` Provides access to the predefined `PluralRules` for a given `java.util.Locale` and the plural type.
open MutableCollection<Double!>!	`getAllKeywordValues(keyword: String!)` Returns all the values that trigger this keyword, or null if the number of such values is unlimited.
open MutableSet<String!>!	`getKeywords()` Returns a set of all rule keywords used in this `PluralRules` object.
open MutableCollection<Double!>!	`getSamples(keyword: String!)` Returns a list of integer values for which select() would return that keyword, or null if the keyword is not defined.
open Double	`getUniqueKeywordValue(keyword: String!)` 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.
open static PluralRules!	`parseDescription(description: String!)` Parses a plural rules description and returns a PluralRules.
open String!	`select(number: FormattedNumber!)` Given a formatted number, returns the keyword of the first rule that applies to the number.
open String!	`select(range: FormattedNumberRange!)` Given a formatted number range, returns the overall plural form of the range.
open String!	`select(number: Double)` Given a floating-point number, returns the keyword of the first rule that applies to the number.
open String	`toString()` Returns a string representation of the object.

Properties
static PluralRules!	`DEFAULT` The default rules that accept any number and return `KEYWORD_OTHER`.

Parameters
`locale`	ULocale!: The locale for which a `PluralRules` object is returned.
`type`	PluralRules.PluralType!: The plural type (e.g., cardinal or ordinal).

Parameters
`locale`	Locale!: The locale for which a `PluralRules` object is returned.
`type`	PluralRules.PluralType!: The plural type (e.g., cardinal or ordinal).

PluralRules

Summary

Constants

KEYWORD_FEW

KEYWORD_MANY

KEYWORD_ONE

KEYWORD_OTHER

KEYWORD_TWO

KEYWORD_ZERO

NO_UNIQUE_VALUE

Public methods

createRules

equals

equals

forLocale

forLocale

forLocale

forLocale

getAllKeywordValues

getKeywords

getSamples

getUniqueKeywordValue

parseDescription

select

select

select

toString

Properties

DEFAULT