icuSources/i18n/unicode/plurfmt.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 * Copyright (C) 2007-2014, International Business Machines Corporation and
   6 * others. All Rights Reserved.
   7 *******************************************************************************
   8 *
   9
  10 * File PLURFMT.H
  11 ********************************************************************************
  12 */
  13
  14 #ifndef PLURFMT
  15 #define PLURFMT
  16
  17 #include "unicode/utypes.h"
  18
  19 /**
  20  * \file
  21  * \brief C++ API: PluralFormat object
  22  */
  23
  24 #if !UCONFIG_NO_FORMATTING
  25
  26 #include "unicode/messagepattern.h"
  27 #include "unicode/numfmt.h"
  28 #include "unicode/plurrule.h"
  29
  30 #if U_SHOW_CPLUSPLUS_API
  31 U_NAMESPACE_BEGIN
  32
  33 class Hashtable;
  34 class NFRule;
  35
  36 /**
  37  * <p>
  38  * <code>PluralFormat</code> supports the creation of internationalized
  39  * messages with plural inflection. It is based on <i>plural
  40  * selection</i>, i.e. the caller specifies messages for each
  41  * plural case that can appear in the user's language and the
  42  * <code>PluralFormat</code> selects the appropriate message based on
  43  * the number.
  44  * </p>
  45  * <h4>The Problem of Plural Forms in Internationalized Messages</h4>
  46  * <p>
  47  * Different languages have different ways to inflect
  48  * plurals. Creating internationalized messages that include plural
  49  * forms is only feasible when the framework is able to handle plural
  50  * forms of <i>all</i> languages correctly. <code>ChoiceFormat</code>
  51  * doesn't handle this well, because it attaches a number interval to
  52  * each message and selects the message whose interval contains a
  53  * given number. This can only handle a finite number of
  54  * intervals. But in some languages, like Polish, one plural case
  55  * applies to infinitely many intervals (e.g., the plural case applies to
  56  * numbers ending with 2, 3, or 4 except those ending with 12, 13, or
  57  * 14). Thus <code>ChoiceFormat</code> is not adequate.
  58  * </p><p>
  59  * <code>PluralFormat</code> deals with this by breaking the problem
  60  * into two parts:
  61  * <ul>
  62  * <li>It uses <code>PluralRules</code> that can define more complex
  63  *     conditions for a plural case than just a single interval. These plural
  64  *     rules define both what plural cases exist in a language, and to
  65  *     which numbers these cases apply.
  66  * <li>It provides predefined plural rules for many languages. Thus, the programmer
  67  *     need not worry about the plural cases of a language and
  68  *     does not have to define the plural cases; they can simply
  69  *     use the predefined keywords. The whole plural formatting of messages can
  70  *     be done using localized patterns from resource bundles. For predefined plural
  71  *     rules, see the CLDR <i>Language Plural Rules</i> page at
  72  *    http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html
  73  * </ul>
  74  * </p>
  75  * <h4>Usage of <code>PluralFormat</code></h4>
  76  * <p>Note: Typically, plural formatting is done via <code>MessageFormat</code>
  77  * with a <code>plural</code> argument type,
  78  * rather than using a stand-alone <code>PluralFormat</code>.
  79  * </p><p>
  80  * This discussion assumes that you use <code>PluralFormat</code> with
  81  * a predefined set of plural rules. You can create one using one of
  82  * the constructors that takes a <code>locale</code> object. To
  83  * specify the message pattern, you can either pass it to the
  84  * constructor or set it explicitly using the
  85  * <code>applyPattern()</code> method. The <code>format()</code>
  86  * method takes a number object and selects the message of the
  87  * matching plural case. This message will be returned.
  88  * </p>
  89  * <h5>Patterns and Their Interpretation</h5>
  90  * <p>
  91  * The pattern text defines the message output for each plural case of the
  92  * specified locale. Syntax:
  93  * <pre>
  94  * pluralStyle = [offsetValue] (selector '{' message '}')+
  95  * offsetValue = "offset:" number
  96  * selector = explicitValue | keyword
  97  * explicitValue = '=' number  // adjacent, no white space in between
  98  * keyword = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+
  99  * message: see {@link MessageFormat}
 100  * </pre>
 101  * Pattern_White_Space between syntax elements is ignored, except
 102  * between the {curly braces} and their sub-message,
 103  * and between the '=' and the number of an explicitValue.
 104  *
 105  * </p><p>
 106  * There are 6 predefined casekeyword in CLDR/ICU - 'zero', 'one', 'two', 'few', 'many' and
 107  * 'other'. You always have to define a message text for the default plural case
 108  * <code>other</code> which is contained in every rule set.
 109  * If you do not specify a message text for a particular plural case, the
 110  * message text of the plural case <code>other</code> gets assigned to this
 111  * plural case.
 112  * </p><p>
 113  * When formatting, the input number is first matched against the explicitValue clauses.
 114  * If there is no exact-number match, then a keyword is selected by calling
 115  * the <code>PluralRules</code> with the input number <em>minus the offset</em>.
 116  * (The offset defaults to 0 if it is omitted from the pattern string.)
 117  * If there is no clause with that keyword, then the "other" clauses is returned.
 118  * </p><p>
 119  * An unquoted pound sign (<code>#</code>) in the selected sub-message
 120  * itself (i.e., outside of arguments nested in the sub-message)
 121  * is replaced by the input number minus the offset.
 122  * The number-minus-offset value is formatted using a
 123  * <code>NumberFormat</code> for the <code>PluralFormat</code>'s locale. If you
 124  * need special number formatting, you have to use a <code>MessageFormat</code>
 125  * and explicitly specify a <code>NumberFormat</code> argument.
 126  * <strong>Note:</strong> That argument is formatting without subtracting the offset!
 127  * If you need a custom format and have a non-zero offset, then you need to pass the
 128  * number-minus-offset value as a separate parameter.
 129  * </p>
 130  * For a usage example, see the {@link MessageFormat} class documentation.
 131  *
 132  * <h4>Defining Custom Plural Rules</h4>
 133  * <p>If you need to use <code>PluralFormat</code> with custom rules, you can
 134  * create a <code>PluralRules</code> object and pass it to
 135  * <code>PluralFormat</code>'s constructor. If you also specify a locale in this
 136  * constructor, this locale will be used to format the number in the message
 137  * texts.
 138  * </p><p>
 139  * For more information about <code>PluralRules</code>, see
 140  * {@link PluralRules}.
 141  * </p>
 142  *
 143  * ported from Java
 144  * @stable ICU 4.0
 145  */
 146
 147 class U_I18N_API PluralFormat : public Format {
 148 public:
 149
 150     /**
 151      * Creates a new cardinal-number <code>PluralFormat</code> for the default locale.
 152      * This locale will be used to get the set of plural rules and for standard
 153      * number formatting.
 154      * @param status  output param set to success/failure code on exit, which
 155      *                must not indicate a failure before the function call.
 156      * @stable ICU 4.0
 157      */
 158     PluralFormat(UErrorCode& status);
 159
 160     /**
 161      * Creates a new cardinal-number <code>PluralFormat</code> for a given locale.
 162      * @param locale the <code>PluralFormat</code> will be configured with
 163      *               rules for this locale. This locale will also be used for
 164      *               standard number formatting.
 165      * @param status output param set to success/failure code on exit, which
 166      *               must not indicate a failure before the function call.
 167      * @stable ICU 4.0
 168      */
 169     PluralFormat(const Locale& locale, UErrorCode& status);
 170
 171     /**
 172      * Creates a new <code>PluralFormat</code> for a given set of rules.
 173      * The standard number formatting will be done using the default locale.
 174      * @param rules   defines the behavior of the <code>PluralFormat</code>
 175      *                object.
 176      * @param status  output param set to success/failure code on exit, which
 177      *                must not indicate a failure before the function call.
 178      * @stable ICU 4.0
 179      */
 180     PluralFormat(const PluralRules& rules, UErrorCode& status);
 181
 182     /**
 183      * Creates a new <code>PluralFormat</code> for a given set of rules.
 184      * The standard number formatting will be done using the given locale.
 185      * @param locale  the default number formatting will be done using this
 186      *                locale.
 187      * @param rules   defines the behavior of the <code>PluralFormat</code>
 188      *                object.
 189      * @param status  output param set to success/failure code on exit, which
 190      *                must not indicate a failure before the function call.
 191      * @stable ICU 4.0
 192          * <p>
 193          * <h4>Sample code</h4>
 194          * \snippet samples/plurfmtsample/plurfmtsample.cpp PluralFormatExample1
 195          * \snippet samples/plurfmtsample/plurfmtsample.cpp PluralFormatExample
 196          * <p>
 197      */
 198     PluralFormat(const Locale& locale, const PluralRules& rules, UErrorCode& status);
 199
 200     /**
 201      * Creates a new <code>PluralFormat</code> for the plural type.
 202      * The standard number formatting will be done using the given locale.
 203      * @param locale  the default number formatting will be done using this
 204      *                locale.
 205      * @param type    The plural type (e.g., cardinal or ordinal).
 206      * @param status  output param set to success/failure code on exit, which
 207      *                must not indicate a failure before the function call.
 208      * @stable ICU 50
 209      */
 210     PluralFormat(const Locale& locale, UPluralType type, UErrorCode& status);
 211
 212     /**
 213      * Creates a new cardinal-number <code>PluralFormat</code> for a given pattern string.
 214      * The default locale will be used to get the set of plural rules and for
 215      * standard number formatting.
 216      * @param  pattern the pattern for this <code>PluralFormat</code>.
 217      *                 errors are returned to status if the pattern is invalid.
 218      * @param status   output param set to success/failure code on exit, which
 219      *                 must not indicate a failure before the function call.
 220      * @stable ICU 4.0
 221      */
 222     PluralFormat(const UnicodeString& pattern, UErrorCode& status);
 223
 224     /**
 225      * Creates a new cardinal-number <code>PluralFormat</code> for a given pattern string and
 226      * locale.
 227      * The locale will be used to get the set of plural rules and for
 228      * standard number formatting.
 229      * @param locale   the <code>PluralFormat</code> will be configured with
 230      *                 rules for this locale. This locale will also be used for
 231      *                 standard number formatting.
 232      * @param pattern  the pattern for this <code>PluralFormat</code>.
 233      *                 errors are returned to status if the pattern is invalid.
 234      * @param status   output param set to success/failure code on exit, which
 235      *                 must not indicate a failure before the function call.
 236      * @stable ICU 4.0
 237      */
 238     PluralFormat(const Locale& locale, const UnicodeString& pattern, UErrorCode& status);
 239
 240     /**
 241      * Creates a new <code>PluralFormat</code> for a given set of rules, a
 242      * pattern and a locale.
 243      * @param rules    defines the behavior of the <code>PluralFormat</code>
 244      *                 object.
 245      * @param pattern  the pattern for this <code>PluralFormat</code>.
 246      *                 errors are returned to status if the pattern is invalid.
 247      * @param status   output param set to success/failure code on exit, which
 248      *                 must not indicate a failure before the function call.
 249      * @stable ICU 4.0
 250      */
 251     PluralFormat(const PluralRules& rules,
 252                  const UnicodeString& pattern,
 253                  UErrorCode& status);
 254
 255     /**
 256      * Creates a new <code>PluralFormat</code> for a given set of rules, a
 257      * pattern and a locale.
 258      * @param locale  the <code>PluralFormat</code> will be configured with
 259      *                rules for this locale. This locale will also be used for
 260      *                standard number formatting.
 261      * @param rules   defines the behavior of the <code>PluralFormat</code>
 262      *                object.
 263      * @param pattern the pattern for this <code>PluralFormat</code>.
 264      *                errors are returned to status if the pattern is invalid.
 265      * @param status  output param set to success/failure code on exit, which
 266      *                must not indicate a failure before the function call.
 267      * @stable ICU 4.0
 268      */
 269     PluralFormat(const Locale& locale,
 270                  const PluralRules& rules,
 271                  const UnicodeString& pattern,
 272                  UErrorCode& status);
 273
 274     /**
 275      * Creates a new <code>PluralFormat</code> for a plural type, a
 276      * pattern and a locale.
 277      * @param locale  the <code>PluralFormat</code> will be configured with
 278      *                rules for this locale. This locale will also be used for
 279      *                standard number formatting.
 280      * @param type    The plural type (e.g., cardinal or ordinal).
 281      * @param pattern the pattern for this <code>PluralFormat</code>.
 282      *                errors are returned to status if the pattern is invalid.
 283      * @param status  output param set to success/failure code on exit, which
 284      *                must not indicate a failure before the function call.
 285      * @stable ICU 50
 286      */
 287     PluralFormat(const Locale& locale,
 288                  UPluralType type,
 289                  const UnicodeString& pattern,
 290                  UErrorCode& status);
 291
 292     /**
 293       * copy constructor.
 294       * @stable ICU 4.0
 295       */
 296     PluralFormat(const PluralFormat& other);
 297
 298     /**
 299      * Destructor.
 300      * @stable ICU 4.0
 301      */
 302     virtual ~PluralFormat();
 303
 304     /**
 305      * Sets the pattern used by this plural format.
 306      * The method parses the pattern and creates a map of format strings
 307      * for the plural rules.
 308      * Patterns and their interpretation are specified in the class description.
 309      *
 310      * @param pattern the pattern for this plural format
 311      *                errors are returned to status if the pattern is invalid.
 312      * @param status  output param set to success/failure code on exit, which
 313      *                must not indicate a failure before the function call.
 314      * @stable ICU 4.0
 315      */
 316     void applyPattern(const UnicodeString& pattern, UErrorCode& status);
 317
 318
 319     using Format::format;
 320
 321     /**
 322      * Formats a plural message for a given number.
 323      *
 324      * @param number  a number for which the plural message should be formatted
 325      *                for. If no pattern has been applied to this
 326      *                <code>PluralFormat</code> object yet, the formatted number
 327      *                will be returned.
 328      * @param status  output param set to success/failure code on exit, which
 329      *                must not indicate a failure before the function call.
 330      * @return        the string containing the formatted plural message.
 331      * @stable ICU 4.0
 332      */
 333     UnicodeString format(int32_t number, UErrorCode& status) const;
 334
 335     /**
 336      * Formats a plural message for a given number.
 337      *
 338      * @param number  a number for which the plural message should be formatted
 339      *                for. If no pattern has been applied to this
 340      *                PluralFormat object yet, the formatted number
 341      *                will be returned.
 342      * @param status  output param set to success or failure code on exit, which
 343      *                must not indicate a failure before the function call.
 344      * @return        the string containing the formatted plural message.
 345      * @stable ICU 4.0
 346      */
 347     UnicodeString format(double number, UErrorCode& status) const;
 348
 349     /**
 350      * Formats a plural message for a given number.
 351      *
 352      * @param number   a number for which the plural message should be formatted
 353      *                 for. If no pattern has been applied to this
 354      *                 <code>PluralFormat</code> object yet, the formatted number
 355      *                 will be returned.
 356      * @param appendTo output parameter to receive result.
 357      *                 result is appended to existing contents.
 358      * @param pos      On input: an alignment field, if desired.
 359      *                 On output: the offsets of the alignment field.
 360      * @param status   output param set to success/failure code on exit, which
 361      *                 must not indicate a failure before the function call.
 362      * @return         the string containing the formatted plural message.
 363      * @stable ICU 4.0
 364      */
 365     UnicodeString& format(int32_t number,
 366                           UnicodeString& appendTo,
 367                           FieldPosition& pos,
 368                           UErrorCode& status) const;
 369
 370     /**
 371      * Formats a plural message for a given number.
 372      *
 373      * @param number   a number for which the plural message should be formatted
 374      *                 for. If no pattern has been applied to this
 375      *                 PluralFormat object yet, the formatted number
 376      *                 will be returned.
 377      * @param appendTo output parameter to receive result.
 378      *                 result is appended to existing contents.
 379      * @param pos      On input: an alignment field, if desired.
 380      *                 On output: the offsets of the alignment field.
 381      * @param status   output param set to success/failure code on exit, which
 382      *                 must not indicate a failure before the function call.
 383      * @return         the string containing the formatted plural message.
 384      * @stable ICU 4.0
 385      */
 386     UnicodeString& format(double number,
 387                           UnicodeString& appendTo,
 388                           FieldPosition& pos,
 389                           UErrorCode& status) const;
 390
 391 #ifndef U_HIDE_DEPRECATED_API
 392     /**
 393      * Sets the locale used by this <code>PluraFormat</code> object.
 394      * Note: Calling this method resets this <code>PluraFormat</code> object,
 395      *     i.e., a pattern that was applied previously will be removed,
 396      *     and the NumberFormat is set to the default number format for
 397      *     the locale.  The resulting format behaves the same as one
 398      *     constructed from {@link #PluralFormat(const Locale& locale, UPluralType type, UErrorCode& status)}
 399      *     with UPLURAL_TYPE_CARDINAL.
 400      * @param locale  the <code>locale</code> to use to configure the formatter.
 401      * @param status  output param set to success/failure code on exit, which
 402      *                must not indicate a failure before the function call.
 403      * @deprecated ICU 50 This method clears the pattern and might create
 404      *             a different kind of PluralRules instance;
 405      *             use one of the constructors to create a new instance instead.
 406      */
 407     void setLocale(const Locale& locale, UErrorCode& status);
 408 #endif  /* U_HIDE_DEPRECATED_API */
 409
 410     /**
 411       * Sets the number format used by this formatter.  You only need to
 412       * call this if you want a different number format than the default
 413       * formatter for the locale.
 414       * @param format  the number format to use.
 415       * @param status  output param set to success/failure code on exit, which
 416       *                must not indicate a failure before the function call.
 417       * @stable ICU 4.0
 418       */
 419     void setNumberFormat(const NumberFormat* format, UErrorCode& status);
 420
 421     /**
 422        * Assignment operator
 423        *
 424        * @param other    the PluralFormat object to copy from.
 425        * @stable ICU 4.0
 426        */
 427     PluralFormat& operator=(const PluralFormat& other);
 428
 429     /**
 430       * Return true if another object is semantically equal to this one.
 431       *
 432       * @param other    the PluralFormat object to be compared with.
 433       * @return         true if other is semantically equal to this.
 434       * @stable ICU 4.0
 435       */
 436     virtual UBool operator==(const Format& other) const;
 437
 438     /**
 439      * Return true if another object is semantically unequal to this one.
 440      *
 441      * @param other    the PluralFormat object to be compared with.
 442      * @return         true if other is semantically unequal to this.
 443      * @stable ICU 4.0
 444      */
 445     virtual UBool operator!=(const Format& other) const;
 446
 447     /**
 448      * Clones this Format object polymorphically.  The caller owns the
 449      * result and should delete it when done.
 450      * @stable ICU 4.0
 451      */
 452     virtual Format* clone(void) const;
 453
 454    /**
 455     * Formats a plural message for a number taken from a Formattable object.
 456     *
 457     * @param obj       The object containing a number for which the
 458     *                  plural message should be formatted.
 459     *                  The object must be of a numeric type.
 460     * @param appendTo  output parameter to receive result.
 461     *                  Result is appended to existing contents.
 462     * @param pos       On input: an alignment field, if desired.
 463     *                  On output: the offsets of the alignment field.
 464     * @param status    output param filled with success/failure status.
 465     * @return          Reference to 'appendTo' parameter.
 466     * @stable ICU 4.0
 467     */
 468    UnicodeString& format(const Formattable& obj,
 469                          UnicodeString& appendTo,
 470                          FieldPosition& pos,
 471                          UErrorCode& status) const;
 472
 473    /**
 474     * Returns the pattern from applyPattern() or constructor().
 475     *
 476     * @param  appendTo  output parameter to receive result.
 477      *                  Result is appended to existing contents.
 478     * @return the UnicodeString with inserted pattern.
 479     * @stable ICU 4.0
 480     */
 481    UnicodeString& toPattern(UnicodeString& appendTo);
 482
 483    /**
 484     * This method is not yet supported by <code>PluralFormat</code>.
 485     * <P>
 486     * Before calling, set parse_pos.index to the offset you want to start
 487     * parsing at in the source. After calling, parse_pos.index is the end of
 488     * the text you parsed. If error occurs, index is unchanged.
 489     * <P>
 490     * When parsing, leading whitespace is discarded (with a successful parse),
 491     * while trailing whitespace is left as is.
 492     * <P>
 493     * See Format::parseObject() for more.
 494     *
 495     * @param source    The string to be parsed into an object.
 496     * @param result    Formattable to be set to the parse result.
 497     *                  If parse fails, return contents are undefined.
 498     * @param parse_pos The position to start parsing at. Upon return
 499     *                  this param is set to the position after the
 500     *                  last character successfully parsed. If the
 501     *                  source is not parsed successfully, this param
 502     *                  will remain unchanged.
 503     * @stable ICU 4.0
 504     */
 505    virtual void parseObject(const UnicodeString& source,
 506                             Formattable& result,
 507                             ParsePosition& parse_pos) const;
 508
 509     /**
 510      * ICU "poor man's RTTI", returns a UClassID for this class.
 511      *
 512      * @stable ICU 4.0
 513      *
 514      */
 515     static UClassID U_EXPORT2 getStaticClassID(void);
 516
 517     /**
 518      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 519      *
 520      * @stable ICU 4.0
 521      */
 522      virtual UClassID getDynamicClassID() const;
 523
 524 private:
 525      /**
 526       * @internal
 527       */
 528     class U_I18N_API PluralSelector : public UMemory {
 529       public:
 530         virtual ~PluralSelector();
 531         /**
 532          * Given a number, returns the appropriate PluralFormat keyword.
 533          *
 534          * @param context worker object for the selector.
 535          * @param number The number to be plural-formatted.
 536          * @param ec Error code.
 537          * @return The selected PluralFormat keyword.
 538          * @internal
 539          */
 540         virtual UnicodeString select(void *context, double number, UErrorCode& ec) const = 0;
 541     };
 542
 543     /**
 544      * @internal
 545      */
 546     class U_I18N_API PluralSelectorAdapter : public PluralSelector {
 547       public:
 548         PluralSelectorAdapter() : pluralRules(NULL) {
 549         }
 550
 551         virtual ~PluralSelectorAdapter();
 552
 553         virtual UnicodeString select(void *context, double number, UErrorCode& /*ec*/) const; /**< @internal */
 554
 555         void reset();
 556
 557         PluralRules* pluralRules;
 558     };
 559
 560     Locale  locale;
 561     MessagePattern msgPattern;
 562     NumberFormat*  numberFormat;
 563     double offset;
 564     PluralSelectorAdapter pluralRulesWrapper;
 565
 566     PluralFormat();   // default constructor not implemented
 567     void init(const PluralRules* rules, UPluralType type, UErrorCode& status);
 568     /**
 569      * Copies dynamically allocated values (pointer fields).
 570      * Others are copied using their copy constructors and assignment operators.
 571      */
 572     void copyObjects(const PluralFormat& other);
 573
 574     UnicodeString& format(const Formattable& numberObject, double number,
 575                           UnicodeString& appendTo,
 576                           FieldPosition& pos,
 577                           UErrorCode& status) const; /**< @internal */
 578
 579     /**
 580      * Finds the PluralFormat sub-message for the given number, or the "other" sub-message.
 581      * @param pattern A MessagePattern.
 582      * @param partIndex the index of the first PluralFormat argument style part.
 583      * @param selector the PluralSelector for mapping the number (minus offset) to a keyword.
 584      * @param context worker object for the selector.
 585      * @param number a number to be matched to one of the PluralFormat argument's explicit values,
 586      *        or mapped via the PluralSelector.
 587      * @param ec ICU error code.
 588      * @return the sub-message start part index.
 589      */
 590     static int32_t findSubMessage(
 591          const MessagePattern& pattern, int32_t partIndex,
 592          const PluralSelector& selector, void *context, double number, UErrorCode& ec); /**< @internal */
 593
 594     void parseType(const UnicodeString& source, const NFRule *rbnfLenientScanner,
 595         Formattable& result, FieldPosition& pos) const;
 596
 597     friend class MessageFormat;
 598     friend class NFRule;
 599 };
 600
 601 U_NAMESPACE_END
 602 #endif // U_SHOW_CPLUSPLUS_API
 603
 604 #endif /* #if !UCONFIG_NO_FORMATTING */
 605
 606 #endif // _PLURFMT
 607 //eof