icuSources/i18n/unicode/plurfmt.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 2007-2012, International Business Machines Corporation and
   4 * others. All Rights Reserved.
   5 *******************************************************************************
   6 *
   7
   8 * File PLURFMT.H
   9 *
  10 * Modification History:*
  11 *   Date        Name        Description
  12 *
  13 ********************************************************************************
  14 */
  15
  16 #ifndef PLURFMT
  17 #define PLURFMT
  18
  19 #include "unicode/utypes.h"
  20
  21 /**
  22  * \file
  23  * \brief C++ API: PluralFormat object
  24  */
  25
  26 #if !UCONFIG_NO_FORMATTING
  27
  28 #include "unicode/messagepattern.h"
  29 #include "unicode/numfmt.h"
  30 #include "unicode/plurrule.h"
  31
  32 U_NAMESPACE_BEGIN
  33
  34 class Hashtable;
  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 <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 <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      */
 193     PluralFormat(const Locale& locale, const PluralRules& rules, UErrorCode& status);
 194
 195     /**
 196      * Creates a new <code>PluralFormat</code> for a given pattern string.
 197      * The default locale will be used to get the set of plural rules and for
 198      * standard number formatting.
 199      * @param  pattern the pattern for this <code>PluralFormat</code>.
 200      *                 errors are returned to status if the pattern is invalid.
 201      * @param status   output param set to success/failure code on exit, which
 202      *                 must not indicate a failure before the function call.
 203      * @stable ICU 4.0
 204      */
 205     PluralFormat(const UnicodeString& pattern, UErrorCode& status);
 206
 207     /**
 208      * Creates a new <code>PluralFormat</code> for a given pattern string and
 209      * locale.
 210      * The locale will be used to get the set of plural rules and for
 211      * standard number formatting.
 212      * @param locale   the <code>PluralFormat</code> will be configured with
 213      *                 rules for this locale. This locale will also be used 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.
 219      * @stable ICU 4.0
 220      */
 221     PluralFormat(const Locale& locale, const UnicodeString& pattern, UErrorCode& status);
 222
 223     /**
 224      * Creates a new <code>PluralFormat</code> for a given set of rules, a
 225      * pattern and a locale.
 226      * @param rules    defines the behavior of the <code>PluralFormat</code>
 227      *                 object.
 228      * @param pattern  the pattern for this <code>PluralFormat</code>.
 229      *                 errors are returned to status if the pattern is invalid.
 230      * @param status   output param set to success/failure code on exit, which
 231      *                 must not indicate a failure before the function call.
 232      * @stable ICU 4.0
 233      */
 234     PluralFormat(const PluralRules& rules,
 235                  const UnicodeString& pattern,
 236                  UErrorCode& status);
 237
 238     /**
 239      * Creates a new <code>PluralFormat</code> for a given set of rules, a
 240      * pattern and a locale.
 241      * @param locale  the <code>PluralFormat</code> will be configured with
 242      *                rules for this locale. This locale will also be used for
 243      *                standard number formatting.
 244      * @param rules   defines the behavior of the <code>PluralFormat</code>
 245      *                object.
 246      * @param pattern the pattern for this <code>PluralFormat</code>.
 247      *                errors are returned to status if the pattern is invalid.
 248      * @param status  output param set to success/failure code on exit, which
 249      *                must not indicate a failure before the function call.
 250      * @stable ICU 4.0
 251      */
 252     PluralFormat(const Locale& locale,
 253                  const PluralRules& rules,
 254                  const UnicodeString& pattern,
 255                  UErrorCode& status);
 256
 257     /**
 258       * copy constructor.
 259       * @stable ICU 4.0
 260       */
 261     PluralFormat(const PluralFormat& other);
 262
 263     /**
 264      * Destructor.
 265      * @stable ICU 4.0
 266      */
 267     virtual ~PluralFormat();
 268
 269     /**
 270      * Sets the pattern used by this plural format.
 271      * The method parses the pattern and creates a map of format strings
 272      * for the plural rules.
 273      * Patterns and their interpretation are specified in the class description.
 274      *
 275      * @param pattern the pattern for this plural format
 276      *                errors are returned to status if the pattern is invalid.
 277      * @param status  output param set to success/failure code on exit, which
 278      *                must not indicate a failure before the function call.
 279      * @stable ICU 4.0
 280      */
 281     void applyPattern(const UnicodeString& pattern, UErrorCode& status);
 282
 283
 284     using Format::format;
 285
 286     /**
 287      * Formats a plural message for a given number.
 288      *
 289      * @param number  a number for which the plural message should be formatted
 290      *                for. If no pattern has been applied to this
 291      *                <code>PluralFormat</code> object yet, the formatted number
 292      *                will be returned.
 293      * @param status  output param set to success/failure code on exit, which
 294      *                must not indicate a failure before the function call.
 295      * @return        the string containing the formatted plural message.
 296      * @stable ICU 4.0
 297      */
 298     UnicodeString format(int32_t number, UErrorCode& status) const;
 299
 300     /**
 301      * Formats a plural message for a given number.
 302      *
 303      * @param number  a number for which the plural message should be formatted
 304      *                for. If no pattern has been applied to this
 305      *                PluralFormat object yet, the formatted number
 306      *                will be returned.
 307      * @param status  output param set to success or failure code on exit, which
 308      *                must not indicate a failure before the function call.
 309      * @return        the string containing the formatted plural message.
 310      * @stable ICU 4.0
 311      */
 312     UnicodeString format(double number, UErrorCode& status) const;
 313
 314     /**
 315      * Formats a plural message for a given number.
 316      *
 317      * @param number   a number for which the plural message should be formatted
 318      *                 for. If no pattern has been applied to this
 319      *                 <code>PluralFormat</code> object yet, the formatted number
 320      *                 will be returned.
 321      * @param appendTo output parameter to receive result.
 322      *                 result is appended to existing contents.
 323      * @param pos      On input: an alignment field, if desired.
 324      *                 On output: the offsets of the alignment field.
 325      * @param status   output param set to success/failure code on exit, which
 326      *                 must not indicate a failure before the function call.
 327      * @return         the string containing the formatted plural message.
 328      * @stable ICU 4.0
 329      */
 330     UnicodeString& format(int32_t number,
 331                           UnicodeString& appendTo,
 332                           FieldPosition& pos,
 333                           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 appendTo output parameter to receive result.
 343      *                 result is appended to existing contents.
 344      * @param pos      On input: an alignment field, if desired.
 345      *                 On output: the offsets of the alignment field.
 346      * @param status   output param set to success/failure code on exit, which
 347      *                 must not indicate a failure before the function call.
 348      * @return         the string containing the formatted plural message.
 349      * @stable ICU 4.0
 350      */
 351     UnicodeString& format(double number,
 352                           UnicodeString& appendTo,
 353                           FieldPosition& pos,
 354                           UErrorCode& status) const;
 355
 356     /**
 357      * Sets the locale used by this <code>PluraFormat</code> object.
 358      * Note: Calling this method resets this <code>PluraFormat</code> object,
 359      *     i.e., a pattern that was applied previously will be removed,
 360      *     and the NumberFormat is set to the default number format for
 361      *     the locale.  The resulting format behaves the same as one
 362      *     constructed from {@link #PluralFormat(const Locale& locale, UErrorCode& status)}.
 363      * @param locale  the <code>locale</code> to use to configure the formatter.
 364      * @param status  output param set to success/failure code on exit, which
 365      *                must not indicate a failure before the function call.
 366      * @stable ICU 4.0
 367      */
 368     void setLocale(const Locale& locale, UErrorCode& status);
 369
 370     /**
 371       * Sets the number format used by this formatter.  You only need to
 372       * call this if you want a different number format than the default
 373       * formatter for the locale.
 374       * @param format  the number format to use.
 375       * @param status  output param set to success/failure code on exit, which
 376       *                must not indicate a failure before the function call.
 377       * @stable ICU 4.0
 378       */
 379     void setNumberFormat(const NumberFormat* format, UErrorCode& status);
 380
 381     /**
 382        * Assignment operator
 383        *
 384        * @param other    the PluralFormat object to copy from.
 385        * @stable ICU 4.0
 386        */
 387     PluralFormat& operator=(const PluralFormat& other);
 388
 389     /**
 390       * Return true if another object is semantically equal to this one.
 391       *
 392       * @param other    the PluralFormat object to be compared with.
 393       * @return         true if other is semantically equal to this.
 394       * @stable ICU 4.0
 395       */
 396     virtual UBool operator==(const Format& other) const;
 397
 398     /**
 399      * Return true if another object is semantically unequal to this one.
 400      *
 401      * @param other    the PluralFormat object to be compared with.
 402      * @return         true if other is semantically unequal to this.
 403      * @stable ICU 4.0
 404      */
 405     virtual UBool operator!=(const Format& other) const;
 406
 407     /**
 408      * Clones this Format object polymorphically.  The caller owns the
 409      * result and should delete it when done.
 410      * @stable ICU 4.0
 411      */
 412     virtual Format* clone(void) const;
 413
 414     /**
 415     * Redeclared Format method.
 416     *
 417     * @param obj       The object to be formatted into a string.
 418     * @param appendTo  output parameter to receive result.
 419     *                  Result is appended to existing contents.
 420     * @param pos       On input: an alignment field, if desired.
 421     *                  On output: the offsets of the alignment field.
 422     * @param status    output param filled with success/failure status.
 423     * @return          Reference to 'appendTo' parameter.
 424     * @stable ICU 4.0
 425     */
 426    UnicodeString& format(const Formattable& obj,
 427                          UnicodeString& appendTo,
 428                          FieldPosition& pos,
 429                          UErrorCode& status) const;
 430
 431    /**
 432     * Returns the pattern from applyPattern() or constructor().
 433     *
 434     * @param  appendTo  output parameter to receive result.
 435      *                  Result is appended to existing contents.
 436     * @return the UnicodeString with inserted pattern.
 437     * @stable ICU 4.0
 438     */
 439    UnicodeString& toPattern(UnicodeString& appendTo);
 440
 441    /**
 442     * This method is not yet supported by <code>PluralFormat</code>.
 443     * <P>
 444     * Before calling, set parse_pos.index to the offset you want to start
 445     * parsing at in the source. After calling, parse_pos.index is the end of
 446     * the text you parsed. If error occurs, index is unchanged.
 447     * <P>
 448     * When parsing, leading whitespace is discarded (with a successful parse),
 449     * while trailing whitespace is left as is.
 450     * <P>
 451     * See Format::parseObject() for more.
 452     *
 453     * @param source    The string to be parsed into an object.
 454     * @param result    Formattable to be set to the parse result.
 455     *                  If parse fails, return contents are undefined.
 456     * @param parse_pos The position to start parsing at. Upon return
 457     *                  this param is set to the position after the
 458     *                  last character successfully parsed. If the
 459     *                  source is not parsed successfully, this param
 460     *                  will remain unchanged.
 461     * @stable ICU 4.0
 462     */
 463    virtual void parseObject(const UnicodeString& source,
 464                             Formattable& result,
 465                             ParsePosition& parse_pos) const;
 466
 467     /**
 468      * ICU "poor man's RTTI", returns a UClassID for this class.
 469      *
 470      * @stable ICU 4.0
 471      *
 472      */
 473     static UClassID U_EXPORT2 getStaticClassID(void);
 474
 475     /**
 476      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 477      *
 478      * @stable ICU 4.0
 479      */
 480      virtual UClassID getDynamicClassID() const;
 481
 482 #if defined(__xlC__) || (U_PLATFORM == U_PF_OS390) || (U_PLATFORM ==U_PF_OS400)
 483 // Work around a compiler bug on xlC 11.1 on AIX 7.1 that would
 484 // prevent PluralSelectorAdapter from implementing private PluralSelector.
 485 // xlC error message:
 486 // 1540-0300 (S) The "private" member "class icu_49::PluralFormat::PluralSelector" cannot be accessed.
 487 public:
 488 #else
 489 private:
 490 #endif
 491      /**
 492       * @internal
 493       */
 494     class U_I18N_API PluralSelector : public UMemory {
 495       public:
 496         virtual ~PluralSelector();
 497         /**
 498          * Given a number, returns the appropriate PluralFormat keyword.
 499          *
 500          * @param number The number to be plural-formatted.
 501          * @param ec Error code.
 502          * @return The selected PluralFormat keyword.
 503          */
 504         virtual UnicodeString select(double number, UErrorCode& ec) const = 0;
 505     };
 506
 507     /**
 508      * @internal
 509      */
 510     class U_I18N_API PluralSelectorAdapter : public PluralSelector {
 511       public:
 512         PluralSelectorAdapter() : pluralRules(NULL) {
 513         }
 514
 515         virtual ~PluralSelectorAdapter();
 516
 517         virtual UnicodeString select(double number, UErrorCode& /*ec*/) const;
 518
 519         void reset();
 520
 521         PluralRules* pluralRules;
 522     };
 523
 524 #if defined(__xlC__)
 525 // End of xlC bug workaround, keep remaining definitions private.
 526 private:
 527 #endif
 528     Locale  locale;
 529     MessagePattern msgPattern;
 530     NumberFormat*  numberFormat;
 531     double offset;
 532     PluralSelectorAdapter pluralRulesWrapper;
 533
 534     PluralFormat();   // default constructor not implemented
 535     void init(const PluralRules* rules, UErrorCode& status);
 536     /**
 537      * Copies dynamically allocated values (pointer fields).
 538      * Others are copied using their copy constructors and assignment operators.
 539      */
 540     void copyObjects(const PluralFormat& other);
 541
 542     /**
 543      * Finds the PluralFormat sub-message for the given number, or the "other" sub-message.
 544      * @param pattern A MessagePattern.
 545      * @param partIndex the index of the first PluralFormat argument style part.
 546      * @param selector the PluralSelector for mapping the number (minus offset) to a keyword.
 547      * @param number a number to be matched to one of the PluralFormat argument's explicit values,
 548      *        or mapped via the PluralSelector.
 549      * @param ec ICU error code.
 550      * @return the sub-message start part index.
 551      */
 552     static int32_t findSubMessage(
 553          const MessagePattern& pattern, int32_t partIndex,
 554          const PluralSelector& selector, double number, UErrorCode& ec);
 555
 556     friend class MessageFormat;
 557 };
 558
 559 U_NAMESPACE_END
 560
 561 #endif /* #if !UCONFIG_NO_FORMATTING */
 562
 563 #endif // _PLURFMT
 564 //eof