icuSources/i18n/unicode/msgfmt.h

   1 /*
   2 * Copyright (C) 2007-2008, International Business Machines Corporation and others. All Rights Reserved.
   3 ********************************************************************************
   4 *
   5 * File MSGFMT.H
   6 *
   7 * Modification History:
   8 *
   9 *   Date        Name        Description
  10 *   02/19/97    aliu        Converted from java.
  11 *   03/20/97    helena      Finished first cut of implementation.
  12 *   07/22/98    stephen     Removed operator!= (defined in Format)
  13 *   08/19/2002  srl         Removing Javaisms
  14 ********************************************************************************
  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  * A MessageFormat produces concatenated messages in a
  42  * language-neutral way.  It should be used for all string
  43  * concatenations that are visible to end users.
  44  * <P>
  45  * 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  * <P>
  50  * 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  * <P>
  54  * During formatting, the 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 resultant strings are then assembled
  60  * within the string template of the MessageFormat to produce the
  61  * final output string.
  62  * <p>
  63  * <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  * <p>
  70  * 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 Formattable* arguments, const UnicodeString *argumentNames, int32_t cnt, UnicodeString& appendTo, FieldPosition& status, int32_t recursionProtection, UErrorCode& success)},
  76  * {@link #format(const UnicodeString* argumentNames, const Formattable* arguments, 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  * <p>
  81  * When named arguments are used, certain methods on MessageFormat 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.  UErrorCode is set to
  84  * U_ARGUMENT_TYPE_MISMATCH if there is a status/success field in the method.
  85  * These methods are
  86  * {@link #adoptFormats(Format** newFormats, int32_t count)},
  87  * {@link #setFormats(const Format** newFormats,int32_t count)},
  88  * {@link #adoptFormat(int32_t n, Format *newFormat)},
  89  * {@link #getFormats(int32_t& cnt)},
  90  * {@link #format(const Formattable* source,int32_t cnt,UnicodeString& appendTo, FieldPosition& ignore, UErrorCode& success)},
  91  * {@link #format(const UnicodeString& pattern,const Formattable* arguments,int32_t cnt,UnicodeString& appendTo,UErrorCode& success)},
  92  * {@link #format(const Formattable& source, UnicodeString& appendTo,FieldPosition& ignore, UErrorCode& success)},
  93  * {@link #format(const Formattable* arguments, int32_t cnt, UnicodeString& appendTo, FieldPosition& status, int32_t recursionProtection,UErrorCode& success)},
  94  * {@link #parse(const UnicodeString& source, ParsePosition& pos,int32_t& count)},
  95  * {@link #parse(const UnicodeString& source, int32_t& cnt, UErrorCode& status)}
  96  * <p>
  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 intput 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 is 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 quotes 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  *
 194  *       datetimeStyle := "short"
 195  *                      | "medium"
 196  *                      | "long"
 197  *                      | "full"
 198  *                      | dateFormatPattern
 199  *
 200  *       numberStyle :=   "currency"
 201  *                      | "percent"
 202  *                      | "integer"
 203  *                      | numberFormatPattern
 204  *
 205  *       choiceStyle :=   choiceFormatPattern
 206  *
 207  *       pluralStyle := pluralFormatPattern
 208  * \endcode
 209  * </pre>
 210  * If there is no elementFormat, then the argument must be a string,
 211  * which is substituted. If there is no dateTimeStyle or numberStyle,
 212  * then the default format is used (e.g.  NumberFormat::createInstance(),
 213  * DateFormat::createTimeInstance(DateFormat::kDefault, ...) or DateFormat::createDateInstance(DateFormat::kDefault, ...). For
 214  * a ChoiceFormat, the pattern must always be specified, since there
 215  * is no default.
 216  * <P>
 217  * In strings, single quotes can be used to quote syntax characters.
 218  * A literal single quote is represented by '', both within and outside
 219  * of single-quoted segments.  Inside a
 220  * messageFormatElement, quotes are <EM>not</EM> removed. For example,
 221  * {1,number,$'#',##} will produce a number format with the pound-sign
 222  * quoted, with a result such as: "$#31,45".
 223  * <P>
 224  * If a pattern is used, then unquoted braces in the pattern, if any,
 225  * must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab
 226  * {0'}' de" and "ab } de" are not.
 227  * <p>
 228  * <dl><dt><b>Warning:</b><dd>The rules for using quotes within message
 229  * format patterns unfortunately have shown to be somewhat confusing.
 230  * In particular, it isn't always obvious to localizers whether single
 231  * quotes need to be doubled or not. Make sure to inform localizers about
 232  * the rules, and tell them (for example, by using comments in resource
 233  * bundle source files) which strings will be processed by MessageFormat.
 234  * Note that localizers may need to use single quotes in translated
 235  * strings where the original version doesn't have them.
 236  * <br>Note also that the simplest way to avoid the problem is to
 237  * use the real apostrophe (single quote) character U+2019 (') for
 238  * human-readable text, and to use the ASCII apostrophe (U+0027 ' )
 239  * only in program syntax, like quoting in MessageFormat.
 240  * See the annotations for U+0027 Apostrophe in The Unicode Standard.</p>
 241  * </dl>
 242  * <P>
 243  * The argumentIndex is a non-negative integer, which corresponds to the
 244  * index of the arguments presented in an array to be formatted.  The
 245  * first argument has argumentIndex 0.
 246  * <P>
 247  * It is acceptable to have unused arguments in the array.  With missing
 248  * arguments or arguments that are not of the right class for the
 249  * specified format, a failing UErrorCode result is set.
 250  * <P>
 251  * For more sophisticated patterns, you can use a ChoiceFormat to get
 252  * output:
 253  * <pre>
 254  * \code
 255  *     UErrorCode success = U_ZERO_ERROR;
 256  *     MessageFormat* form("The disk \"{1}\" contains {0}.", success);
 257  *     double filelimits[] = {0,1,2};
 258  *     UnicodeString filepart[] = {"no files","one file","{0,number} files"};
 259  *     ChoiceFormat* fileform = new ChoiceFormat(filelimits, filepart, 3);
 260  *     form.setFormat(1, *fileform); // NOT zero, see below
 261  *
 262  *     Formattable testArgs[] = {1273L, "MyDisk"};
 263  *
 264  *     UnicodeString string;
 265  *     FieldPosition fpos = 0;
 266  *     cout << form.format(testArgs, 2, string, fpos, success) << endl;
 267  *
 268  *     // output, with different testArgs
 269  *     // output: The disk "MyDisk" contains no files.
 270  *     // output: The disk "MyDisk" contains one file.
 271  *     // output: The disk "MyDisk" contains 1,273 files.
 272  * \endcode
 273  * </pre>
 274  * You can either do this programmatically, as in the above example,
 275  * or by using a pattern (see ChoiceFormat for more information) as in:
 276  * <pre>
 277  * \code
 278  *    form.applyPattern(
 279  *      "There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.");
 280  * \endcode
 281  * </pre>
 282  * <P>
 283  * <EM>Note:</EM> As we see above, the string produced by a ChoiceFormat in
 284  * MessageFormat is treated specially; occurences of '{' are used to
 285  * indicated subformats, and cause recursion.  If you create both a
 286  * MessageFormat and ChoiceFormat programmatically (instead of using
 287  * the string patterns), then be careful not to produce a format that
 288  * recurses on itself, which will cause an infinite loop.
 289  * <P>
 290  * <EM>Note:</EM> Subformats are numbered by their order in the pattern.
 291  * This is <EM>not</EM> the same as the argumentIndex.
 292  * <pre>
 293  * \code
 294  *    For example: with "abc{2}def{3}ghi{0}...",
 295  *
 296  *    format0 affects the first variable {2}
 297  *    format1 affects the second variable {3}
 298  *    format2 affects the second variable {0}
 299  * \endcode
 300  * </pre>
 301  *
 302  * <p><em>User subclasses are not supported.</em> While clients may write
 303  * subclasses, such code will not necessarily work and will not be
 304  * guaranteed to work stably from release to release.
 305  */
 306 class U_I18N_API MessageFormat : public Format {
 307 public:
 308     /**
 309      * Enum type for kMaxFormat.
 310      * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,
 311      * rendering this enum type obsolete.
 312      */
 313     enum EFormatNumber {
 314         /**
 315          * The maximum number of arguments.
 316          * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,
 317          * rendering this constant obsolete.
 318          */
 319         kMaxFormat = 10
 320     };
 321
 322     /**
 323      * Constructs a new MessageFormat using the given pattern and the
 324      * default locale.
 325      *
 326      * @param pattern   Pattern used to construct object.
 327      * @param status    Input/output error code.  If the
 328      *                  pattern cannot be parsed, set to failure code.
 329      * @stable ICU 2.0
 330      */
 331     MessageFormat(const UnicodeString& pattern,
 332                   UErrorCode &status);
 333
 334     /**
 335      * Constructs a new MessageFormat using the given pattern and locale.
 336      * @param pattern   Pattern used to construct object.
 337      * @param newLocale The locale to use for formatting dates and numbers.
 338      * @param status    Input/output error code.  If the
 339      *                  pattern cannot be parsed, set to failure code.
 340      * @stable ICU 2.0
 341      */
 342     MessageFormat(const UnicodeString& pattern,
 343                   const Locale& newLocale,
 344                         UErrorCode& status);
 345     /**
 346      * Constructs a new MessageFormat using the given pattern and locale.
 347      * @param pattern   Pattern used to construct object.
 348      * @param newLocale The locale to use for formatting dates and numbers.
 349      * @param parseError Struct to recieve information on position
 350      *                   of error within the pattern.
 351      * @param status    Input/output error code.  If the
 352      *                  pattern cannot be parsed, set to failure code.
 353      * @stable ICU 2.0
 354      */
 355     MessageFormat(const UnicodeString& pattern,
 356                   const Locale& newLocale,
 357                   UParseError& parseError,
 358                   UErrorCode& status);
 359     /**
 360      * Constructs a new MessageFormat from an existing one.
 361      * @stable ICU 2.0
 362      */
 363     MessageFormat(const MessageFormat&);
 364
 365     /**
 366      * Assignment operator.
 367      * @stable ICU 2.0
 368      */
 369     const MessageFormat& operator=(const MessageFormat&);
 370
 371     /**
 372      * Destructor.
 373      * @stable ICU 2.0
 374      */
 375     virtual ~MessageFormat();
 376
 377     /**
 378      * Clones this Format object polymorphically.  The caller owns the
 379      * result and should delete it when done.
 380      * @stable ICU 2.0
 381      */
 382     virtual Format* clone(void) const;
 383
 384     /**
 385      * Returns true if the given Format objects are semantically equal.
 386      * Objects of different subclasses are considered unequal.
 387      * @param other  the object to be compared with.
 388      * @return       true if the given Format objects are semantically equal.
 389      * @stable ICU 2.0
 390      */
 391     virtual UBool operator==(const Format& other) const;
 392
 393     /**
 394      * Sets the locale. This locale is used for fetching default number or date
 395      * format information.
 396      * @param theLocale    the new locale value to be set.
 397      * @stable ICU 2.0
 398      */
 399     virtual void setLocale(const Locale& theLocale);
 400
 401     /**
 402      * Gets the locale. This locale is used for fetching default number or date
 403      * format information.
 404      * @return    the locale of the object.
 405      * @stable ICU 2.0
 406      */
 407     virtual const Locale& getLocale(void) const;
 408
 409     /**
 410      * Applies the given pattern string to this message format.
 411      *
 412      * @param pattern   The pattern to be applied.
 413      * @param status    Input/output error code.  If the
 414      *                  pattern cannot be parsed, set to failure code.
 415      * @stable ICU 2.0
 416      */
 417     virtual void applyPattern(const UnicodeString& pattern,
 418                               UErrorCode& status);
 419     /**
 420      * Applies the given pattern string to this message format.
 421      *
 422      * @param pattern    The pattern to be applied.
 423      * @param parseError Struct to recieve information on position
 424      *                   of error within pattern.
 425      * @param status    Input/output error code.  If the
 426      *                  pattern cannot be parsed, set to failure code.
 427      * @stable ICU 2.0
 428      */
 429     virtual void applyPattern(const UnicodeString& pattern,
 430                              UParseError& parseError,
 431                              UErrorCode& status);
 432
 433     /**
 434      * Returns a pattern that can be used to recreate this object.
 435      *
 436      * @param appendTo  Output parameter to receive the pattern.
 437      *                  Result is appended to existing contents.
 438      * @return          Reference to 'appendTo' parameter.
 439      * @stable ICU 2.0
 440      */
 441     virtual UnicodeString& toPattern(UnicodeString& appendTo) const;
 442
 443     /**
 444      * Sets subformats.
 445      * See the class description about format numbering.
 446      * The caller should not delete the Format objects after this call.
 447      * <EM>The array formatsToAdopt is not itself adopted.</EM> Its
 448      * ownership is retained by the caller. If the call fails because
 449      * memory cannot be allocated, then the formats will be deleted
 450      * by this method, and this object will remain unchanged.
 451      *
 452      * @stable ICU 2.0
 453      * @param formatsToAdopt    the format to be adopted.
 454      * @param count             the size of the array.
 455      */
 456     virtual void adoptFormats(Format** formatsToAdopt, int32_t count);
 457
 458     /**
 459      * Sets subformats.
 460      * See the class description about format numbering.
 461      * Each item in the array is cloned into the internal array.
 462      * If the call fails because memory cannot be allocated, then this
 463      * object will remain unchanged.
 464      *
 465      * @stable ICU 2.0
 466      * @param newFormats the new format to be set.
 467      * @param cnt        the size of the array.
 468      */
 469     virtual void setFormats(const Format** newFormats, int32_t cnt);
 470
 471
 472     /**
 473      * Sets one subformat.
 474      * See the class description about format numbering.
 475      * The caller should not delete the Format object after this call.
 476      * If the number is over the number of formats already set,
 477      * the item will be deleted and ignored.
 478      * @stable ICU 2.0
 479      * @param formatNumber     index of the subformat.
 480      * @param formatToAdopt    the format to be adopted.
 481      */
 482     virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt);
 483
 484     /**
 485      * Sets one subformat.
 486      * See the class description about format numbering.
 487      * If the number is over the number of formats already set,
 488      * the item will be ignored.
 489      * @param formatNumber     index of the subformat.
 490      * @param format    the format to be set.
 491      * @stable ICU 2.0
 492      */
 493     virtual void setFormat(int32_t formatNumber, const Format& format);
 494
 495     /**
 496      * Gets format names. This function returns formatNames in StringEnumerations
 497      * which can be used with getFormat() and setFormat() to export formattable
 498      * array from current MessageFormat to another.  It is caller's resposibility
 499      * to delete the returned formatNames.
 500      * @param status  output param set to success/failure code.
 501      * @draft ICU 4.0
 502      */
 503     virtual StringEnumeration* getFormatNames(UErrorCode& status);
 504
 505     /**
 506      * Gets subformat pointer for given format name.
 507      * This function supports both named and numbered
 508      * arguments-- if numbered, the formatName is the
 509      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 510      * The returned Format object should not be deleted by the caller,
 511      * nor should the ponter of other object .  The pointer and its
 512      * contents remain valid only until the next call to any method
 513      * of this class is made with this object.
 514      * @param formatName the name or number specifying a format
 515      * @param status  output param set to success/failure code.
 516      * @draft ICU 4.0
 517      */
 518     virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status);
 519
 520     /**
 521      * Sets one subformat for given format name.
 522      * See the class description about format name.
 523      * This function supports both named and numbered
 524      * arguments-- if numbered, the formatName is the
 525      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 526      * If there is no matched formatName or wrong type,
 527      * the item will be ignored.
 528      * @param formatName  Name of the subformat.
 529      * @param format      the format to be set.
 530      * @param status  output param set to success/failure code.
 531      * @draft ICU 4.0
 532      */
 533     virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status);
 534
 535     /**
 536      * Sets one subformat for given format name.
 537      * See the class description about format name.
 538      * This function supports both named and numbered
 539      * arguments-- if numbered, the formatName is the
 540      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 541      * If there is no matched formatName or wrong type,
 542      * the item will be ignored.
 543      * The caller should not delete the Format object after this call.
 544      * @param formatName  Name of the subformat.
 545      * @param formatToAdopt  Format to be adopted.
 546      * @param status      output param set to success/failure code.
 547      * @draft ICU 4.0
 548      */
 549     virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status);
 550
 551
 552     /**
 553      * Gets an array of subformats of this object.  The returned array
 554      * should not be deleted by the caller, nor should the pointers
 555      * within the array.  The array and its contents remain valid only
 556      * until the next call to any method of this class is made with
 557      * this object.  See the class description about format numbering.
 558      * @param count output parameter to receive the size of the array
 559      * @return an array of count Format* objects, or NULL if out of
 560      * memory.  Any or all of the array elements may be NULL.
 561      * @stable ICU 2.0
 562      */
 563     virtual const Format** getFormats(int32_t& count) const;
 564
 565     /**
 566      * Formats the given array of arguments into a user-readable string.
 567      * Does not take ownership of the Formattable* array or its contents.
 568      *
 569      * @param source    An array of objects to be formatted.
 570      * @param count     The number of elements of 'source'.
 571      * @param appendTo  Output parameter to receive result.
 572      *                  Result is appended to existing contents.
 573      * @param ignore    Not used; inherited from base class API.
 574      * @param status    Input/output error code.  If the
 575      *                  pattern cannot be parsed, set to failure code.
 576      * @return          Reference to 'appendTo' parameter.
 577      * @stable ICU 2.0
 578      */
 579     UnicodeString& format(  const Formattable* source,
 580                             int32_t count,
 581                             UnicodeString& appendTo,
 582                             FieldPosition& ignore,
 583                             UErrorCode& status) const;
 584
 585     /**
 586      * Formats the given array of arguments into a user-readable string
 587      * using the given pattern.
 588      *
 589      * @param pattern   The pattern.
 590      * @param arguments An array of objects to be formatted.
 591      * @param count     The number of elements of 'source'.
 592      * @param appendTo  Output parameter to receive result.
 593      *                  Result is appended to existing contents.
 594      * @param status    Input/output error code.  If the
 595      *                  pattern cannot be parsed, set to failure code.
 596      * @return          Reference to 'appendTo' parameter.
 597      * @stable ICU 2.0
 598      */
 599     static UnicodeString& format(const UnicodeString& pattern,
 600                                  const Formattable* arguments,
 601                                  int32_t count,
 602                                  UnicodeString& appendTo,
 603                                  UErrorCode& status);
 604
 605     /**
 606      * Formats the given array of arguments into a user-readable
 607      * string.  The array must be stored within a single Formattable
 608      * object of type kArray. If the Formattable object type is not of
 609      * type kArray, then returns a failing UErrorCode.
 610      *
 611      * @param obj       A Formattable of type kArray containing
 612      *                  arguments to be formatted.
 613      * @param appendTo  Output parameter to receive result.
 614      *                  Result is appended to existing contents.
 615      * @param pos       On input: an alignment field, if desired.
 616      *                  On output: the offsets of the alignment field.
 617      * @param status    Input/output error code.  If the
 618      *                  pattern cannot be parsed, set to failure code.
 619      * @return          Reference to 'appendTo' parameter.
 620      * @stable ICU 2.0
 621      */
 622     virtual UnicodeString& format(const Formattable& obj,
 623                                   UnicodeString& appendTo,
 624                                   FieldPosition& pos,
 625                                   UErrorCode& status) const;
 626
 627     /**
 628      * Formats the given array of arguments into a user-readable
 629      * string.  The array must be stored within a single Formattable
 630      * object of type kArray. If the Formattable object type is not of
 631      * type kArray, then returns a failing UErrorCode.
 632      *
 633      * @param obj       The object to format
 634      * @param appendTo  Output parameter to receive result.
 635      *                  Result is appended to existing contents.
 636      * @param status    Input/output error code.  If the
 637      *                  pattern cannot be parsed, set to failure code.
 638      * @return          Reference to 'appendTo' parameter.
 639      * @stable ICU 2.0
 640      */
 641     UnicodeString& format(const Formattable& obj,
 642                           UnicodeString& appendTo,
 643                           UErrorCode& status) const;
 644
 645
 646     /**
 647      * Formats the given array of arguments into a user-defined argument name
 648      * array. This function supports both named and numbered
 649      * arguments-- if numbered, the formatName is the
 650      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
 651      *
 652      * @param argumentNames argument name array
 653      * @param arguments An array of objects to be formatted.
 654      * @param count     The number of elements of 'argumentNames' and
 655      *                  arguments.  The number of argumentNames and arguments
 656      *                  must be the same.
 657      * @param appendTo  Output parameter to receive result.
 658      *                  Result is appended to existing contents.
 659      * @param status    Input/output error code.  If the
 660      *                  pattern cannot be parsed, set to failure code.
 661      * @return          Reference to 'appendTo' parameter.
 662      * @stable ICU 4.0
 663      */
 664     UnicodeString& format(const UnicodeString* argumentNames,
 665                           const Formattable* arguments,
 666                           int32_t count,
 667                           UnicodeString& appendTo,
 668                           UErrorCode& status) const;
 669     /**
 670      * Parses the given string into an array of output arguments.
 671      *
 672      * @param source    String to be parsed.
 673      * @param pos       On input, starting position for parse. On output,
 674      *                  final position after parse.  Unchanged if parse
 675      *                  fails.
 676      * @param count     Output parameter to receive the number of arguments
 677      *                  parsed.
 678      * @return an array of parsed arguments.  The caller owns both
 679      * the array and its contents.
 680      * @stable ICU 2.0
 681      */
 682     virtual Formattable* parse( const UnicodeString& source,
 683                                 ParsePosition& pos,
 684                                 int32_t& count) const;
 685
 686     /**
 687      * Parses the given string into an array of output arguments.
 688      *
 689      * @param source    String to be parsed.
 690      * @param count     Output param to receive size of returned array.
 691      * @param status    Input/output error code.  If the
 692      *                  pattern cannot be parsed, set to failure code.
 693      *                  If the MessageFormat is named argument, the status is
 694      *                  set to U_ARGUMENT_TYPE_MISMATCH.
 695      * @return an array of parsed arguments.  The caller owns both
 696      * the array and its contents. Return NULL if status is not U_ZERO_ERROR.
 697      *
 698      * @stable ICU 2.0
 699      */
 700     virtual Formattable* parse( const UnicodeString& source,
 701                                 int32_t& count,
 702                                 UErrorCode& status) const;
 703
 704     /**
 705      * Parses the given string into an array of output arguments
 706      * stored within a single Formattable of type kArray.
 707      *
 708      * @param source    The string to be parsed into an object.
 709      * @param result    Formattable to be set to the parse result.
 710      *                  If parse fails, return contents are undefined.
 711      * @param pos       On input, starting position for parse. On output,
 712      *                  final position after parse.  Unchanged if parse
 713      *                  fails.
 714      * @stable ICU 2.0
 715      */
 716     virtual void parseObject(const UnicodeString& source,
 717                              Formattable& result,
 718                              ParsePosition& pos) const;
 719
 720     /**
 721      * Convert an 'apostrophe-friendly' pattern into a standard
 722      * pattern.  Standard patterns treat all apostrophes as
 723      * quotes, which is problematic in some languages, e.g.
 724      * French, where apostrophe is commonly used.  This utility
 725      * assumes that only an unpaired apostrophe immediately before
 726      * a brace is a true quote.  Other unpaired apostrophes are paired,
 727      * and the resulting standard pattern string is returned.
 728      *
 729      * <p><b>Note</b> it is not guaranteed that the returned pattern
 730      * is indeed a valid pattern.  The only effect is to convert
 731      * between patterns having different quoting semantics.
 732      *
 733      * @param pattern the 'apostrophe-friendly' patttern to convert
 734      * @param status    Input/output error code.  If the pattern
 735      *                  cannot be parsed, the failure code is set.
 736      * @return the standard equivalent of the original pattern
 737      * @stable ICU 3.4
 738      */
 739     static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern,
 740         UErrorCode& status);
 741
 742     /**
 743      * Returns true if this MessageFormat uses named arguments,
 744      * and false otherwise.  See class description.
 745      *
 746      * @return true if named arguments are used.
 747      * @draft ICU 4.0
 748      */
 749     UBool usesNamedArguments() const;
 750
 751     /**
 752      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
 753      * This method is to implement a simple version of RTTI, since not all
 754      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
 755      * clone() methods call this method.
 756      *
 757      * @return          The class ID for this object. All objects of a
 758      *                  given class have the same class ID.  Objects of
 759      *                  other classes have different class IDs.
 760      * @stable ICU 2.0
 761      */
 762     virtual UClassID getDynamicClassID(void) const;
 763
 764     /**
 765      * Return the class ID for this class.  This is useful only for
 766      * comparing to a return value from getDynamicClassID().  For example:
 767      * <pre>
 768      * .   Base* polymorphic_pointer = createPolymorphicObject();
 769      * .   if (polymorphic_pointer->getDynamicClassID() ==
 770      * .      Derived::getStaticClassID()) ...
 771      * </pre>
 772      * @return          The class ID for all objects of this class.
 773      * @stable ICU 2.0
 774      */
 775     static UClassID U_EXPORT2 getStaticClassID(void);
 776
 777 private:
 778
 779     Locale              fLocale;
 780     UnicodeString       fPattern;
 781     Format**            formatAliases; // see getFormats
 782     int32_t             formatAliasesCapacity;
 783     UProperty           idStart;
 784     UProperty           idContinue;
 785
 786     MessageFormat(); // default constructor not implemented
 787
 788     /*
 789      * A structure representing one subformat of this MessageFormat.
 790      * Each subformat has a Format object, an offset into the plain
 791      * pattern text fPattern, and an argument number.  The argument
 792      * number corresponds to the array of arguments to be formatted.
 793      * @internal
 794      */
 795     class Subformat;
 796
 797     /**
 798      * A MessageFormat contains an array of subformats.  This array
 799      * needs to grow dynamically if the MessageFormat is modified.
 800      */
 801     Subformat* subformats;
 802     int32_t    subformatCount;
 803     int32_t    subformatCapacity;
 804
 805     /**
 806      * A MessageFormat formats an array of arguments.  Each argument
 807      * has an expected type, based on the pattern.  For example, if
 808      * the pattern contains the subformat "{3,number,integer}", then
 809      * we expect argument 3 to have type Formattable::kLong.  This
 810      * array needs to grow dynamically if the MessageFormat is
 811      * modified.
 812      */
 813     Formattable::Type* argTypes;
 814     int32_t            argTypeCount;
 815     int32_t            argTypeCapacity;
 816
 817     /**
 818       * Is true iff all argument names are non-negative numbers.
 819       *
 820       */
 821     UBool isArgNumeric;
 822
 823     // Variable-size array management
 824     UBool allocateSubformats(int32_t capacity);
 825     UBool allocateArgTypes(int32_t capacity);
 826
 827     /**
 828      * Default Format objects used when no format is specified and a
 829      * numeric or date argument is formatted.  These are volatile
 830      * cache objects maintained only for performance.  They do not
 831      * participate in operator=(), copy constructor(), nor
 832      * operator==().
 833      */
 834     NumberFormat* defaultNumberFormat;
 835     DateFormat*   defaultDateFormat;
 836
 837     /**
 838      * Method to retrieve default formats (or NULL on failure).
 839      * These are semantically const, but may modify *this.
 840      */
 841     const NumberFormat* getDefaultNumberFormat(UErrorCode&) const;
 842     const DateFormat*   getDefaultDateFormat(UErrorCode&) const;
 843
 844     /**
 845      * Finds the word s, in the keyword list and returns the located index.
 846      * @param s the keyword to be searched for.
 847      * @param list the list of keywords to be searched with.
 848      * @return the index of the list which matches the keyword s.
 849      */
 850     static int32_t findKeyword( const UnicodeString& s,
 851                                 const UChar * const *list);
 852
 853     /**
 854      * Formats the array of arguments and copies the result into the
 855      * result buffer, updates the field position.
 856      *
 857      * @param arguments The formattable objects array.
 858      * @param cnt       The array count.
 859      * @param appendTo  Output parameter to receive result.
 860      *                  Result is appended to existing contents.
 861      * @param status    Field position status.
 862      * @param recursionProtection
 863      *                  Initially zero. Bits 0..9 are used to indicate
 864      *                  that a parameter has already been seen, to
 865      *                  avoid recursion.  Currently unused.
 866      * @param success   The error code status.
 867      * @return          Reference to 'appendTo' parameter.
 868      */
 869     UnicodeString&  format( const Formattable* arguments,
 870                             int32_t cnt,
 871                             UnicodeString& appendTo,
 872                             FieldPosition& status,
 873                             int32_t recursionProtection,
 874                             UErrorCode& success) const;
 875
 876     UnicodeString&  format( const Formattable* arguments,
 877                             const UnicodeString *argumentNames,
 878                             int32_t cnt,
 879                             UnicodeString& appendTo,
 880                             FieldPosition& status,
 881                             int32_t recursionProtection,
 882                             UErrorCode& success) const;
 883
 884     void             makeFormat(int32_t offsetNumber,
 885                                 UnicodeString* segments,
 886                                 UParseError& parseError,
 887                                 UErrorCode& success);
 888
 889     /**
 890      * Convenience method that ought to be in NumberFormat
 891      */
 892     NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const;
 893
 894     /**
 895      * Checks the range of the source text to quote the special
 896      * characters, { and ' and copy to target buffer.
 897      * @param source
 898      * @param start the text offset to start the process of in the source string
 899      * @param end the text offset to end the process of in the source string
 900      * @param appendTo  Output parameter to receive result.
 901      *                  Result is appended to existing contents.
 902      */
 903     static void copyAndFixQuotes(const UnicodeString& appendTo, int32_t start, int32_t end, UnicodeString& target);
 904
 905     /**
 906      * Returns array of argument types in the parsed pattern
 907      * for use in C API.  Only for the use of umsg_vformat().  Not
 908      * for public consumption.
 909      * @param listCount  Output parameter to receive the size of array
 910      * @return           The array of formattable types in the pattern
 911      * @internal
 912      */
 913     const Formattable::Type* getArgTypeList(int32_t& listCount) const {
 914         listCount = argTypeCount;
 915         return argTypes;
 916     }
 917
 918     /**
 919      * Returns FALSE if the argument name is not legal.
 920      * @param  argName   argument name.
 921      * @return TRUE if the argument name is legal, otherwise return FALSE.
 922      */
 923     UBool isLegalArgName(const UnicodeString& argName) const;
 924
 925     friend class MessageFormatAdapter; // getFormatTypeList() access
 926 };
 927
 928 inline UnicodeString&
 929 MessageFormat::format(const Formattable& obj,
 930                       UnicodeString& appendTo,
 931                       UErrorCode& status) const {
 932     return Format::format(obj, appendTo, status);
 933 }
 934 U_NAMESPACE_END
 935
 936 #endif /* #if !UCONFIG_NO_FORMATTING */
 937
 938 #endif // _MSGFMT
 939 //eof
 940