Logo Search packages:      
Sourcecode: icu version File versions  Download package

PluralFormat Class Reference

#include <plurfmt.h>

Inheritance diagram for PluralFormat:

Format UObject UMemory

List of all members.

Detailed Description

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 users 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., paucal 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:

Usage of 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 used locale. The pattern is a sequence of caseKeyword{message} clauses, separated by white space characters. Each clause assigns the message message to the plural case identified by caseKeyword.

You always have to define a message text for the default plural case "<code>other</code>" which is contained in every rule set. If the plural rules of the PluralFormat object do not contain a plural case identified by caseKeyword, U_DEFAULT_KEYWORD_MISSING will be set to status. If you do not specify a message text for a particular plural case, the message text of the plural case "<code>other</code>" gets assigned to this plural case. If you specify more than one message for the same plural case, U_DUPLICATE_KEYWORD will be set to status.
Spaces between caseKeyword and message will be ignored; spaces within message will be preserved.

The message text for a particular plural case may contain other message format patterns. PluralFormat preserves these so that you can use the strings produced by PluralFormat with other formatters. If you are using PluralFormat inside a MessageFormat pattern, MessageFormat will automatically evaluate the resulting format pattern.
Thus, curly braces ({, }) are only allowed in message texts to define a nested format pattern.
The pound sign (#) will be interpreted as the number placeholder in the message text, if it is not contained in curly braces (to preserve NumberFormat patterns). PluralFormat will replace each of those pound signs by the number passed to the format() method. It will be formatted using a NumberFormat for the PluralFormat's locale. If you need special number formatting, you have to explicitly specify a NumberFormat for the PluralFormat to use. Example

 UErrorCode status = U_ZERO_ERROR;
 MessageFormat* msgFmt = new MessageFormat(UnicodeString("{0, plural,
   one{{0, number, C''est #,##0.0#  fichier}} other {Ce sont # fichiers}} dans la liste."),
   Locale("fr"), status);
 if (U_FAILURE(status)) {
 Formattable args1[] = {(int32_t)0};
 Formattable args2[] = {(int32_t)3};
 FieldPosition ignore(FieldPosition::DONT_CARE);
 UnicodeString result;
 msgFmt->format(args1, 1, result, ignore, status);
 cout << result << endl;
 msgFmt->format(args2, 1, result, ignore, status);
 cout << result << endl;
Produces the output:
C'est 0,0 fichier dans la liste.
Ce sont 3 fichiers dans la liste."

Currently PluralFormat does not make use of quotes like MessageFormat. If you use plural format strings with MessageFormat and want to use a quote sign "<code>'</code>", you have to write "<code>''</code>". MessageFormat unquotes this pattern and passes the unquoted pattern to PluralFormat. It's a bit trickier if you use nested formats that do quoting. In the example above, we wanted to insert "<code>'</code>" in the number format pattern. Since NumberFormat supports quotes, we had to insert "<code>''</code>". But since MessageFormat unquotes the pattern before it gets passed to PluralFormat, we have to double these quotes, i.e. write "<code>''''</code>".

Defining Custom Plural Rules

If you need to use PluralFormat with custom rules, you can create a PluralRules object and pass it to PluralFormat's constructor. If you also specify a locale in this constructor, this locale will be used to format the number in the message texts.

For more information about PluralRules, see PluralRules.

ported from Java ICU 4.0

Definition at line 174 of file plurfmt.h.

Public Member Functions

void applyPattern (const UnicodeString &pattern, UErrorCode &status)
virtual Formatclone (void) const
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
UnicodeString format (double number, UErrorCode &status) const
UnicodeString format (int32_t number, UErrorCode &status) const
virtual UClassID getDynamicClassID () const
Locale getLocale (ULocDataLocaleType type, UErrorCode &status) const
const char * getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
virtual UBool operator!= (const Format &other) const
PluralFormatoperator= (const PluralFormat &other)
virtual UBool operator== (const Format &other) const
void parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
virtual void parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const
 PluralFormat (const PluralFormat &other)
 PluralFormat (const Locale &locale, const PluralRules &rules, const UnicodeString &pattern, UErrorCode &status)
 PluralFormat (const PluralRules &rules, const UnicodeString &pattern, UErrorCode &status)
 PluralFormat (const Locale &locale, const UnicodeString &pattern, UErrorCode &status)
 PluralFormat (const UnicodeString &pattern, UErrorCode &status)
 PluralFormat (const Locale &locale, const PluralRules &rules, UErrorCode &status)
 PluralFormat (const PluralRules &rules, UErrorCode &status)
 PluralFormat (const Locale &locale, UErrorCode &status)
 PluralFormat (UErrorCode &status)
void setLocale (const Locale &locale, UErrorCode &status)
void setNumberFormat (const NumberFormat *format, UErrorCode &status)
UnicodeStringtoPattern (UnicodeString &appendTo)
virtual ~PluralFormat ()

Static Public Member Functions

static UClassID U_EXPORT2 getStaticClassID (void)
static void U_EXPORT2 operator delete (void *, void *) U_NO_THROW
static void U_EXPORT2 operator delete (void *p) U_NO_THROW
static void U_EXPORT2 operator delete[] (void *p) U_NO_THROW
static void *U_EXPORT2 operator new (size_t, void *ptr) U_NO_THROW
static void *U_EXPORT2 operator new (size_t size) U_NO_THROW
static void *U_EXPORT2 operator new[] (size_t size) U_NO_THROW

Protected Member Functions

void setLocaleIDs (const char *valid, const char *actual)

Static Protected Member Functions

static void syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)

Private Types

typedef enum PluralFormat::fmtToken fmtToken
enum  fmtToken {
  none, tLetter, tNumber, tSpace,
  tNumberSign, tLeftBrace, tRightBrace

Private Member Functions

UBool checkSufficientDefinition ()
void copyHashtable (Hashtable *other, UErrorCode &status)
void init (const PluralRules *rules, const Locale &curlocale, UErrorCode &status)
UBool inRange (UChar ch, fmtToken &type)
UnicodeString insertFormattedNumber (double number, UnicodeString &message, UnicodeString &appendTo, FieldPosition &pos) const
void parsingFailure ()

Private Attributes

Locale locale
UnicodeString pattern

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

Generated by  Doxygen 1.6.0   Back to index