1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 *******************************************************************************
5 * Copyright (C) 2007-2014, International Business Machines Corporation and
6 * others. All Rights Reserved.
7 *******************************************************************************
11 ********************************************************************************
17 #include "unicode/utypes.h"
21 * \brief C++ API: PluralFormat object
24 #if !UCONFIG_NO_FORMATTING
26 #include "unicode/messagepattern.h"
27 #include "unicode/numfmt.h"
28 #include "unicode/plurrule.h"
37 * <code>PluralFormat</code> supports the creation of internationalized
38 * messages with plural inflection. It is based on <i>plural
39 * selection</i>, i.e. the caller specifies messages for each
40 * plural case that can appear in the user's language and the
41 * <code>PluralFormat</code> selects the appropriate message based on
44 * <h4>The Problem of Plural Forms in Internationalized Messages</h4>
46 * Different languages have different ways to inflect
47 * plurals. Creating internationalized messages that include plural
48 * forms is only feasible when the framework is able to handle plural
49 * forms of <i>all</i> languages correctly. <code>ChoiceFormat</code>
50 * doesn't handle this well, because it attaches a number interval to
51 * each message and selects the message whose interval contains a
52 * given number. This can only handle a finite number of
53 * intervals. But in some languages, like Polish, one plural case
54 * applies to infinitely many intervals (e.g., the plural case applies to
55 * numbers ending with 2, 3, or 4 except those ending with 12, 13, or
56 * 14). Thus <code>ChoiceFormat</code> is not adequate.
58 * <code>PluralFormat</code> deals with this by breaking the problem
61 * <li>It uses <code>PluralRules</code> that can define more complex
62 * conditions for a plural case than just a single interval. These plural
63 * rules define both what plural cases exist in a language, and to
64 * which numbers these cases apply.
65 * <li>It provides predefined plural rules for many languages. Thus, the programmer
66 * need not worry about the plural cases of a language and
67 * does not have to define the plural cases; they can simply
68 * use the predefined keywords. The whole plural formatting of messages can
69 * be done using localized patterns from resource bundles. For predefined plural
70 * rules, see the CLDR <i>Language Plural Rules</i> page at
71 * http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html
74 * <h4>Usage of <code>PluralFormat</code></h4>
75 * <p>Note: Typically, plural formatting is done via <code>MessageFormat</code>
76 * with a <code>plural</code> argument type,
77 * rather than using a stand-alone <code>PluralFormat</code>.
79 * This discussion assumes that you use <code>PluralFormat</code> with
80 * a predefined set of plural rules. You can create one using one of
81 * the constructors that takes a <code>locale</code> object. To
82 * specify the message pattern, you can either pass it to the
83 * constructor or set it explicitly using the
84 * <code>applyPattern()</code> method. The <code>format()</code>
85 * method takes a number object and selects the message of the
86 * matching plural case. This message will be returned.
88 * <h5>Patterns and Their Interpretation</h5>
90 * The pattern text defines the message output for each plural case of the
91 * specified locale. Syntax:
93 * pluralStyle = [offsetValue] (selector '{' message '}')+
94 * offsetValue = "offset:" number
95 * selector = explicitValue | keyword
96 * explicitValue = '=' number // adjacent, no white space in between
97 * keyword = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+
98 * message: see {@link MessageFormat}
100 * Pattern_White_Space between syntax elements is ignored, except
101 * between the {curly braces} and their sub-message,
102 * and between the '=' and the number of an explicitValue.
105 * There are 6 predefined casekeyword in CLDR/ICU - 'zero', 'one', 'two', 'few', 'many' and
106 * 'other'. You always have to define a message text for the default plural case
107 * <code>other</code> which is contained in every rule set.
108 * If you do not specify a message text for a particular plural case, the
109 * message text of the plural case <code>other</code> gets assigned to this
112 * When formatting, the input number is first matched against the explicitValue clauses.
113 * If there is no exact-number match, then a keyword is selected by calling
114 * the <code>PluralRules</code> with the input number <em>minus the offset</em>.
115 * (The offset defaults to 0 if it is omitted from the pattern string.)
116 * If there is no clause with that keyword, then the "other" clauses is returned.
118 * An unquoted pound sign (<code>#</code>) in the selected sub-message
119 * itself (i.e., outside of arguments nested in the sub-message)
120 * is replaced by the input number minus the offset.
121 * The number-minus-offset value is formatted using a
122 * <code>NumberFormat</code> for the <code>PluralFormat</code>'s locale. If you
123 * need special number formatting, you have to use a <code>MessageFormat</code>
124 * and explicitly specify a <code>NumberFormat</code> argument.
125 * <strong>Note:</strong> That argument is formatting without subtracting the offset!
126 * If you need a custom format and have a non-zero offset, then you need to pass the
127 * number-minus-offset value as a separate parameter.
129 * For a usage example, see the {@link MessageFormat} class documentation.
131 * <h4>Defining Custom Plural Rules</h4>
132 * <p>If you need to use <code>PluralFormat</code> with custom rules, you can
133 * create a <code>PluralRules</code> object and pass it to
134 * <code>PluralFormat</code>'s constructor. If you also specify a locale in this
135 * constructor, this locale will be used to format the number in the message
138 * For more information about <code>PluralRules</code>, see
139 * {@link PluralRules}.
146 class U_I18N_API PluralFormat : public Format {
150 * Creates a new cardinal-number <code>PluralFormat</code> for the default locale.
151 * This locale will be used to get the set of plural rules and for standard
153 * @param status output param set to success/failure code on exit, which
154 * must not indicate a failure before the function call.
157 PluralFormat(UErrorCode& status);
160 * Creates a new cardinal-number <code>PluralFormat</code> for a given locale.
161 * @param locale the <code>PluralFormat</code> will be configured with
162 * rules for this locale. This locale will also be used for
163 * standard number formatting.
164 * @param status output param set to success/failure code on exit, which
165 * must not indicate a failure before the function call.
168 PluralFormat(const Locale& locale, UErrorCode& status);
171 * Creates a new <code>PluralFormat</code> for a given set of rules.
172 * The standard number formatting will be done using the default locale.
173 * @param rules defines the behavior of the <code>PluralFormat</code>
175 * @param status output param set to success/failure code on exit, which
176 * must not indicate a failure before the function call.
179 PluralFormat(const PluralRules& rules, UErrorCode& status);
182 * Creates a new <code>PluralFormat</code> for a given set of rules.
183 * The standard number formatting will be done using the given locale.
184 * @param locale the default number formatting will be done using this
186 * @param rules defines the behavior of the <code>PluralFormat</code>
188 * @param status output param set to success/failure code on exit, which
189 * must not indicate a failure before the function call.
192 * <h4>Sample code</h4>
193 * \snippet samples/plurfmtsample/plurfmtsample.cpp PluralFormatExample1
194 * \snippet samples/plurfmtsample/plurfmtsample.cpp PluralFormatExample
197 PluralFormat(const Locale& locale, const PluralRules& rules, UErrorCode& status);
200 * Creates a new <code>PluralFormat</code> for the plural type.
201 * The standard number formatting will be done using the given locale.
202 * @param locale the default number formatting will be done using this
204 * @param type The plural type (e.g., cardinal or ordinal).
205 * @param status output param set to success/failure code on exit, which
206 * must not indicate a failure before the function call.
209 PluralFormat(const Locale& locale, UPluralType type, UErrorCode& status);
212 * Creates a new cardinal-number <code>PluralFormat</code> for a given pattern string.
213 * The default locale will be used to get the set of plural rules and for
214 * standard number formatting.
215 * @param pattern the pattern for this <code>PluralFormat</code>.
216 * errors are returned to status if the pattern is invalid.
217 * @param status output param set to success/failure code on exit, which
218 * must not indicate a failure before the function call.
221 PluralFormat(const UnicodeString& pattern, UErrorCode& status);
224 * Creates a new cardinal-number <code>PluralFormat</code> for a given pattern string and
226 * The locale will be used to get the set of plural rules and for
227 * standard number formatting.
228 * @param locale the <code>PluralFormat</code> will be configured with
229 * rules for this locale. This locale will also be used for
230 * standard number formatting.
231 * @param pattern the pattern for this <code>PluralFormat</code>.
232 * errors are returned to status if the pattern is invalid.
233 * @param status output param set to success/failure code on exit, which
234 * must not indicate a failure before the function call.
237 PluralFormat(const Locale& locale, const UnicodeString& pattern, UErrorCode& status);
240 * Creates a new <code>PluralFormat</code> for a given set of rules, a
241 * pattern and a locale.
242 * @param rules defines the behavior of the <code>PluralFormat</code>
244 * @param pattern the pattern for this <code>PluralFormat</code>.
245 * errors are returned to status if the pattern is invalid.
246 * @param status output param set to success/failure code on exit, which
247 * must not indicate a failure before the function call.
250 PluralFormat(const PluralRules& rules,
251 const UnicodeString& pattern,
255 * Creates a new <code>PluralFormat</code> for a given set of rules, a
256 * pattern and a locale.
257 * @param locale the <code>PluralFormat</code> will be configured with
258 * rules for this locale. This locale will also be used for
259 * standard number formatting.
260 * @param rules defines the behavior of the <code>PluralFormat</code>
262 * @param pattern the pattern for this <code>PluralFormat</code>.
263 * errors are returned to status if the pattern is invalid.
264 * @param status output param set to success/failure code on exit, which
265 * must not indicate a failure before the function call.
268 PluralFormat(const Locale& locale,
269 const PluralRules& rules,
270 const UnicodeString& pattern,
274 * Creates a new <code>PluralFormat</code> for a plural type, a
275 * pattern and a locale.
276 * @param locale the <code>PluralFormat</code> will be configured with
277 * rules for this locale. This locale will also be used for
278 * standard number formatting.
279 * @param type The plural type (e.g., cardinal or ordinal).
280 * @param pattern the pattern for this <code>PluralFormat</code>.
281 * errors are returned to status if the pattern is invalid.
282 * @param status output param set to success/failure code on exit, which
283 * must not indicate a failure before the function call.
286 PluralFormat(const Locale& locale,
288 const UnicodeString& pattern,
295 PluralFormat(const PluralFormat& other);
301 virtual ~PluralFormat();
304 * Sets the pattern used by this plural format.
305 * The method parses the pattern and creates a map of format strings
306 * for the plural rules.
307 * Patterns and their interpretation are specified in the class description.
309 * @param pattern the pattern for this plural format
310 * errors are returned to status if the pattern is invalid.
311 * @param status output param set to success/failure code on exit, which
312 * must not indicate a failure before the function call.
315 void applyPattern(const UnicodeString& pattern, UErrorCode& status);
318 using Format::format;
321 * Formats a plural message for a given number.
323 * @param number a number for which the plural message should be formatted
324 * for. If no pattern has been applied to this
325 * <code>PluralFormat</code> object yet, the formatted number
327 * @param status output param set to success/failure code on exit, which
328 * must not indicate a failure before the function call.
329 * @return the string containing the formatted plural message.
332 UnicodeString format(int32_t number, UErrorCode& status) const;
335 * Formats a plural message for a given number.
337 * @param number a number for which the plural message should be formatted
338 * for. If no pattern has been applied to this
339 * PluralFormat object yet, the formatted number
341 * @param status output param set to success or failure code on exit, which
342 * must not indicate a failure before the function call.
343 * @return the string containing the formatted plural message.
346 UnicodeString format(double number, UErrorCode& status) const;
349 * Formats a plural message for a given number.
351 * @param number a number for which the plural message should be formatted
352 * for. If no pattern has been applied to this
353 * <code>PluralFormat</code> object yet, the formatted number
355 * @param appendTo output parameter to receive result.
356 * result is appended to existing contents.
357 * @param pos On input: an alignment field, if desired.
358 * On output: the offsets of the alignment field.
359 * @param status output param set to success/failure code on exit, which
360 * must not indicate a failure before the function call.
361 * @return the string containing the formatted plural message.
364 UnicodeString& format(int32_t number,
365 UnicodeString& appendTo,
367 UErrorCode& status) const;
370 * Formats a plural message for a given number.
372 * @param number a number for which the plural message should be formatted
373 * for. If no pattern has been applied to this
374 * PluralFormat object yet, the formatted number
376 * @param appendTo output parameter to receive result.
377 * result is appended to existing contents.
378 * @param pos On input: an alignment field, if desired.
379 * On output: the offsets of the alignment field.
380 * @param status output param set to success/failure code on exit, which
381 * must not indicate a failure before the function call.
382 * @return the string containing the formatted plural message.
385 UnicodeString& format(double number,
386 UnicodeString& appendTo,
388 UErrorCode& status) const;
390 #ifndef U_HIDE_DEPRECATED_API
392 * Sets the locale used by this <code>PluraFormat</code> object.
393 * Note: Calling this method resets this <code>PluraFormat</code> object,
394 * i.e., a pattern that was applied previously will be removed,
395 * and the NumberFormat is set to the default number format for
396 * the locale. The resulting format behaves the same as one
397 * constructed from {@link #PluralFormat(const Locale& locale, UPluralType type, UErrorCode& status)}
398 * with UPLURAL_TYPE_CARDINAL.
399 * @param locale the <code>locale</code> to use to configure the formatter.
400 * @param status output param set to success/failure code on exit, which
401 * must not indicate a failure before the function call.
402 * @deprecated ICU 50 This method clears the pattern and might create
403 * a different kind of PluralRules instance;
404 * use one of the constructors to create a new instance instead.
406 void setLocale(const Locale& locale, UErrorCode& status);
407 #endif /* U_HIDE_DEPRECATED_API */
410 * Sets the number format used by this formatter. You only need to
411 * call this if you want a different number format than the default
412 * formatter for the locale.
413 * @param format the number format to use.
414 * @param status output param set to success/failure code on exit, which
415 * must not indicate a failure before the function call.
418 void setNumberFormat(const NumberFormat* format, UErrorCode& status);
421 * Assignment operator
423 * @param other the PluralFormat object to copy from.
426 PluralFormat& operator=(const PluralFormat& other);
429 * Return true if another object is semantically equal to this one.
431 * @param other the PluralFormat object to be compared with.
432 * @return true if other is semantically equal to this.
435 virtual UBool operator==(const Format& other) const;
438 * Return true if another object is semantically unequal to this one.
440 * @param other the PluralFormat object to be compared with.
441 * @return true if other is semantically unequal to this.
444 virtual UBool operator!=(const Format& other) const;
447 * Clones this Format object polymorphically. The caller owns the
448 * result and should delete it when done.
451 virtual Format* clone(void) const;
454 * Formats a plural message for a number taken from a Formattable object.
456 * @param obj The object containing a number for which the
457 * plural message should be formatted.
458 * The object must be of a numeric type.
459 * @param appendTo output parameter to receive result.
460 * Result is appended to existing contents.
461 * @param pos On input: an alignment field, if desired.
462 * On output: the offsets of the alignment field.
463 * @param status output param filled with success/failure status.
464 * @return Reference to 'appendTo' parameter.
467 UnicodeString& format(const Formattable& obj,
468 UnicodeString& appendTo,
470 UErrorCode& status) const;
473 * Returns the pattern from applyPattern() or constructor().
475 * @param appendTo output parameter to receive result.
476 * Result is appended to existing contents.
477 * @return the UnicodeString with inserted pattern.
480 UnicodeString& toPattern(UnicodeString& appendTo);
483 * This method is not yet supported by <code>PluralFormat</code>.
485 * Before calling, set parse_pos.index to the offset you want to start
486 * parsing at in the source. After calling, parse_pos.index is the end of
487 * the text you parsed. If error occurs, index is unchanged.
489 * When parsing, leading whitespace is discarded (with a successful parse),
490 * while trailing whitespace is left as is.
492 * See Format::parseObject() for more.
494 * @param source The string to be parsed into an object.
495 * @param result Formattable to be set to the parse result.
496 * If parse fails, return contents are undefined.
497 * @param parse_pos The position to start parsing at. Upon return
498 * this param is set to the position after the
499 * last character successfully parsed. If the
500 * source is not parsed successfully, this param
501 * will remain unchanged.
504 virtual void parseObject(const UnicodeString& source,
506 ParsePosition& parse_pos) const;
509 * ICU "poor man's RTTI", returns a UClassID for this class.
514 static UClassID U_EXPORT2 getStaticClassID(void);
517 * ICU "poor man's RTTI", returns a UClassID for the actual class.
521 virtual UClassID getDynamicClassID() const;
523 #if (defined(__xlC__) && (__xlC__ < 0x0C00)) || (U_PLATFORM == U_PF_OS390) || (U_PLATFORM ==U_PF_OS400)
524 // Work around a compiler bug on xlC 11.1 on AIX 7.1 that would
525 // prevent PluralSelectorAdapter from implementing private PluralSelector.
526 // xlC error message:
527 // 1540-0300 (S) The "private" member "class icu_49::PluralFormat::PluralSelector" cannot be accessed.
535 class U_I18N_API PluralSelector : public UMemory {
537 virtual ~PluralSelector();
539 * Given a number, returns the appropriate PluralFormat keyword.
541 * @param context worker object for the selector.
542 * @param number The number to be plural-formatted.
543 * @param ec Error code.
544 * @return The selected PluralFormat keyword.
547 virtual UnicodeString select(void *context, double number, UErrorCode& ec) const = 0;
553 class U_I18N_API PluralSelectorAdapter : public PluralSelector {
555 PluralSelectorAdapter() : pluralRules(NULL) {
558 virtual ~PluralSelectorAdapter();
560 virtual UnicodeString select(void *context, double number, UErrorCode& /*ec*/) const; /**< @internal */
564 PluralRules* pluralRules;
568 // End of xlC bug workaround, keep remaining definitions private.
572 MessagePattern msgPattern;
573 NumberFormat* numberFormat;
575 PluralSelectorAdapter pluralRulesWrapper;
577 PluralFormat(); // default constructor not implemented
578 void init(const PluralRules* rules, UPluralType type, UErrorCode& status);
580 * Copies dynamically allocated values (pointer fields).
581 * Others are copied using their copy constructors and assignment operators.
583 void copyObjects(const PluralFormat& other);
585 UnicodeString& format(const Formattable& numberObject, double number,
586 UnicodeString& appendTo,
588 UErrorCode& status) const; /**< @internal */
591 * Finds the PluralFormat sub-message for the given number, or the "other" sub-message.
592 * @param pattern A MessagePattern.
593 * @param partIndex the index of the first PluralFormat argument style part.
594 * @param selector the PluralSelector for mapping the number (minus offset) to a keyword.
595 * @param context worker object for the selector.
596 * @param number a number to be matched to one of the PluralFormat argument's explicit values,
597 * or mapped via the PluralSelector.
598 * @param ec ICU error code.
599 * @return the sub-message start part index.
601 static int32_t findSubMessage(
602 const MessagePattern& pattern, int32_t partIndex,
603 const PluralSelector& selector, void *context, double number, UErrorCode& ec); /**< @internal */
605 void parseType(const UnicodeString& source, const NFRule *rbnfLenientScanner,
606 Formattable& result, FieldPosition& pos) const;
608 friend class MessageFormat;
614 #endif /* #if !UCONFIG_NO_FORMATTING */