ICU 76.1: icu::PluralRules Class Reference

ICU 76.1 76.1

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:

## Public Member Functions
| PluralRules (UErrorCode &status)
| Constructor. More...
| PluralRules (const PluralRules &other)
| Copy constructor. More...
virtual | ~PluralRules ()
| Destructor. More...
PluralRules * | clone () const
| Clone. More...
PluralRules & | operator= (const PluralRules &)
| Assignment operator. More...
UnicodeString | select (int32_t number) const
| Given an integer, returns the keyword of the first rule that applies to the number. More...
UnicodeString | select (double number) const
| Given a floating-point number, returns the keyword of the first rule that applies to the number. More...
UnicodeString | select (const number::FormattedNumber &number, UErrorCode &status) const
| Given a formatted number, returns the keyword of the first rule that applies to the number. More...
UnicodeString | select (const number::FormattedNumberRange &range, UErrorCode &status) const
| Given a formatted number range, returns the overall plural form of the range. More...
UnicodeString | select (const IFixedDecimal &number) const
UnicodeString | select (const number::impl::UFormattedNumberRangeData *urange, UErrorCode &status) const
StringEnumeration * | getKeywords (UErrorCode &status) const
| Returns a list of all rule keywords used in this `PluralRules` object. More...
double | getUniqueKeywordValue (const UnicodeString &keyword)
| Deprecated Function, does not return useful results. More...
int32_t | getAllKeywordValues (const UnicodeString &keyword, double *dest, int32_t destCapacity, UErrorCode &status)
| Deprecated Function, does not produce useful results. 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...
int32_t | getSamples (const UnicodeString &keyword, DecimalQuantity *dest, int32_t destCapacity, UErrorCode &status)
| Internal-only function that returns DecimalQuantitys instead of doubles. 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 bool | operator== (const PluralRules &other) const
| Compares the equality of two PluralRules objects. More...
bool | operator!= (const PluralRules &other) const
| Compares the inequality of two PluralRules objects. More...
virtual UClassID | getDynamicClassID () const override
| 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 PluralRules * | createRules (const UnicodeString &description, UErrorCode &status)
| Creates a PluralRules from a description if it is parsable, otherwise returns nullptr. More...
static PluralRules * | createDefaultRules (UErrorCode &status)
| The default rules that accept any number. More...
static PluralRules * | forLocale (const Locale &locale, UErrorCode &status)
| Provides access to the predefined cardinal-number `PluralRules` for a given locale. More...
static PluralRules * | forLocale (const Locale &locale, UPluralType type, UErrorCode &status)
| Provides access to the predefined `PluralRules` for a given locale and the plural type. More...
static StringEnumeration * | getAvailableLocales (UErrorCode &status)
| Return a StringEnumeration over the locales for which there is plurals data. More...
static PluralRules * | internalForLocale (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 ()
| 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, Part 3.5 Language Plural Rules: https://www.unicode.org/reports/tr35/tr35-numbers.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

</p

The i, f, and v values are defined as follows:

- i to be the integer digits.
- f to be the visible fractional digits, 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

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 https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html

Definition at line 212 of file plurrule.h.

## Constructor & Destructor Documentation

## ◆ PluralRules() [1/2]

icu::PluralRules::PluralRules | ( | UErrorCode & | status | ) |

Constructor.

Parameters

  status | Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Stable:
  ICU 4.0

## ◆ PluralRules() [2/2]

icu::PluralRules::PluralRules | ( | const PluralRules & | other | ) |

Copy constructor.

Stable:
  ICU 4.0

## ◆ ~PluralRules()

virtual icu::PluralRules::~PluralRules | ( |  | ) |
| virtual

Destructor.

Stable:
  ICU 4.0

## Member Function Documentation

## ◆ clone()

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

Clone.

Stable:
  ICU 4.0

## ◆ createDefaultRules()

static PluralRules* icu::PluralRules::createDefaultRules | ( | UErrorCode & | status | ) |
| static

The default rules that accept any number.

Parameters

  status | Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns
  new PluralRules pointer. nullptr if there is an error.

Stable:
  ICU 4.0

## ◆ createRules()

static PluralRules* icu::PluralRules::createRules | ( | const UnicodeString & | description,
|  | UErrorCode & | status
| ) |  |
| static

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

Parameters

  description | rule description
  status | Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns
  new PluralRules pointer. nullptr if there is an error.

Stable:
  ICU 4.0

## ◆ createSharedInstance()

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.

## ◆ forLocale() [1/2]

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

  locale | The locale for which a `PluralRules` object is returned.
  status | Output 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

## ◆ forLocale() [2/2]

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

  locale | The locale for which a `PluralRules` object is returned.
  type | The plural type (e.g., cardinal or ordinal).
  status | Output 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

## ◆ getAllKeywordValues()

int32_t icu::PluralRules::getAllKeywordValues | ( | const UnicodeString & | keyword,
|  | double * | dest,
|  | int32_t | destCapacity,
|  | UErrorCode & | status
| ) |  |

Deprecated Function, does not produce useful results.

Originally intended to return 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

  keyword | The keyword.
  dest | Array into which to put the returned values. May be nullptr if destCapacity is 0.
  destCapacity | The capacity of the array, must be at least 0.
  status | The error code. Deprecated function, always sets U_UNSUPPORTED_ERROR.

Returns
  The count of values available, or -1. This count can be larger than destCapacity, but no more than destCapacity values will be written.

Deprecated:
  ICU 55

## ◆ getAvailableLocales()

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.

## ◆ getDynamicClassID()

virtual UClassID icu::PluralRules::getDynamicClassID | ( |  | ) | const
| overridevirtual

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

Stable:
  ICU 4.0

Reimplemented from icu::UObject.

## ◆ getKeywordOther()

UnicodeString icu::PluralRules::getKeywordOther | ( |  | ) | const

Returns keyword for default plural form.

Returns
  keyword for default plural form.

Stable:
  ICU 4.0

## ◆ getKeywords()

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

  status | Output 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

## ◆ getRules()

UnicodeString icu::PluralRules::getRules | ( |  | ) | const

Internal:
  Do not use.

This API is for internal use only.

## ◆ getSamples() [1/2]

int32_t icu::PluralRules::getSamples | ( | const UnicodeString & | keyword,
|  | DecimalQuantity * | dest,
|  | int32_t | destCapacity,
|  | UErrorCode & | status
| ) |  |

Internal-only function that returns DecimalQuantitys instead of doubles.

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

  keyword | The keyword.
  dest | Array into which to put the returned values. May be nullptr if destCapacity is 0.
  destCapacity | The capacity of the array, must be at least 0.
  status | The 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.)

Internal:
  Do not use. This API is for internal use only.

## ◆ getSamples() [2/2]

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

  keyword | The keyword.
  dest | Array into which to put the returned values. May be nullptr if destCapacity is 0.
  destCapacity | The capacity of the array, must be at least 0.
  status | The 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

## ◆ getStaticClassID()

static UClassID icu::PluralRules::getStaticClassID | ( |  | ) |
| static

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

Stable:
  ICU 4.0

## ◆ getUniqueKeywordValue()

double icu::PluralRules::getUniqueKeywordValue | ( | const UnicodeString & | keyword | ) |

Deprecated Function, does not return useful results.

Originally intended to return a unique value for this keyword if it exists, else the constant UPLRULES_NO_UNIQUE_VALUE.

Parameters

  keyword | The keyword.

Returns
  Stub deprecated function returns UPLRULES_NO_UNIQUE_VALUE always.

Deprecated:
  ICU 55

## ◆ internalForLocale()

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.

## ◆ isKeyword()

UBool icu::PluralRules::isKeyword | ( | const UnicodeString & | keyword | ) | const

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

Parameters

  keyword | the input keyword.

Returns
  true if the input keyword is defined. Otherwise, return false.

Stable:
  ICU 4.0

## ◆ operator!=()

bool icu::PluralRules::operator!= | ( | const PluralRules & | other | ) | const
| inline

Compares the inequality of two PluralRules objects.

Parameters

  other | The 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 547 of file plurrule.h.

References icu::operator==().

## ◆ operator=()

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

Assignment operator.

Stable:
  ICU 4.0

## ◆ operator==()

virtual bool icu::PluralRules::operator== | ( | const PluralRules & | other | ) | const
| virtual

Compares the equality of two PluralRules objects.

Parameters

  other | The 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

## ◆ select() [1/6]

UnicodeString icu::PluralRules::select | ( | const IFixedDecimal & | number | ) | const

Internal:
  Do not use.

This API is for internal use only.

## ◆ select() [2/6]

UnicodeString icu::PluralRules::select | ( | const number::FormattedNumber & | number,
|  | UErrorCode & | status
| ) |  | const

Given a formatted 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.

A FormattedNumber allows you to specify an exponent or trailing zeros, which can affect the plural category. To get a FormattedNumber, see NumberFormatter.

Parameters

  number | The number for which the rule has to be determined.
  status | Set if an error occurs while selecting plural keyword. This could happen if the FormattedNumber is invalid.

Returns
  The keyword of the selected rule.

Stable:
  ICU 64

## ◆ select() [3/6]

UnicodeString icu::PluralRules::select | ( | const number::FormattedNumberRange & | range,
|  | UErrorCode & | status
| ) |  | const

Given a formatted number range, returns the overall plural form of the range.

For example, "3-5" returns "other" in English.

To get a FormattedNumberRange, see NumberRangeFormatter.

This method only works if PluralRules was created with a locale. If it was created from PluralRules::createRules(), this method sets status code U_UNSUPPORTED_ERROR.

Parameters

  range | The number range onto which the rules will be applied.
  status | Set if an error occurs while selecting plural keyword. This could happen if the FormattedNumberRange is invalid, or if plural ranges data is unavailable.

Returns
  The keyword of the selected rule.

Stable:
  ICU 68

## ◆ select() [4/6]

UnicodeString icu::PluralRules::select | ( | const number::impl::UFormattedNumberRangeData * | urange,
|  | UErrorCode & | status
| ) |  | const

Internal:
  Do not use.

This API is for internal use only.

## ◆ select() [5/6]

UnicodeString icu::PluralRules::select | ( | double | number | ) | const

Given a floating-point 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

  number | The number for which the rule has to be determined.

Returns
  The keyword of the selected rule.

Stable:
  ICU 4.0

## ◆ select() [6/6]

UnicodeString icu::PluralRules::select | ( | int32_t | number | ) | const

Given an integer, 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

  number | The number for which the rule has to be determined.

Returns
  The keyword of the selected rule.

Stable:
  ICU 4.0

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

- i18n/unicode/plurrule.h