com.ibm.icu.text
Class PluralRules

java.lang.Object
  extended by com.ibm.icu.text.PluralRules
All Implemented Interfaces:
Serializable

public class PluralRules
extends Object
implements Serializable

Defines rules for mapping positive double values onto a small set of keywords. Serializable so can be used in formatters, which are serializable. 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.

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       = 
 condition     = and_condition ('or' and_condition)*
 and_condition = relation ('and' relation)*
 relation      = is_relation | in_relation | within_relation | 'n' 
 is_relation   = expr 'is' ('not')? value
 in_relation   = expr ('not')? 'in' range
 within_relation = expr ('not')? 'within' range
 expr          = 'n' ('mod' value)?
 value         = digit+
 digit         = 0|1|2|3|4|5|6|7|8|9
 range         = value'..'value
 

The difference between 'in' and 'within' is that 'in' only includes integers in the specified range, while 'within' includes all values.

See Also:
Serialized Form
Status:
Draft ICU 3.8.

Field Summary
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_TWO
          Common name for the 'dual' plural form.
static String KEYWORD_ZERO
          Common name for the 'zero' plural form.
 
Method Summary
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)
          Return tif rhs is equal to this.
static PluralRules forLocale(ULocale locale)
          Provides access to the predefined PluralRules for a given locale.
 Set getKeywords()
          Returns a set of all rule keywords used in this PluralRules object.
 int hashCode()
          
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()
          
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

KEYWORD_ZERO

public static final String KEYWORD_ZERO
Common name for the 'zero' plural form.

See Also:
Constant Field Values
Status:
Draft ICU 3.8.

KEYWORD_ONE

public static final String KEYWORD_ONE
Common name for the 'singular' plural form.

See Also:
Constant Field Values
Status:
Draft ICU 3.8.

KEYWORD_TWO

public static final String KEYWORD_TWO
Common name for the 'dual' plural form.

See Also:
Constant Field Values
Status:
Draft ICU 3.8.

KEYWORD_FEW

public static final String KEYWORD_FEW
Common name for the 'paucal' or other special plural form.

See Also:
Constant Field Values
Status:
Draft ICU 3.8.

KEYWORD_MANY

public static final String KEYWORD_MANY
Common name for the arabic (11 to 99) plural form.

See Also:
Constant Field Values
Status:
Draft ICU 3.8.

KEYWORD_OTHER

public static final 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.

See Also:
Constant Field Values
Status:
Draft ICU 3.8.

DEFAULT

public static final PluralRules DEFAULT
The default rules that accept any number and return KEYWORD_OTHER.

Status:
Draft ICU 3.8.
Method Detail

parseDescription

public static PluralRules parseDescription(String description)
                                    throws ParseException
Parses a plural rules description and returns a PluralRules.

Parameters:
description - the rule description.
Throws:
ParseException - if the description cannot be parsed. The exception index is typically not set, it will be -1.
Status:
Draft ICU 3.8.

createRules

public static PluralRules createRules(String description)
Creates a PluralRules from a description if it is parsable, otherwise returns null.

Parameters:
description - the rule description.
Returns:
the PluralRules
Status:
Draft ICU 3.8.

forLocale

public static PluralRules forLocale(ULocale locale)
Provides access to the predefined PluralRules for a given locale.

Parameters:
locale - The locale for which a PluralRules object is returned.
Returns:
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.
Status:
Draft ICU 3.8.

select

public String select(double number)
Given a number, returns the keyword of the first rule that applies to the number.

Parameters:
number - The number for which the rule has to be determined.
Returns:
The keyword of the selected rule.
Status:
Draft ICU 4.0.

getKeywords

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

Returns:
The set of keywords.
Status:
Draft ICU 3.8.

toString

public String toString()

Overrides:
toString in class Object
Status:
Draft ICU 3.8.

hashCode

public int hashCode()

Overrides:
hashCode in class Object
Status:
Draft ICU 3.8.

equals

public boolean equals(Object rhs)

Overrides:
equals in class Object
Status:
Draft ICU 3.8.

equals

public boolean equals(PluralRules rhs)
Return tif rhs is equal to this.

Parameters:
rhs - the PluralRules to compare to.
Returns:
true if this and rhs are equal.
Status:
Draft ICU 3.8.


Copyright (c) 2009 IBM Corporation and others.