ICU 53.1  53.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Friends
icu::PluralRules Class Reference

Defines rules for mapping non-negative numeric values onto a small set of keywords. More...

#include <plurrule.h>

Inheritance diagram for icu::PluralRules:
icu::UObject icu::UMemory

Public Member Functions

 PluralRules (UErrorCode &status)
 Constructor. More...
 
 PluralRules (const PluralRules &other)
 Copy constructor. More...
 
virtual ~PluralRules ()
 Destructor. More...
 
PluralRulesclone () const
 Clone. More...
 
PluralRulesoperator= (const PluralRules &)
 Assignment operator. More...
 
UnicodeString select (int32_t number) const
 Given a number, returns the keyword of the first rule that applies to the number. More...
 
UnicodeString select (double number) const
 Given a number, returns the keyword of the first rule that applies to the number. More...
 
UnicodeString select (const FixedDecimal &number) const
 
StringEnumerationgetKeywords (UErrorCode &status) const
 Returns a list of all rule keywords used in this PluralRules object. More...
 
double getUniqueKeywordValue (const UnicodeString &keyword)
 Returns a unique value for this keyword if it exists, else the constant UPLRULES_NO_UNIQUE_VALUE. More...
 
int32_t getAllKeywordValues (const UnicodeString &keyword, double *dest, int32_t destCapacity, UErrorCode &status)
 Returns all the values for which select() would return the keyword. More...
 
int32_t getSamples (const UnicodeString &keyword, double *dest, int32_t destCapacity, UErrorCode &status)
 Returns sample values for which select() would return the keyword. More...
 
UBool isKeyword (const UnicodeString &keyword) const
 Returns TRUE if the given keyword is defined in this PluralRules object. More...
 
UnicodeString getKeywordOther () const
 Returns keyword for default plural form. More...
 
UnicodeString getRules () const
 
virtual UBool operator== (const PluralRules &other) const
 Compares the equality of two PluralRules objects. More...
 
UBool operator!= (const PluralRules &other) const
 Compares the inequality of two PluralRules objects. More...
 
virtual UClassID getDynamicClassID () const
 ICU "poor man's RTTI", returns a UClassID for the actual class. More...
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor. More...
 

Static Public Member Functions

static PluralRulescreateRules (const UnicodeString &description, UErrorCode &status)
 Creates a PluralRules from a description if it is parsable, otherwise returns NULL. More...
 
static PluralRulescreateDefaultRules (UErrorCode &status)
 The default rules that accept any number. More...
 
static PluralRulesforLocale (const Locale &locale, UErrorCode &status)
 Provides access to the predefined cardinal-number PluralRules for a given locale. More...
 
static PluralRulesforLocale (const Locale &locale, UPluralType type, UErrorCode &status)
 Provides access to the predefined PluralRules for a given locale and the plural type. More...
 
static StringEnumerationgetAvailableLocales (UErrorCode &status)
 Return a StringEnumeration over the locales for which there is plurals data. More...
 
static UBool hasOverride (const Locale &locale)
 Returns whether or not there are overrides. More...
 
static PluralRulesinternalForLocale (const Locale &locale, UPluralType type, UErrorCode &status)
 For ICU use only. More...
 
static const SharedPluralRules * createSharedInstance (const Locale &locale, UPluralType type, UErrorCode &status)
 For ICU use only. More...
 
static UClassID getStaticClassID (void)
 ICU "poor man's RTTI", returns a UClassID for this class. More...
 

Friends

class PluralRuleParser
 

Detailed Description

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, default rule(other) is returned.

For more information, details, and tips for writing rules, see the LDML spec, C.11 Language Plural Rules: http://www.unicode.org/draft/reports/tr35/tr35.html#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 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 = is_relation | in_relation | within_relation | 'n' <EOL>
is_relation = expr 'is' ('not')? value
in_relation = expr ('not')? 'in' range_list
within_relation = expr ('not')? 'within' range
expr = ('n' | 'i' | 'f' | 'v' | 'j') ('mod' value)?
range_list = (range | value) (',' range_list)*
value = digit+ ('.' digit+)?
digit = 0|1|2|3|4|5|6|7|8|9
range = value'..'value

The i, f, 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 </tbody>

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

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

Keywords could be defined by users or from ICU locale data. There are 6 predefined values in ICU - 'zero', 'one', 'two', 'few', 'many' and 'other'. Callers need to check the value of keyword returned by select method.

Examples:

 UnicodeString keyword = pl->select(number);
 if (keyword== UnicodeString("one") {
     ...
 }
 else if ( ... )
 

Note:

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

Definition at line 191 of file plurrule.h.

Constructor & Destructor Documentation

icu::PluralRules::PluralRules ( UErrorCode status)

Constructor.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Stable:
ICU 4.0
icu::PluralRules::PluralRules ( const PluralRules other)

Copy constructor.

Stable:
ICU 4.0
virtual icu::PluralRules::~PluralRules ( )
virtual

Destructor.

Stable:
ICU 4.0

Member Function Documentation

PluralRules* icu::PluralRules::clone ( ) const

Clone.

Stable:
ICU 4.0
static PluralRules* icu::PluralRules::createDefaultRules ( UErrorCode status)
static

The default rules that accept any number.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
new PluralRules pointer. NULL if there is an error.
Stable:
ICU 4.0
static PluralRules* icu::PluralRules::createRules ( const UnicodeString description,
UErrorCode status 
)
static

Creates a PluralRules from a description if it is parsable, otherwise returns NULL.

Parameters
descriptionrule description
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
new PluralRules pointer. NULL if there is an error.
Stable:
ICU 4.0
static const SharedPluralRules* icu::PluralRules::createSharedInstance ( const Locale locale,
UPluralType  type,
UErrorCode status 
)
static

For ICU use only.

Returns handle to the shared, cached PluralRules instance. Caller must call removeRef() on returned value once it is done with the shared instance.

Internal:
Do not use. This API is for internal use only.
static PluralRules* icu::PluralRules::forLocale ( const Locale locale,
UErrorCode status 
)
static

Provides access to the predefined cardinal-number PluralRules for a given locale.

Same as forLocale(locale, UPLURAL_TYPE_CARDINAL, status).

Parameters
localeThe locale for which a PluralRules object is returned.
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
The predefined PluralRules object pointer 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 'other' rules.
Stable:
ICU 4.0
static PluralRules* icu::PluralRules::forLocale ( const Locale locale,
UPluralType  type,
UErrorCode status 
)
static

Provides access to the predefined PluralRules for a given locale and the plural type.

Parameters
localeThe locale for which a PluralRules object is returned.
typeThe plural type (e.g., cardinal or ordinal).
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
The predefined PluralRules object pointer 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 'other' rules.
Stable:
ICU 50
int32_t icu::PluralRules::getAllKeywordValues ( const UnicodeString keyword,
double *  dest,
int32_t  destCapacity,
UErrorCode status 
)

Returns all the values for which select() would return the keyword.

If the keyword is unknown, returns no values, but this is not an error. If the number of values is unlimited, returns no values and -1 as the count.

The number of returned values is typically small.

Parameters
keywordThe keyword.
destArray into which to put the returned values. May be NULL if destCapacity is 0.
destCapacityThe capacity of the array, must be at least 0.
statusThe error code.
Returns
The count of values available, or -1. This count can be larger than destCapacity, but no more than destCapacity values will be written.
Stable:
ICU 4.8
static StringEnumeration* icu::PluralRules::getAvailableLocales ( UErrorCode status)
static

Return a StringEnumeration over the locales for which there is plurals data.

Returns
a StringEnumeration over the locales available.
Internal:
Do not use. This API is for internal use only.
virtual UClassID icu::PluralRules::getDynamicClassID ( ) const
virtual

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
ICU 4.0

Reimplemented from icu::UObject.

UnicodeString icu::PluralRules::getKeywordOther ( ) const

Returns keyword for default plural form.

Returns
keyword for default plural form.
Stable:
ICU 4.0
StringEnumeration* icu::PluralRules::getKeywords ( UErrorCode status) const

Returns a list of all rule keywords used in this PluralRules object.

The rule 'other' is always present by default.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
StringEnumeration with the keywords. The caller must delete the object.
Stable:
ICU 4.0
UnicodeString icu::PluralRules::getRules ( ) const
Internal:
Do not use. This API is for internal use only.
int32_t icu::PluralRules::getSamples ( const UnicodeString keyword,
double *  dest,
int32_t  destCapacity,
UErrorCode status 
)

Returns sample values for which select() would return the keyword.

If the keyword is unknown, returns no values, but this is not an error.

The number of returned values is typically small.

Parameters
keywordThe keyword.
destArray into which to put the returned values. May be NULL if destCapacity is 0.
destCapacityThe capacity of the array, must be at least 0.
statusThe error code.
Returns
The count of values written. If more than destCapacity samples are available, then only destCapacity are written, and destCapacity is returned as the count, rather than setting a U_BUFFER_OVERFLOW_ERROR. (The actual number of keyword values could be unlimited.)
Stable:
ICU 4.8
static UClassID icu::PluralRules::getStaticClassID ( void  )
static

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
ICU 4.0
double icu::PluralRules::getUniqueKeywordValue ( const UnicodeString keyword)

Returns a unique value for this keyword if it exists, else the constant UPLRULES_NO_UNIQUE_VALUE.

Parameters
keywordThe keyword.
Returns
The unique value that generates the keyword, or UPLRULES_NO_UNIQUE_VALUE if the keyword is undefined or there is no unique value that generates this keyword.
Stable:
ICU 4.8
static UBool icu::PluralRules::hasOverride ( const Locale locale)
static

Returns whether or not there are overrides.

Parameters
localethe locale to check.
Returns
Internal:
Do not use. This API is for internal use only.
static PluralRules* icu::PluralRules::internalForLocale ( const Locale locale,
UPluralType  type,
UErrorCode status 
)
static

For ICU use only.

creates a SharedPluralRules object

Internal:
Do not use. This API is for internal use only.
UBool icu::PluralRules::isKeyword ( const UnicodeString keyword) const

Returns TRUE if the given keyword is defined in this PluralRules object.

Parameters
keywordthe input keyword.
Returns
TRUE if the input keyword is defined. Otherwise, return FALSE.
Stable:
ICU 4.0
UBool icu::PluralRules::operator!= ( const PluralRules other) const
inline

Compares the inequality of two PluralRules objects.

Parameters
otherThe PluralRules object to be compared with.
Returns
True if the given PluralRules is not the same as this PluralRules; false otherwise.
Stable:
ICU 4.0

Definition at line 465 of file plurrule.h.

References icu::operator==().

PluralRules& icu::PluralRules::operator= ( const PluralRules )

Assignment operator.

Stable:
ICU 4.0
virtual UBool icu::PluralRules::operator== ( const PluralRules other) const
virtual

Compares the equality of two PluralRules objects.

Parameters
otherThe other PluralRules object to be compared with.
Returns
True if the given PluralRules is the same as this PluralRules; false otherwise.
Stable:
ICU 4.0
UnicodeString icu::PluralRules::select ( int32_t  number) const

Given a number, returns the keyword of the first rule that applies to the number.

This function can be used with isKeyword* functions to determine the keyword for default plural rules.

Parameters
numberThe number for which the rule has to be determined.
Returns
The keyword of the selected rule.
Stable:
ICU 4.0
UnicodeString icu::PluralRules::select ( double  number) const

Given a number, returns the keyword of the first rule that applies to the number.

This function can be used with isKeyword* functions to determine the keyword for default plural rules.

Parameters
numberThe number for which the rule has to be determined.
Returns
The keyword of the selected rule.
Stable:
ICU 4.0
UnicodeString icu::PluralRules::select ( const FixedDecimal &  number) const
Internal:
Do not use. This API is for internal use only.

The documentation for this class was generated from the following file: