class PluralFormat

Defined at line 148 of file ../../third_party/icu/default/source/i18n/unicode/plurfmt.h

PluralFormat

supports the creation of internationalized

messages with plural inflection. It is based on

plural

selection

, i.e. the caller specifies messages for each

plural case that can appear in the user's language and the

PluralFormat

selects the appropriate message based on

the number.

The Problem of Plural Forms in Internationalized Messages

Different languages have different ways to inflect

plurals. Creating internationalized messages that include plural

forms is only feasible when the framework is able to handle plural

forms of

all

languages correctly.

ChoiceFormat

doesn't handle this well, because it attaches a number interval to

each message and selects the message whose interval contains a

given number. This can only handle a finite number of

intervals. But in some languages, like Polish, one plural case

applies to infinitely many intervals (e.g., the plural case applies to

numbers ending with 2, 3, or 4 except those ending with 12, 13, or

14). Thus

ChoiceFormat

is not adequate.

PluralFormat

deals with this by breaking the problem

into two parts:

It uses

PluralRules

that can define more complex

conditions for a plural case than just a single interval. These plural

rules define both what plural cases exist in a language, and to

which numbers these cases apply.

It provides predefined plural rules for many languages. Thus, the programmer

need not worry about the plural cases of a language and

does not have to define the plural cases; they can simply

use the predefined keywords. The whole plural formatting of messages can

be done using localized patterns from resource bundles. For predefined plural

rules, see the CLDR

Language Plural Rules

page at

https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html

Usage of

PluralFormat

Note: Typically, plural formatting is done via

MessageFormat

with a

plural

argument type,

rather than using a stand-alone

PluralFormat

This discussion assumes that you use

PluralFormat

with

a predefined set of plural rules. You can create one using one of

the constructors that takes a

locale

object. To

specify the message pattern, you can either pass it to the

constructor or set it explicitly using the

applyPattern()

method. The

format()

method takes a number object and selects the message of the

matching plural case. This message will be returned.

Patterns and Their Interpretation

The pattern text defines the message output for each plural case of the

specified locale. Syntax:

pluralStyle = [offsetValue] (selector '{' message '}')+

offsetValue = "offset:" number

selector = explicitValue | keyword

explicitValue = '=' number // adjacent, no white space in between

keyword = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+

message: see {

Public Methods

void PluralFormat (UErrorCode & status)

Creates a new cardinal-number

PluralFormat

for the default locale.

This locale will be used to get the set of plural rules and for standard

number formatting.

Parameters

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

void PluralFormat (const Locale & locale, UErrorCode & status)

Creates a new cardinal-number

PluralFormat

for a given locale.

Parameters

locale the PluralFormat will be configured with rules for this locale. This locale will also be used for standard number formatting.

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

void PluralFormat (const PluralRules & rules, UErrorCode & status)

Creates a new

PluralFormat

for a given set of rules.

The standard number formatting will be done using the default locale.

Parameters

rules defines the behavior of the PluralFormat object.

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

void PluralFormat (const Locale & locale, const PluralRules & rules, UErrorCode & status)

Creates a new

PluralFormat

for a given set of rules.

The standard number formatting will be done using the given locale.

Parameters

locale the default number formatting will be done using this locale.

rules defines the behavior of the PluralFormat object.

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

void PluralFormat (const Locale & locale, UPluralType type, UErrorCode & status)

Creates a new

PluralFormat

for the plural type.

The standard number formatting will be done using the given locale.

Parameters

locale the default number formatting will be done using this locale.

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. ICU 50

void PluralFormat (const UnicodeString & pattern, UErrorCode & status)

Creates a new cardinal-number

PluralFormat

for a given pattern string.

The default locale will be used to get the set of plural rules and for

standard number formatting.

Parameters

pattern the pattern for this PluralFormat. errors are returned to status if the pattern is invalid.

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

void PluralFormat (const Locale & locale, const UnicodeString & pattern, UErrorCode & status)

Creates a new cardinal-number

PluralFormat

for a given pattern string and

locale.

The locale will be used to get the set of plural rules and for

standard number formatting.

Parameters

locale the PluralFormat will be configured with rules for this locale. This locale will also be used for standard number formatting.

pattern the pattern for this PluralFormat. errors are returned to status if the pattern is invalid.

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

void PluralFormat (const PluralRules & rules, const UnicodeString & pattern, UErrorCode & status)

Creates a new

PluralFormat

for a given set of rules, a

pattern and a locale.

Parameters

rules defines the behavior of the PluralFormat object.

pattern the pattern for this PluralFormat. errors are returned to status if the pattern is invalid.

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

void PluralFormat (const Locale & locale, const PluralRules & rules, const UnicodeString & pattern, UErrorCode & status)

Creates a new

PluralFormat

for a given set of rules, a

pattern and a locale.

Parameters

locale the PluralFormat will be configured with rules for this locale. This locale will also be used for standard number formatting.

rules defines the behavior of the PluralFormat object.

pattern the pattern for this PluralFormat. errors are returned to status if the pattern is invalid.

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

void PluralFormat (const Locale & locale, UPluralType type, const UnicodeString & pattern, UErrorCode & status)

Creates a new

PluralFormat

for a plural type, a

pattern and a locale.

Parameters

locale the PluralFormat will be configured with rules for this locale. This locale will also be used for standard number formatting.

type The plural type (e.g., cardinal or ordinal).

pattern the pattern for this PluralFormat. errors are returned to status if the pattern is invalid.

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

void PluralFormat (const PluralFormat & other)

copy constructor.

ICU 4.0

void ~PluralFormat ()

Destructor.

ICU 4.0

void applyPattern (const UnicodeString & pattern, UErrorCode & status)

Sets the pattern used by this plural format.

The method parses the pattern and creates a map of format strings

for the plural rules.

Patterns and their interpretation are specified in the class description.

Parameters

pattern the pattern for this plural format errors are returned to status if the pattern is invalid.

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

UnicodeString format (int32_t number, UErrorCode & status)

Formats a plural message for a given number.

Parameters

number a number for which the plural message should be formatted for. If no pattern has been applied to thisPluralFormat object yet, the formatted number will be returned.

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

Returns

the string containing the formatted plural message.

ICU 4.0

UnicodeString format (double number, UErrorCode & status)

Formats a plural message for a given number.

Parameters

number a number for which the plural message should be formatted for. If no pattern has been applied to this PluralFormat object yet, the formatted number will be returned.

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

Returns

the string containing the formatted plural message.

ICU 4.0

UnicodeString & format (int32_t number, UnicodeString & appendTo, FieldPosition & pos, UErrorCode & status)

Formats a plural message for a given number.

Parameters

number a number for which the plural message should be formatted for. If no pattern has been applied to thisPluralFormat object yet, the formatted number will be returned.

appendTo output parameter to receive result. result is appended to existing contents.

pos On input: an alignment field, if desired. On output: the offsets of the alignment field.

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

Returns

the string containing the formatted plural message.

ICU 4.0

UnicodeString & format (double number, UnicodeString & appendTo, FieldPosition & pos, UErrorCode & status)

Formats a plural message for a given number.

Parameters

number a number for which the plural message should be formatted for. If no pattern has been applied to this PluralFormat object yet, the formatted number will be returned.

appendTo output parameter to receive result. result is appended to existing contents.

pos On input: an alignment field, if desired. On output: the offsets of the alignment field.

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

Returns

the string containing the formatted plural message.

ICU 4.0

void setLocale (const Locale & locale, UErrorCode & status)

Sets the locale used by this

PluraFormat

object.

Note: Calling this method resets this

PluraFormat

object,

i.e., a pattern that was applied previously will be removed,

and the NumberFormat is set to the default number format for

the locale. The resulting format behaves the same as one

constructed from {

void setNumberFormat (const NumberFormat * format, UErrorCode & status)

Sets the number format used by this formatter. You only need to

call this if you want a different number format than the default

formatter for the locale.

Parameters

format the number format to use.

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

PluralFormat & operator= (const PluralFormat & other)

Assignment operator

Parameters

other the PluralFormat object to copy from. ICU 4.0

bool operator== (const Format & other)

Return true if another object is semantically equal to this one.

Parameters

other the PluralFormat object to be compared with.

Returns

true if other is semantically equal to this.

ICU 4.0

bool operator!= (const Format & other)

Return true if another object is semantically unequal to this one.

Parameters

other the PluralFormat object to be compared with.

Returns

true if other is semantically unequal to this.

ICU 4.0

PluralFormat * clone ()

Clones this Format object polymorphically. The caller owns the

result and should delete it when done.

ICU 4.0

UnicodeString & format (const Formattable & obj, UnicodeString & appendTo, FieldPosition & pos, UErrorCode & status)

Formats a plural message for a number taken from a Formattable object.

Parameters

obj The object containing a number for which the plural message should be formatted. The object must be of a numeric type.

appendTo output parameter to receive result. Result is appended to existing contents.

pos On input: an alignment field, if desired. On output: the offsets of the alignment field.

status output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

ICU 4.0

UnicodeString & toPattern (UnicodeString & appendTo)

Returns the pattern from applyPattern() or constructor().

Parameters

appendTo output parameter to receive result. Result is appended to existing contents.

Returns

the UnicodeString with inserted pattern.

ICU 4.0

void parseObject (const UnicodeString & source, Formattable & result, ParsePosition & parse_pos)

This method is not yet supported by

PluralFormat

Before calling, set parse_pos.index to the offset you want to start

parsing at in the source. After calling, parse_pos.index is the end of

the text you parsed. If error occurs, index is unchanged.

When parsing, leading whitespace is discarded (with a successful parse),

while trailing whitespace is left as is.

See Format::parseObject() for more.

Parameters

source The string to be parsed into an object.

result Formattable to be set to the parse result. If parse fails, return contents are undefined.

parse_pos The position to start parsing at. Upon return this param is set to the position after the last character successfully parsed. If the source is not parsed successfully, this param will remain unchanged. ICU 4.0

UClassID getStaticClassID ()

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

ICU 4.0

UClassID getDynamicClassID ()

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

ICU 4.0

Friends

class NFRule

class MessageFormat