public class PluralRules extends Object implements Serializable
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).
Modifier and Type | Class and Description |
---|---|
static class |
PluralRules.Factory
Deprecated.
This API is ICU internal only.
|
static class |
PluralRules.FixedDecimal
Deprecated.
This API is ICU internal only.
|
static class |
PluralRules.FixedDecimalRange
Deprecated.
This API is ICU internal only.
|
static class |
PluralRules.FixedDecimalSamples
Deprecated.
This API is ICU internal only.
|
static class |
PluralRules.KeywordStatus
Status of the keyword for the rules, given a set of explicit values.
|
static class |
PluralRules.PluralType
Type of plurals and PluralRules.
|
static class |
PluralRules.SampleType
Deprecated.
This API is ICU internal only.
|
Modifier and Type | Field and Description |
---|---|
static String |
CATEGORY_SEPARATOR
Deprecated.
This API is ICU internal only.
|
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_RULE_SEPARATOR
Deprecated.
This API is ICU internal only.
|
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. |
Modifier and Type | Method and Description |
---|---|
boolean |
addSample(String keyword,
Number sample,
int maxCount,
Set<Double> result)
Deprecated.
This API is ICU internal only.
|
int |
compareTo(PluralRules other)
Deprecated.
internal
|
boolean |
computeLimited(String keyword,
PluralRules.SampleType sampleType)
Deprecated.
internal
|
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)
Returns true if rhs is equal to this.
|
static PluralRules |
forLocale(Locale locale)
Provides access to the predefined cardinal-number
PluralRules for a given
Locale . |
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(ULocale locale,
PluralRules.PluralType type)
Provides access to the predefined
PluralRules for a given
locale and the plural type. |
Collection<Double> |
getAllKeywordValues(String keyword)
Returns all the values that trigger this keyword, or null if the number of such
values is unlimited.
|
Collection<Double> |
getAllKeywordValues(String keyword,
PluralRules.SampleType type)
Deprecated.
This API is ICU internal only.
|
static ULocale[] |
getAvailableULocales()
Returns the set of locales for which PluralRules are known.
|
PluralRules.FixedDecimalSamples |
getDecimalSamples(String keyword,
PluralRules.SampleType sampleType)
Deprecated.
This API is ICU internal only.
|
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. |
PluralRules.KeywordStatus |
getKeywordStatus(String keyword,
int offset,
Set<Double> explicits,
Output<Double> uniqueValue)
Find the status for the keyword, given a certain set of explicit values.
|
PluralRules.KeywordStatus |
getKeywordStatus(String keyword,
int offset,
Set<Double> explicits,
Output<Double> uniqueValue,
PluralRules.SampleType sampleType)
Deprecated.
This API is ICU internal only.
|
String |
getRules(String keyword)
Deprecated.
This API is ICU internal only.
|
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.
|
Collection<Double> |
getSamples(String keyword,
PluralRules.SampleType sampleType)
Deprecated.
ICU internal only
|
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()
Deprecated.
This API is ICU internal only.
|
Boolean |
isLimited(String keyword)
Deprecated.
internal
|
boolean |
isLimited(String keyword,
PluralRules.SampleType sampleType)
Deprecated.
internal
|
boolean |
matches(PluralRules.FixedDecimal sample,
String keyword)
Deprecated.
This API is ICU internal only.
|
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 |
select(double number,
int countVisibleFractionDigits,
long fractionaldigits)
Deprecated.
This API is ICU internal only.
|
String |
select(PluralRules.FixedDecimal number)
Deprecated.
This API is ICU internal only.
|
String |
toString() |
@Deprecated public static final String CATEGORY_SEPARATOR
@Deprecated public static final String KEYWORD_RULE_SEPARATOR
public static final String KEYWORD_ZERO
public static final String KEYWORD_ONE
public static final String KEYWORD_TWO
public static final String KEYWORD_FEW
public static final String KEYWORD_MANY
public static final String KEYWORD_OTHER
public static final double NO_UNIQUE_VALUE
getUniqueKeywordValue(java.lang.String)
when there is no
unique value to return.public static final PluralRules DEFAULT
KEYWORD_OTHER
.public static PluralRules parseDescription(String description) throws ParseException
description
- the rule description.ParseException
- if the description cannot be parsed.
The exception index is typically not set, it will be -1.public static PluralRules createRules(String description)
description
- the rule description.public static PluralRules forLocale(ULocale locale)
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
locale
- The locale for which a PluralRules
object is
returned.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.public static PluralRules forLocale(Locale locale)
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
locale
- The locale for which a PluralRules
object is
returned.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.public static PluralRules forLocale(ULocale locale, PluralRules.PluralType type)
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
locale
- The locale for which a PluralRules
object is
returned.type
- The plural type (e.g., cardinal or ordinal).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.public static PluralRules forLocale(Locale locale, PluralRules.PluralType type)
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
locale
- The locale for which a PluralRules
object is
returned.type
- The plural type (e.g., cardinal or ordinal).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.@Deprecated public int hashCode()
public String select(double number)
number
- The number for which the rule has to be determined.@Deprecated public String select(double number, int countVisibleFractionDigits, long fractionaldigits)
number
- The number for which the rule has to be determined.@Deprecated public String select(PluralRules.FixedDecimal number)
number
- The number information for which the rule has to be determined.@Deprecated public boolean matches(PluralRules.FixedDecimal sample, String keyword)
sample
- The number information for which the rule has to be determined.keyword
- The keyword to filter onpublic Set<String> getKeywords()
PluralRules
object. The rule "other" is always present by default.public double getUniqueKeywordValue(String keyword)
NO_UNIQUE_VALUE
if the keyword matches multiple values or is not defined for this PluralRules.keyword
- the keyword to check for a unique valuepublic Collection<Double> getAllKeywordValues(String keyword)
keyword
- the keyword@Deprecated public Collection<Double> getAllKeywordValues(String keyword, PluralRules.SampleType type)
keyword
- the keywordtype
- the type of samples requested, INTEGER or DECIMALpublic Collection<Double> getSamples(String keyword)
keyword
- the keyword to test@Deprecated public Collection<Double> getSamples(String keyword, PluralRules.SampleType sampleType)
keyword
- the keyword to testsampleType
- the type of samples requested, INTEGER or DECIMAL@Deprecated public boolean addSample(String keyword, Number sample, int maxCount, Set<Double> result)
@Deprecated public PluralRules.FixedDecimalSamples getDecimalSamples(String keyword, PluralRules.SampleType sampleType)
keyword
- the keyword to testsampleType
- the type of samples requested, INTEGER or DECIMALpublic static ULocale[] getAvailableULocales()
public static ULocale getFunctionalEquivalent(ULocale locale, boolean[] isAvailable)
locale
- the locale to checkisAvailable
- if not null and of length > 0, this will hold 'true' at
index 0 if locale is directly defined (without fallback) as having plural rulespublic boolean equals(PluralRules rhs)
rhs
- the PluralRules to compare to.public PluralRules.KeywordStatus getKeywordStatus(String keyword, int offset, Set<Double> explicits, Output<Double> uniqueValue)
keyword
- the particular keyword (call rules.getKeywords() to get the valid ones)offset
- the offset used, or 0.0d if not. Internally, the offset is subtracted from each explicit value before
checking against the keyword values.explicits
- a set of Doubles that are used explicitly (eg [=0], "[=1]"). May be empty or null.uniqueValue
- If non null, set to the unique value.@Deprecated public PluralRules.KeywordStatus getKeywordStatus(String keyword, int offset, Set<Double> explicits, Output<Double> uniqueValue, PluralRules.SampleType sampleType)
keyword
- the particular keyword (call rules.getKeywords() to get the valid ones)offset
- the offset used, or 0.0d if not. Internally, the offset is subtracted from each explicit value before
checking against the keyword values.explicits
- a set of Doubles that are used explicitly (eg [=0], "[=1]"). May be empty or null.sampleType
- request KeywordStatus relative to INTEGER or DECIMAL valuesuniqueValue
- If non null, set to the unique value.@Deprecated public String getRules(String keyword)
@Deprecated public int compareTo(PluralRules other)
@Deprecated public Boolean isLimited(String keyword)
@Deprecated public boolean isLimited(String keyword, PluralRules.SampleType sampleType)
@Deprecated public boolean computeLimited(String keyword, PluralRules.SampleType sampleType)
Copyright (c) 2016 IBM Corporation and others.