icuSources/i18n/unicode/msgfmt.h

   1 /*
   2 * Copyright (C) 2007-2010, International Business Machines Corporation and
   3 * others. All Rights Reserved.
   4 ********************************************************************************
   5 *
   6 * File MSGFMT.H
   7 *
   8 * Modification History:
   9 *
  10 *   Date        Name        Description
  11 *   02/19/97    aliu        Converted from java.
  12 *   03/20/97    helena      Finished first cut of implementation.
  13 *   07/22/98    stephen     Removed operator!= (defined in Format)
  14 *   08/19/2002  srl         Removing Javaisms
  15 *******************************************************************************/
  16
  17 #ifndef MSGFMT_H
  18 #define MSGFMT_H
  19
  20 #include "unicode/utypes.h"
  21
  22 /**
  23  * \file
  24  * \brief C++ API: Formats messages in a language-neutral way.
  25  */
  26
  27 #if !UCONFIG_NO_FORMATTING
  28
  29 #include "unicode/format.h"
  30 #include "unicode/locid.h"
  31 #include "unicode/parseerr.h"
  32 #include "unicode/uchar.h"
  33
  34 U_NAMESPACE_BEGIN
  35
  36 class NumberFormat;
  37 class DateFormat;
  38
  39 /**
  40  *
  41  * MessageFormat produces concatenated messages in a language-neutral
  42  * way.  Use this whenever concatenating strings that are displayed to
  43  * end users.
  44  *
  45  * <P>A MessageFormat contains an array of <EM>subformats</EM> arranged
  46  * within a <EM>template string</EM>.  Together, the subformats and
  47  * template string determine how the MessageFormat will operate during
  48  * formatting and parsing.
  49  *
  50  * <P>Typically, both the subformats and the template string are
  51  * specified at once in a <EM>pattern</EM>.  By using different
  52  * patterns for different locales, messages may be localized.
  53  *
  54  * <P>When formatting, MessageFormat takes an array of arguments
  55  * and produces a user-readable string.  Each argument is a
  56  * Formattable object; they may be passed in in an array, or as a
  57  * single Formattable object which itself contains an array.  Each
  58  * argument is matched up with its corresponding subformat, which then
  59  * formats it into a string.  The resulting strings are then assembled
  60  * within the string template of the MessageFormat to produce the
  61  * final output string.
  62  *
  63  * <p><strong>Note:</strong>
  64  * In ICU 4.0 MessageFormat supports named arguments.  If a named argument
  65  * is used, all arguments must be named.  Names start with a character in
  66  * <code>UCHAR_ID_START</code> and continue with characters in
  67  * <code>UCHARID_CONTINUE</code>, in particular they do not start with a digit.
  68  * If named arguments are used, {@link #usesNamedArguments()} will return true.
  69  *
  70  * <p>The other new methods supporting named arguments are
  71  * {@link #getFormatNames(UErrorCode& status)},
  72  * {@link #getFormat(const UnicodeString& formatName, UErrorCode& status)}
  73  * {@link #setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status)},
  74  * {@link #adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status)},
  75  * {@link #format(const UnicodeString* argumentNames, const Formattable* arguments,
  76  *  int32_t count, UnicodeString& appendTo,UErrorCode& status)}.
  77  * These methods are all compatible with patterns that do not used named arguments--
  78  * in these cases the keys in the input or output use <code>UnicodeString</code>s
  79  * that name the argument indices, e.g. "0", "1", "2"... etc.
  80  *
  81  * <p>If this format uses named arguments, certain methods that take or
  82  * return arrays do not perform any action, since it is not possible to
  83  * identify positions in an array using a name.  Of these methods,
  84  * UErrorCode is set to U_ILLEGAL_ARGUMENT_ERROR by format, and to
  85  * U_ARGUMENT_TYPE_MISMATCH by parse.
  86  * These methods are
  87  * {@link #adoptFormats(Format** formatsToAdopt, int32_t count)},
  88  * {@link #setFormats(const Format** newFormats,int32_t count)},
  89  * {@link #adoptFormat(int32_t n, Format *newFormat)},
  90  * {@link #setFormat(int32_t n, Format& newFormat)},
  91  * {@link #format(const Formattable* source, int32_t count, UnicodeString& appendTo, FieldPosition& ignore, UErrorCode& success)},
  92  * {@link #format(const UnicodeString& pattern,const Formattable* arguments,int32_t cnt,UnicodeString& appendTo,UErrorCode& success)},
  93  * {@link #format(const Formattable& source, UnicodeString& appendTo, FieldPosition& ignore, UErrorCode& success)},
  94  * {@link #format(const Formattable* arguments, int32_t cnt, UnicodeString& appendTo, FieldPosition& status, int32_t recursionProtection,UErrorCode& success)},
  95  * {@link #parse(const UnicodeString& source, ParsePosition& pos, int32_t& count)},
  96  * {@link #parse(const UnicodeString& source, int32_t& cnt, UErrorCode& status)}
  97  *
  98  * <P>
  99  * During parsing, an input string is matched against the string
 100  * template of the MessageFormat to produce an array of Formattable
 101  * objects.  Plain text of the template string is matched directly
 102  * against input text.  At each position in the template string where
 103  * a subformat is located, the subformat is called to parse the
 104  * corresponding segment of input text to produce an output argument.
 105  * In this way, an array of arguments is created which together
 106  * constitute the parse result.
 107  * <P>
 108  * Parsing may fail or produce unexpected results in a number of
 109  * circumstances.
 110  * <UL>
 111  * <LI>If one of the arguments does not occur in the pattern, it
 112  * will be returned as a default Formattable.
 113  * <LI>If the format of an argument loses information, such as with
 114  * a choice format where a large number formats to "many", then the
 115  * parse may not correspond to the originally formatted argument.
 116  * <LI>MessageFormat does not handle ChoiceFormat recursion during
 117  * parsing; such parses will fail.
 118  * <LI>Parsing will not always find a match (or the correct match) if
 119  * some part of the parse is ambiguous.  For example, if the pattern
 120  * "{1},{2}" is used with the string arguments {"a,b", "c"}, it will
 121  * format as "a,b,c".  When the result is parsed, it will return {"a",
 122  * "b,c"}.
 123  * <LI>If a single argument is formatted more than once in the string,
 124  * then the rightmost subformat in the pattern string will produce the
 125  * parse result; prior subformats with the same argument index will
 126  * have no effect.
 127  * </UL>
 128  * Here are some examples of usage:
 129  * <P>
 130  * Example 1:
 131  * <pre>
 132  * \code
 133  *     UErrorCode success = U_ZERO_ERROR;
 134  *     GregorianCalendar cal(success);
 135  *     Formattable arguments[] = {
 136  *         7L,
 137  *         Formattable( (Date) cal.getTime(success), Formattable::kIsDate),
 138  *         "a disturbance in the Force"
 139  *     };
 140  *
 141  *     UnicodeString result;
 142  *     MessageFormat::format(
 143  *          "At {1,time} on {1,date}, there was {2} on planet {0,number}.",
 144  *          arguments, 3, result, success );
 145  *
 146  *     cout << "result: " << result << endl;
 147  *     //<output>: At 4:34:20 PM on 23-Mar-98, there was a disturbance
 148  *     //             in the Force on planet 7.
 149  * \endcode
 150  * </pre>
 151  * Typically, the message format will come from resources, and the
 152  * arguments will be dynamically set at runtime.
 153  * <P>
 154  * Example 2:
 155  * <pre>
 156  *  \code
 157  *     success = U_ZERO_ERROR;
 158  *     Formattable testArgs[] = {3L, "MyDisk"};
 159  *
 160  *     MessageFormat form(
 161  *         "The disk \"{1}\" contains {0} file(s).", success );
 162  *
 163  *     UnicodeString string;
 164  *     FieldPosition fpos = 0;
 165  *     cout << "format: " << form.format(testArgs, 2, string, fpos, success ) << endl;
 166  *
 167  *     // output, with different testArgs:
 168  *     // output: The disk "MyDisk" contains 0 file(s).
 169  *     // output: The disk "MyDisk" contains 1 file(s).
 170  *     // output: The disk "MyDisk" contains 1,273 file(s).
 171  *  \endcode
 172  *  </pre>
 173  *
 174  *  The pattern is of the following form.  Legend:
 175  *  <pre>
 176  * \code
 177  *       {optional item}
 178  *       (group that may be repeated)*
 179  * \endcode
 180  *  </pre>
 181  *  Do not confuse optional items with items inside quoted braces, such
 182  *  as this: "{".  Quoted braces are literals.
 183  *  <pre>
 184  *  \code
 185  *       messageFormatPattern := string ( "{" messageFormatElement "}" string )*
 186  *
 187  *       messageFormatElement := argumentIndex | argumentName { "," elementFormat }
 188  *
 189  *       elementFormat := "time" { "," datetimeStyle }
 190  *                      | "date" { "," datetimeStyle }
 191  *                      | "number" { "," numberStyle }
 192  *                      | "choice" "," choiceStyle
 193  *                      | "spellout" { "," spelloutStyle }
 194  *                      | "ordinal" { "," spelloutStyle }
 195  *                      | "duration" { "," spelloutStyle }
 196  *                      | "plural" "," pluralStyle
 197  *                      | "select" "," selectStyle
 198  *
 199  *       datetimeStyle := "short"
 200  *                      | "medium"
 201  *                      | "long"
 202  *                      | "full"
 203  *                      | dateFormatPattern
 204  *
 205  *       numberStyle :=   "currency"
 206  *                      | "percent"
 207  *                      | "integer"
 208  *                      | numberFormatPattern
 209  *
 210  *       choiceStyle :=   choiceFormatPattern
 211  *
 212  *       pluralStyle :=   pluralFormatPattern
 213  *
 214  *       selectStyle :=   selectFormatPattern
 215  *
 216  *       spelloutStyle := ruleSetName
 217  * \endcode
 218  * </pre>
 219  * If there is no elementFormat, then the argument must be a string,
 220  * which is substituted. If there is no dateTimeStyle or numberStyle,
 221  * then the default format is used (e.g.  NumberFormat::createInstance(),
 222  * DateFormat::createTimeInstance(DateFormat::kDefault, ...) or
 223  * DateFormat::createDateInstance(DateFormat::kDefault, ...). For
 224  * a RuleBasedNumberFormat, if there is no ruleSetName, the default
 225  * rule set is used. For a ChoiceFormat or PluralFormat or SelectFormat, the pattern
 226  * must always be specified, since there is no default.
 227  * <P>
 228  * In strings, single quotes can be used to quote syntax characters.
 229  * A literal single quote is represented by '', both within and outside
 230  * of single-quoted segments.  Inside a
 231  * messageFormatElement, quotes are <EM>not</EM> removed. For example,
 232  * {1,number,$'#',##} will produce a number format with the pound-sign
 233  * quoted, with a result such as: "$#31,45".
 234  * <P>
 235  * If a pattern is used, then unquoted braces in the pattern, if any,
 236  * must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab
 237  * {0'}' de" and "ab } de" are not.
 238  * <p>
 239  * <dl><dt><b>Warning:</b><dd>The rules for using quotes within message
 240  * format patterns unfortunately have shown to be somewhat confusing.
 241  * In particular, it isn't always obvious to localizers whether single
 242  * quotes need to be doubled or not. Make sure to inform localizers about
 243  * the rules, and tell them (for example, by using comments in resource
 244  * bundle source files) which strings will be processed by MessageFormat.
 245  * Note that localizers may need to use single quotes in translated
 246  * strings where the original version doesn't have them.
 247  * <br>Note also that the simplest way to avoid the problem is to
 248  * use the real apostrophe (single quote) character U+2019 (') for
 249  * human-readable text, and to use the ASCII apostrophe (U+0027 ' )
 250  * only in program syntax, like quoting in MessageFormat.
 251  * See the annotations for U+0027 Apostrophe in The Unicode Standard.</p>
 252  * </dl>
 253  * <P>
 254  * The argumentIndex is a non-negative integer, which corresponds to the
 255  * index of the arguments presented in an array to be formatted.  The
 256  * first argument has argumentIndex 0.
 257  * <P>
 258  * It is acceptable to have unused arguments in the array.  With missing
 259  * arguments, or arguments that are not of the right class for the
 260  * specified format, a failing UErrorCode result is set.
 261  * <P>
 262  * <strong>Creating internationalized messages that include plural forms, you
 263  * can use a PluralFormat:</strong>
 264  * <pre>
 265  * \code
 266  *  UErrorCode err = U_ZERO_ERROR;
 267  *  UnicodeString t1("{0, plural, one{C''est # fichier} other{Ce sont # fichiers}} dans la liste.");
 268  *  MessageFormat* msgFmt = new MessageFormat(t1, Locale("fr"), err);
 269  *  if (U_FAILURE(err)) {
 270  *      return err;
 271  *  }
 272  *
 273  *  Formattable args1[] = {(int32_t)0};
 274  *  Formattable args2[] = {(int32_t)3};
 275  *  FieldPosition ignore(FieldPosition::DONT_CARE);
 276  *  UnicodeString result;
 277  *  msgFmt->format(args1, 1, result, ignore, status);
 278  *  cout << result << endl;
 279  *  result.remove();
 280  *  msgFmt->format(args2, 1, result, ignore, status);
 281  *  cout << result << endl;
 282  *
 283  *  // output, with different args
 284  *  // output: C'est 0,0 fichier dans la liste.
 285  *  // output: Ce sont 3 fichiers dans la liste."
 286  * \endcode
 287  * </pre>
 288  * Please check PluralFormat and PluralRules for details.
 289  * </P>
 290  */
 291 class U_I18N_API MessageFormat : public Format {
 292 public:
 293     /**
 294      * Enum type for kMaxFormat.
 295      * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,
 296      * rendering this enum type obsolete.
 297      */
 298     enum EFormatNumber {
 299         /**
 300          * The maximum number of arguments.
 301          * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,
 302          * rendering this constant obsolete.
 303          */
 304         kMaxFormat = 10
 305     };
 306
 307     /**
 308      * Constructs a new MessageFormat using the given pattern and the
 309      * default locale.
 310      *
 311      * @param pattern   Pattern used to construct object.
 312      * @param status    Input/output error code.  If the
 313      *                  pattern cannot be parsed, set to failure code.
 314      * @stable ICU 2.0
 315      */
 316     MessageFormat(const UnicodeString& pattern,
 317                   UErrorCode &status);
 318
 319     /**
 320      * Constructs a new MessageFormat using the given pattern and locale.
 321      * @param pattern   Pattern used to construct object.
 322      * @param newLocale The locale to use for formatting dates and numbers.
 323      * @param status    Input/output error code.  If the
 324      *                  pattern cannot be parsed, set to failure code.
 325      * @stable ICU 2.0
 326      */
 327     MessageFormat(const UnicodeString& pattern,
 328                   const Locale& newLocale,
 329                         UErrorCode& status);
 330     /**
 331      * Constructs a new MessageFormat using the given pattern and locale.
 332      * @param pattern   Pattern used to construct object.
 333      * @param newLocale The locale to use for formatting dates and numbers.
 334      * @param parseError Struct to recieve information on position
 335      *                   of error within the pattern.
 336      * @param status    Input/output error code.  If the
 337      *                  pattern cannot be parsed, set to failure code.
 338      * @stable ICU 2.0
 339      */
 340     MessageFormat(const UnicodeString& pattern,
 341                   const Locale& newLocale,
 342                   UParseError& parseError,
 343                   UErrorCode& status);
 344     /**
 345      * Constructs a new MessageFormat from an existing one.
 346      * @stable ICU 2.0
 347      */
 348     MessageFormat(const MessageFormat&);
 349
 350     /**
 351      * Assignment operator.
 352      * @stable ICU 2.0
 353      */
 354     const MessageFormat& operator=(const MessageFormat&);
 355
 356     /**
 357      * Destructor.
 358      * @stable ICU 2.0
 359      */
 360     virtual ~MessageFormat();
 361
 362     /**
 363      * Clones this Format object polymorphically.  The caller owns the
 364      * result and should delete it when done.
 365      * @stable ICU 2.0
 366      */
 367     virtual Format* clone(void) const;
 368
 369     /**
 370      * Returns true if the given Format objects are semantically equal.
 371      * Objects of different subclasses are considered unequal.
 372      * @param other  the object to be compared with.
 373      * @return       true if the given Format objects are semantically equal.
 374      * @stable ICU 2.0
 375      */
 376     virtual UBool operator==(const Format& other) const;
 377
 378     /**
 379      * Sets the locale. This locale is used for fetching default number or date
 380      * format information.
 381      * @param theLocale    the new locale value to be set.
 382      * @stable ICU 2.0
 383      */
 384     virtual void setLocale(const Locale& theLocale);
 385
 386     /**
 387      * Gets the locale. This locale is used for fetching default number or date
 388      * format information.
 389      * @return    the locale of the object.
 390      * @stable ICU 2.0
 391      */
 392     virtual const Locale& getLocale(void) const;
 393
 394     /**
 395      * Applies the given pattern string to this message format.
 396      *
 397      * @param pattern   The pattern to be applied.
 398      * @param status    Input/output error code.  If the
 399      *                  pattern cannot be parsed, set to failure code.
 400      * @stable ICU 2.0
 401      */
 402     virtual void applyPattern(const UnicodeString& pattern,
 403                               UErrorCode& status);
 404     /**
 405      * Applies the given pattern string to this message format.
 406      *
 407      * @param pattern    The pattern to be applied.
 408      * @param parseError Struct to recieve information on position
 409      *                   of error within pattern.
 410      * @param status    Input/output error code.  If the
 411      *                  pattern cannot be parsed, set to failure code.
 412      * @stable ICU 2.0
 413      */
 414     virtual void applyPattern(const UnicodeString& pattern,
 415                              UParseError& parseError,
 416                              UErrorCode& status);
 417
 418     /**
 419      * Returns a pattern that can be used to recreate this object.
 420      *
 421      * @param appendTo  Output parameter to receive the pattern.
 422      *                  Result is appended to existing contents.
 423      * @return          Reference to 'appendTo' parameter.
 424      * @stable ICU 2.0
 425      */
 426     virtual UnicodeString& toPattern(UnicodeString& appendTo) const;
 427
 428     /**
 429      * Sets subformats.
 430      * See the class description about format numbering.
 431      * The caller should not delete the Format objects after this call.
 432      * <EM>The array formatsToAdopt is not itself adopted.</EM> Its
 433      * ownership is retained by the caller. If the call fails because
 434      * memory cannot be allocated, then the formats will be deleted
 435      * by this method, and this object will remain unchanged.
 436      *
 437      * <p>If this format uses named arguments, the new formats are discarded
 438      * and this format remains unchanged.
 439      *
 440      * @stable ICU 2.0
 441      * @param formatsToAdopt    the format to be adopted.
 442      * @param count             the size of the array.
 443      */
 444     virtual void adoptFormats(Format** formatsToAdopt, int32_t count);
 445
 446     /**
 447      * Sets subformats.
 448      * See the class description about format numbering.
 449      * Each item in the array is cloned into the internal array.
 450      * If the call fails because memory cannot be allocated, then this
 451      * object will remain unchanged.
 452      *
 453      * <p>If this format uses named arguments, the new formats are discarded
 454      * and this format remains unchanged.
 455      *
 456      * @stable ICU 2.0
 457      * @param newFormats the new format to be set.
 458      * @param cnt        the size of the array.
 459      */
 460     virtual void setFormats(const Format** newFormats, int32_t cnt);
 461
 462
 463     /**
 464      * Sets one subformat.
 465      * See the class description about format numbering.
 466      * The caller should not delete the Format object after this call.
 467      * If the number is over the number of formats already set,
 468      * the item will be deleted and ignored.
 469      *
 470      * <p>If this format uses named arguments, the new format is discarded
 471      * and this format remains unchanged.
 472      *
 473      * @stable ICU 2.0
 474      * @param formatNumber     index of the subformat.
 475      * @param formatToAdopt    the format to be adopted.
 476      */
 477     virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt);
 478
 479     /**
 480      * Sets one subformat.
 481      * See the class description about format numbering.
 482      * If the number is over the number of formats already set,
 483      * the item will be ignored.
 484      * @param formatNumber     index of the subformat.
 485      * @param format    the format to be set.
 486      * @stable ICU 2.0
 487      */
 488     virtual void setFormat(int32_t formatNumber, const Format& format);
 489
 490     /**
 491      * Gets format names. This function returns formatNames in StringEnumerations
 492      * which can be used with getFormat() and setFormat() to export formattable
 493      * array from current MessageFormat to another.  It is caller's resposibility
 494      * to delete the returned formatNames.
 495      * @param status  output param set to success/failure code.
 496      * @stable ICU 4.0
 497      */
 498     virtual StringEnumeration* getFormatNames(UErrorCode& status);
 499
 500     /**
 501      * Gets subformat pointer for given format name.
 502      * This function supports both named and numbered
 503      * arguments-- if numbered, the formatName is the
 504      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 505      * The returned Format object should not be deleted by the caller,
 506      * nor should the ponter of other object .  The pointer and its
 507      * contents remain valid only until the next call to any method
 508      * of this class is made with this object.
 509      * @param formatName the name or number specifying a format
 510      * @param status  output param set to success/failure code.
 511      * @stable ICU 4.0
 512      */
 513     virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status);
 514
 515     /**
 516      * Sets one subformat for given format name.
 517      * See the class description about format name.
 518      * This function supports both named and numbered
 519      * arguments-- if numbered, the formatName is the
 520      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 521      * If there is no matched formatName or wrong type,
 522      * the item will be ignored.
 523      * @param formatName  Name of the subformat.
 524      * @param format      the format to be set.
 525      * @param status  output param set to success/failure code.
 526      * @stable ICU 4.0
 527      */
 528     virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status);
 529
 530     /**
 531      * Sets one subformat for given format name.
 532      * See the class description about format name.
 533      * This function supports both named and numbered
 534      * arguments-- if numbered, the formatName is the
 535      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 536      * If there is no matched formatName or wrong type,
 537      * the item will be ignored.
 538      * The caller should not delete the Format object after this call.
 539      * @param formatName  Name of the subformat.
 540      * @param formatToAdopt  Format to be adopted.
 541      * @param status      output param set to success/failure code.
 542      * @stable ICU 4.0
 543      */
 544     virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status);
 545
 546     /**
 547      * Gets an array of subformats of this object.  The returned array
 548      * should not be deleted by the caller, nor should the pointers
 549      * within the array.  The array and its contents remain valid only
 550      * until the next call to this format. See the class description
 551      * about format numbering.
 552      *
 553      * @param count output parameter to receive the size of the array
 554      * @return an array of count Format* objects, or NULL if out of
 555      * memory.  Any or all of the array elements may be NULL.
 556      * @stable ICU 2.0
 557      */
 558     virtual const Format** getFormats(int32_t& count) const;
 559
 560
 561     using Format::format;
 562
 563     /**
 564      * Formats the given array of arguments into a user-readable string.
 565      * Does not take ownership of the Formattable* array or its contents.
 566      *
 567      * <p>If this format uses named arguments, appendTo is unchanged and
 568      * status is set to U_ILLEGAL_ARGUMENT_ERROR.
 569      *
 570      * @param source    An array of objects to be formatted.
 571      * @param count     The number of elements of 'source'.
 572      * @param appendTo  Output parameter to receive result.
 573      *                  Result is appended to existing contents.
 574      * @param ignore    Not used; inherited from base class API.
 575      * @param status    Input/output error code.  If the
 576      *                  pattern cannot be parsed, set to failure code.
 577      * @return          Reference to 'appendTo' parameter.
 578      * @stable ICU 2.0
 579      */
 580     UnicodeString& format(const Formattable* source,
 581                           int32_t count,
 582                           UnicodeString& appendTo,
 583                           FieldPosition& ignore,
 584                           UErrorCode& status) const;
 585
 586     /**
 587      * Formats the given array of arguments into a user-readable string
 588      * using the given pattern.
 589      *
 590      * <p>If this format uses named arguments, appendTo is unchanged and
 591      * status is set to U_ILLEGAL_ARGUMENT_ERROR.
 592      *
 593      * @param pattern   The pattern.
 594      * @param arguments An array of objects to be formatted.
 595      * @param count     The number of elements of 'source'.
 596      * @param appendTo  Output parameter to receive result.
 597      *                  Result is appended to existing contents.
 598      * @param status    Input/output error code.  If the
 599      *                  pattern cannot be parsed, set to failure code.
 600      * @return          Reference to 'appendTo' parameter.
 601      * @stable ICU 2.0
 602      */
 603     static UnicodeString& format(const UnicodeString& pattern,
 604                                  const Formattable* arguments,
 605                                  int32_t count,
 606                                  UnicodeString& appendTo,
 607                                  UErrorCode& status);
 608
 609     /**
 610      * Formats the given array of arguments into a user-readable
 611      * string.  The array must be stored within a single Formattable
 612      * object of type kArray. If the Formattable object type is not of
 613      * type kArray, then returns a failing UErrorCode.
 614      *
 615      * <p>If this format uses named arguments, appendTo is unchanged and
 616      * status is set to U_ILLEGAL_ARGUMENT_ERROR.
 617      *
 618      * @param obj       A Formattable of type kArray containing
 619      *                  arguments to be formatted.
 620      * @param appendTo  Output parameter to receive result.
 621      *                  Result is appended to existing contents.
 622      * @param pos       On input: an alignment field, if desired.
 623      *                  On output: the offsets of the alignment field.
 624      * @param status    Input/output error code.  If the
 625      *                  pattern cannot be parsed, set to failure code.
 626      * @return          Reference to 'appendTo' parameter.
 627      * @stable ICU 2.0
 628      */
 629     virtual UnicodeString& format(const Formattable& obj,
 630                                   UnicodeString& appendTo,
 631                                   FieldPosition& pos,
 632                                   UErrorCode& status) const;
 633
 634     /**
 635      * Formats the given array of arguments into a user-readable
 636      * string.  The array must be stored within a single Formattable
 637      * object of type kArray. If the Formattable object type is not of
 638      * type kArray, then returns a failing UErrorCode.
 639      *
 640      * @param obj       The object to format
 641      * @param appendTo  Output parameter to receive result.
 642      *                  Result is appended to existing contents.
 643      * @param status    Input/output error code.  If the
 644      *                  pattern cannot be parsed, set to failure code.
 645      * @return          Reference to 'appendTo' parameter.
 646      * @stable ICU 2.0
 647      */
 648     UnicodeString& format(const Formattable& obj,
 649                           UnicodeString& appendTo,
 650                           UErrorCode& status) const;
 651
 652
 653     /**
 654      * Formats the given array of arguments into a user-defined argument name
 655      * array. This function supports both named and numbered
 656      * arguments-- if numbered, the formatName is the
 657      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 658      *
 659      * @param argumentNames argument name array
 660      * @param arguments An array of objects to be formatted.
 661      * @param count     The number of elements of 'argumentNames' and
 662      *                  arguments.  The number of argumentNames and arguments
 663      *                  must be the same.
 664      * @param appendTo  Output parameter to receive result.
 665      *                  Result is appended to existing contents.
 666      * @param status    Input/output error code.  If the
 667      *                  pattern cannot be parsed, set to failure code.
 668      * @return          Reference to 'appendTo' parameter.
 669      * @stable ICU 4.0
 670      */
 671     UnicodeString& format(const UnicodeString* argumentNames,
 672                           const Formattable* arguments,
 673                           int32_t count,
 674                           UnicodeString& appendTo,
 675                           UErrorCode& status) const;
 676     /**
 677      * Parses the given string into an array of output arguments.
 678      *
 679      * @param source    String to be parsed.
 680      * @param pos       On input, starting position for parse. On output,
 681      *                  final position after parse.  Unchanged if parse
 682      *                  fails.
 683      * @param count     Output parameter to receive the number of arguments
 684      *                  parsed.
 685      * @return an array of parsed arguments.  The caller owns both
 686      * the array and its contents.
 687      * @stable ICU 2.0
 688      */
 689     virtual Formattable* parse(const UnicodeString& source,
 690                                ParsePosition& pos,
 691                                int32_t& count) const;
 692
 693     /**
 694      * Parses the given string into an array of output arguments.
 695      *
 696      * <p>If this format uses named arguments, status is set to
 697      * U_ARGUMENT_TYPE_MISMATCH.
 698      *
 699      * @param source    String to be parsed.
 700      * @param count     Output param to receive size of returned array.
 701      * @param status    Input/output error code.  If the
 702      *                  pattern cannot be parsed, set to failure code.
 703      * @return an array of parsed arguments.  The caller owns both
 704      * the array and its contents. Returns NULL if status is not U_ZERO_ERROR.
 705      *
 706      * @stable ICU 2.0
 707      */
 708     virtual Formattable* parse(const UnicodeString& source,
 709                                int32_t& count,
 710                                UErrorCode& status) const;
 711
 712     /**
 713      * Parses the given string into an array of output arguments
 714      * stored within a single Formattable of type kArray.
 715      *
 716      * @param source    The string to be parsed into an object.
 717      * @param result    Formattable to be set to the parse result.
 718      *                  If parse fails, return contents are undefined.
 719      * @param pos       On input, starting position for parse. On output,
 720      *                  final position after parse.  Unchanged if parse
 721      *                  fails.
 722      * @stable ICU 2.0
 723      */
 724     virtual void parseObject(const UnicodeString& source,
 725                              Formattable& result,
 726                              ParsePosition& pos) const;
 727
 728     /**
 729      * Convert an 'apostrophe-friendly' pattern into a standard
 730      * pattern.  Standard patterns treat all apostrophes as
 731      * quotes, which is problematic in some languages, e.g.
 732      * French, where apostrophe is commonly used.  This utility
 733      * assumes that only an unpaired apostrophe immediately before
 734      * a brace is a true quote.  Other unpaired apostrophes are paired,
 735      * and the resulting standard pattern string is returned.
 736      *
 737      * <p><b>Note</b> it is not guaranteed that the returned pattern
 738      * is indeed a valid pattern.  The only effect is to convert
 739      * between patterns having different quoting semantics.
 740      *
 741      * @param pattern the 'apostrophe-friendly' patttern to convert
 742      * @param status    Input/output error code.  If the pattern
 743      *                  cannot be parsed, the failure code is set.
 744      * @return the standard equivalent of the original pattern
 745      * @stable ICU 3.4
 746      */
 747     static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern,
 748         UErrorCode& status);
 749
 750     /**
 751      * Returns true if this MessageFormat uses named arguments,
 752      * and false otherwise.  See class description.
 753      *
 754      * @return true if named arguments are used.
 755      * @stable ICU 4.0
 756      */
 757     UBool usesNamedArguments() const;
 758
 759
 760     /**
 761      * This API is for ICU internal use only.
 762      * Please do not use it.
 763      *
 764      * Returns argument types count in the parsed pattern.
 765      * Used to distinguish pattern "{0} d" and "d".
 766      *
 767      * @return           The number of formattable types in the pattern
 768      * @internal
 769      */
 770     int32_t getArgTypeCount() const;
 771
 772     /**
 773      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
 774      * This method is to implement a simple version of RTTI, since not all
 775      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
 776      * clone() methods call this method.
 777      *
 778      * @return          The class ID for this object. All objects of a
 779      *                  given class have the same class ID.  Objects of
 780      *                  other classes have different class IDs.
 781      * @stable ICU 2.0
 782      */
 783     virtual UClassID getDynamicClassID(void) const;
 784
 785     /**
 786      * Return the class ID for this class.  This is useful only for
 787      * comparing to a return value from getDynamicClassID().  For example:
 788      * <pre>
 789      * .   Base* polymorphic_pointer = createPolymorphicObject();
 790      * .   if (polymorphic_pointer->getDynamicClassID() ==
 791      * .      Derived::getStaticClassID()) ...
 792      * </pre>
 793      * @return          The class ID for all objects of this class.
 794      * @stable ICU 2.0
 795      */
 796     static UClassID U_EXPORT2 getStaticClassID(void);
 797
 798 private:
 799
 800     Locale              fLocale;
 801     UnicodeString       fPattern;
 802     Format**            formatAliases; // see getFormats
 803     int32_t             formatAliasesCapacity;
 804     UProperty           idStart;
 805     UProperty           idContinue;
 806
 807     MessageFormat(); // default constructor not implemented
 808
 809     /*
 810      * A structure representing one subformat of this MessageFormat.
 811      * Each subformat has a Format object, an offset into the plain
 812      * pattern text fPattern, and an argument number.  The argument
 813      * number corresponds to the array of arguments to be formatted.
 814      * @internal
 815      */
 816     class Subformat;
 817
 818     /**
 819      * A MessageFormat contains an array of subformats.  This array
 820      * needs to grow dynamically if the MessageFormat is modified.
 821      */
 822     Subformat* subformats;
 823     int32_t    subformatCount;
 824     int32_t    subformatCapacity;
 825
 826     /**
 827      * A MessageFormat formats an array of arguments.  Each argument
 828      * has an expected type, based on the pattern.  For example, if
 829      * the pattern contains the subformat "{3,number,integer}", then
 830      * we expect argument 3 to have type Formattable::kLong.  This
 831      * array needs to grow dynamically if the MessageFormat is
 832      * modified.
 833      */
 834     Formattable::Type* argTypes;
 835     int32_t            argTypeCount;
 836     int32_t            argTypeCapacity;
 837
 838     /**
 839       * Is true iff all argument names are non-negative numbers.
 840       *
 841       */
 842     UBool isArgNumeric;
 843
 844     // Variable-size array management
 845     UBool allocateSubformats(int32_t capacity);
 846     UBool allocateArgTypes(int32_t capacity);
 847
 848     /**
 849      * Default Format objects used when no format is specified and a
 850      * numeric or date argument is formatted.  These are volatile
 851      * cache objects maintained only for performance.  They do not
 852      * participate in operator=(), copy constructor(), nor
 853      * operator==().
 854      */
 855     NumberFormat* defaultNumberFormat;
 856     DateFormat*   defaultDateFormat;
 857
 858     /**
 859      * Method to retrieve default formats (or NULL on failure).
 860      * These are semantically const, but may modify *this.
 861      */
 862     const NumberFormat* getDefaultNumberFormat(UErrorCode&) const;
 863     const DateFormat*   getDefaultDateFormat(UErrorCode&) const;
 864
 865     /**
 866      * Finds the word s, in the keyword list and returns the located index.
 867      * @param s the keyword to be searched for.
 868      * @param list the list of keywords to be searched with.
 869      * @return the index of the list which matches the keyword s.
 870      */
 871     static int32_t findKeyword( const UnicodeString& s,
 872                                 const UChar * const *list);
 873
 874     /**
 875      * Formats the array of arguments and copies the result into the
 876      * result buffer, updates the field position.
 877      *
 878      * @param arguments The formattable objects array.
 879      * @param cnt       The array count.
 880      * @param appendTo  Output parameter to receive result.
 881      *                  Result is appended to existing contents.
 882      * @param status    Field position status.
 883      * @param recursionProtection
 884      *                  Initially zero. Bits 0..9 are used to indicate
 885      *                  that a parameter has already been seen, to
 886      *                  avoid recursion.  Currently unused.
 887      * @param success   The error code status.
 888      * @return          Reference to 'appendTo' parameter.
 889      */
 890     UnicodeString&  format( const Formattable* arguments,
 891                             int32_t cnt,
 892                             UnicodeString& appendTo,
 893                             FieldPosition& status,
 894                             int32_t recursionProtection,
 895                             UErrorCode& success) const;
 896
 897     UnicodeString&  format( const Formattable* arguments,
 898                             const UnicodeString *argumentNames,
 899                             int32_t cnt,
 900                             UnicodeString& appendTo,
 901                             FieldPosition& status,
 902                             int32_t recursionProtection,
 903                             UErrorCode& success) const;
 904
 905     void             makeFormat(int32_t offsetNumber,
 906                                 UnicodeString* segments,
 907                                 UParseError& parseError,
 908                                 UErrorCode& success);
 909
 910     /**
 911      * Convenience method that ought to be in NumberFormat
 912      */
 913     NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const;
 914
 915     /**
 916      * Checks the range of the source text to quote the special
 917      * characters, { and ' and copy to target buffer.
 918      * @param source
 919      * @param start the text offset to start the process of in the source string
 920      * @param end the text offset to end the process of in the source string
 921      * @param appendTo  Output parameter to receive result.
 922      *                  Result is appended to existing contents.
 923      */
 924     static void copyAndFixQuotes(const UnicodeString& appendTo, int32_t start, int32_t end, UnicodeString& target);
 925
 926     /**
 927      * Returns array of argument types in the parsed pattern
 928      * for use in C API.  Only for the use of umsg_vformat().  Not
 929      * for public consumption.
 930      * @param listCount  Output parameter to receive the size of array
 931      * @return           The array of formattable types in the pattern
 932      * @internal
 933      */
 934     const Formattable::Type* getArgTypeList(int32_t& listCount) const {
 935         listCount = argTypeCount;
 936         return argTypes;
 937     }
 938
 939     /**
 940      * Returns FALSE if the argument name is not legal.
 941      * @param  argName   argument name.
 942      * @return TRUE if the argument name is legal, otherwise return FALSE.
 943      */
 944     UBool isLegalArgName(const UnicodeString& argName) const;
 945
 946     friend class MessageFormatAdapter; // getFormatTypeList() access
 947 };
 948
 949 inline UnicodeString&
 950 MessageFormat::format(const Formattable& obj,
 951                       UnicodeString& appendTo,
 952                       UErrorCode& status) const {
 953     return Format::format(obj, appendTo, status);
 954 }
 955
 956 U_NAMESPACE_END
 957
 958 #endif /* #if !UCONFIG_NO_FORMATTING */
 959
 960 #endif // _MSGFMT
 961 //eof