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 * For more sophisticated patterns, you can use a ChoiceFormat to get 263 * output: 264 * <pre> 265 * \code 266 * UErrorCode success = U_ZERO_ERROR; 267 * MessageFormat* form("The disk \"{1}\" contains {0}.", success); 268 * double filelimits[] = {0,1,2}; 269 * UnicodeString filepart[] = {"no files","one file","{0,number} files"}; 270 * ChoiceFormat* fileform = new ChoiceFormat(filelimits, filepart, 3); 271 * form.setFormat(1, *fileform); // NOT zero, see below 272 * 273 * Formattable testArgs[] = {1273L, "MyDisk"}; 274 * 275 * UnicodeString string; 276 * FieldPosition fpos = 0; 277 * cout << form.format(testArgs, 2, string, fpos, success) << endl; 278 * 279 * // output, with different testArgs 280 * // output: The disk "MyDisk" contains no files. 281 * // output: The disk "MyDisk" contains one file. 282 * // output: The disk "MyDisk" contains 1,273 files. 283 * \endcode 284 * </pre> 285 * You can either do this programmatically, as in the above example, 286 * or by using a pattern (see ChoiceFormat for more information) as in: 287 * <pre> 288 * \code 289 * form.applyPattern( 290 * "There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}."); 291 * \endcode 292 * </pre> 293 * <P> 294 * <EM>Note:</EM> As we see above, the string produced by a ChoiceFormat in 295 * MessageFormat is treated specially; occurences of '{' are used to 296 * indicated subformats, and cause recursion. If you create both a 297 * MessageFormat and ChoiceFormat programmatically (instead of using 298 * the string patterns), then be careful not to produce a format that 299 * recurses on itself, which will cause an infinite loop. 300 * <P> 301 * <EM>Note:</EM> Subformats are numbered by their order in the pattern. 302 * This is <EM>not</EM> the same as the argumentIndex. 303 * <pre> 304 * \code 305 * For example: with "abc{2}def{3}ghi{0}...", 306 * 307 * format0 affects the first variable {2} 308 * format1 affects the second variable {3} 309 * format2 affects the second variable {0} 310 * \endcode 311 * </pre> 312 * 313 * <p><em>User subclasses are not supported.</em> While clients may write 314 * subclasses, such code will not necessarily work and will not be 315 * guaranteed to work stably from release to release. 316 */ 317 class U_I18N_API MessageFormat : public Format { 318 public: 319 /** 320 * Enum type for kMaxFormat. 321 * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6, 322 * rendering this enum type obsolete. 323 */ 324 enum EFormatNumber { 325 /** 326 * The maximum number of arguments. 327 * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6, 328 * rendering this constant obsolete. 329 */ 330 kMaxFormat = 10 331 }; 332 333 /** 334 * Constructs a new MessageFormat using the given pattern and the 335 * default locale. 336 * 337 * @param pattern Pattern used to construct object. 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 UErrorCode &status); 344 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 status Input/output error code. If the 350 * pattern cannot be parsed, set to failure code. 351 * @stable ICU 2.0 352 */ 353 MessageFormat(const UnicodeString& pattern, 354 const Locale& newLocale, 355 UErrorCode& status); 356 /** 357 * Constructs a new MessageFormat using the given pattern and locale. 358 * @param pattern Pattern used to construct object. 359 * @param newLocale The locale to use for formatting dates and numbers. 360 * @param parseError Struct to recieve information on position 361 * of error within the pattern. 362 * @param status Input/output error code. If the 363 * pattern cannot be parsed, set to failure code. 364 * @stable ICU 2.0 365 */ 366 MessageFormat(const UnicodeString& pattern, 367 const Locale& newLocale, 368 UParseError& parseError, 369 UErrorCode& status); 370 /** 371 * Constructs a new MessageFormat from an existing one. 372 * @stable ICU 2.0 373 */ 374 MessageFormat(const MessageFormat&); 375 376 /** 377 * Assignment operator. 378 * @stable ICU 2.0 379 */ 380 const MessageFormat& operator=(const MessageFormat&); 381 382 /** 383 * Destructor. 384 * @stable ICU 2.0 385 */ 386 virtual ~MessageFormat(); 387 388 /** 389 * Clones this Format object polymorphically. The caller owns the 390 * result and should delete it when done. 391 * @stable ICU 2.0 392 */ 393 virtual Format* clone(void) const; 394 395 /** 396 * Returns true if the given Format objects are semantically equal. 397 * Objects of different subclasses are considered unequal. 398 * @param other the object to be compared with. 399 * @return true if the given Format objects are semantically equal. 400 * @stable ICU 2.0 401 */ 402 virtual UBool operator==(const Format& other) const; 403 404 /** 405 * Sets the locale. This locale is used for fetching default number or date 406 * format information. 407 * @param theLocale the new locale value to be set. 408 * @stable ICU 2.0 409 */ 410 virtual void setLocale(const Locale& theLocale); 411 412 /** 413 * Gets the locale. This locale is used for fetching default number or date 414 * format information. 415 * @return the locale of the object. 416 * @stable ICU 2.0 417 */ 418 virtual const Locale& getLocale(void) const; 419 420 /** 421 * Applies the given pattern string to this message format. 422 * 423 * @param pattern The pattern to be applied. 424 * @param status Input/output error code. If the 425 * pattern cannot be parsed, set to failure code. 426 * @stable ICU 2.0 427 */ 428 virtual void applyPattern(const UnicodeString& pattern, 429 UErrorCode& status); 430 /** 431 * Applies the given pattern string to this message format. 432 * 433 * @param pattern The pattern to be applied. 434 * @param parseError Struct to recieve information on position 435 * of error within pattern. 436 * @param status Input/output error code. If the 437 * pattern cannot be parsed, set to failure code. 438 * @stable ICU 2.0 439 */ 440 virtual void applyPattern(const UnicodeString& pattern, 441 UParseError& parseError, 442 UErrorCode& status); 443 444 /** 445 * Returns a pattern that can be used to recreate this object. 446 * 447 * @param appendTo Output parameter to receive the pattern. 448 * Result is appended to existing contents. 449 * @return Reference to 'appendTo' parameter. 450 * @stable ICU 2.0 451 */ 452 virtual UnicodeString& toPattern(UnicodeString& appendTo) const; 453 454 /** 455 * Sets subformats. 456 * See the class description about format numbering. 457 * The caller should not delete the Format objects after this call. 458 * <EM>The array formatsToAdopt is not itself adopted.</EM> Its 459 * ownership is retained by the caller. If the call fails because 460 * memory cannot be allocated, then the formats will be deleted 461 * by this method, and this object will remain unchanged. 462 * 463 * <p>If this format uses named arguments, the new formats are discarded 464 * and this format remains unchanged. 465 * 466 * @stable ICU 2.0 467 * @param formatsToAdopt the format to be adopted. 468 * @param count the size of the array. 469 */ 470 virtual void adoptFormats(Format** formatsToAdopt, int32_t count); 471 472 /** 473 * Sets subformats. 474 * See the class description about format numbering. 475 * Each item in the array is cloned into the internal array. 476 * If the call fails because memory cannot be allocated, then this 477 * object will remain unchanged. 478 * 479 * <p>If this format uses named arguments, the new formats are discarded 480 * and this format remains unchanged. 481 * 482 * @stable ICU 2.0 483 * @param newFormats the new format to be set. 484 * @param cnt the size of the array. 485 */ 486 virtual void setFormats(const Format** newFormats, int32_t cnt); 487 488 489 /** 490 * Sets one subformat. 491 * See the class description about format numbering. 492 * The caller should not delete the Format object after this call. 493 * If the number is over the number of formats already set, 494 * the item will be deleted and ignored. 495 * 496 * <p>If this format uses named arguments, the new format is discarded 497 * and this format remains unchanged. 498 * 499 * @stable ICU 2.0 500 * @param formatNumber index of the subformat. 501 * @param formatToAdopt the format to be adopted. 502 */ 503 virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt); 504 505 /** 506 * Sets one subformat. 507 * See the class description about format numbering. 508 * If the number is over the number of formats already set, 509 * the item will be ignored. 510 * @param formatNumber index of the subformat. 511 * @param format the format to be set. 512 * @stable ICU 2.0 513 */ 514 virtual void setFormat(int32_t formatNumber, const Format& format); 515 516 /** 517 * Gets format names. This function returns formatNames in StringEnumerations 518 * which can be used with getFormat() and setFormat() to export formattable 519 * array from current MessageFormat to another. It is caller's resposibility 520 * to delete the returned formatNames. 521 * @param status output param set to success/failure code. 522 * @stable ICU 4.0 523 */ 524 virtual StringEnumeration* getFormatNames(UErrorCode& status); 525 526 /** 527 * Gets subformat pointer for given format name. 528 * This function supports both named and numbered 529 * arguments-- if numbered, the formatName is the 530 * corresponding UnicodeStrings (e.g. "0", "1", "2"...). 531 * The returned Format object should not be deleted by the caller, 532 * nor should the ponter of other object . The pointer and its 533 * contents remain valid only until the next call to any method 534 * of this class is made with this object. 535 * @param formatName the name or number specifying a format 536 * @param status output param set to success/failure code. 537 * @stable ICU 4.0 538 */ 539 virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status); 540 541 /** 542 * Sets one subformat for given format name. 543 * See the class description about format name. 544 * This function supports both named and numbered 545 * arguments-- if numbered, the formatName is the 546 * corresponding UnicodeStrings (e.g. "0", "1", "2"...). 547 * If there is no matched formatName or wrong type, 548 * the item will be ignored. 549 * @param formatName Name of the subformat. 550 * @param format the format to be set. 551 * @param status output param set to success/failure code. 552 * @stable ICU 4.0 553 */ 554 virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status); 555 556 /** 557 * Sets one subformat for given format name. 558 * See the class description about format name. 559 * This function supports both named and numbered 560 * arguments-- if numbered, the formatName is the 561 * corresponding UnicodeStrings (e.g. "0", "1", "2"...). 562 * If there is no matched formatName or wrong type, 563 * the item will be ignored. 564 * The caller should not delete the Format object after this call. 565 * @param formatName Name of the subformat. 566 * @param formatToAdopt Format to be adopted. 567 * @param status output param set to success/failure code. 568 * @stable ICU 4.0 569 */ 570 virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status); 571 572 /** 573 * Gets an array of subformats of this object. The returned array 574 * should not be deleted by the caller, nor should the pointers 575 * within the array. The array and its contents remain valid only 576 * until the next call to this format. See the class description 577 * about format numbering. 578 * 579 * @param count output parameter to receive the size of the array 580 * @return an array of count Format* objects, or NULL if out of 581 * memory. Any or all of the array elements may be NULL. 582 * @stable ICU 2.0 583 */ 584 virtual const Format** getFormats(int32_t& count) const; 585 586 587 using Format::format; 588 589 /** 590 * Formats the given array of arguments into a user-readable string. 591 * Does not take ownership of the Formattable* array or its contents. 592 * 593 * <p>If this format uses named arguments, appendTo is unchanged and 594 * status is set to U_ILLEGAL_ARGUMENT_ERROR. 595 * 596 * @param source An array of objects to be formatted. 597 * @param count The number of elements of 'source'. 598 * @param appendTo Output parameter to receive result. 599 * Result is appended to existing contents. 600 * @param ignore Not used; inherited from base class API. 601 * @param status Input/output error code. If the 602 * pattern cannot be parsed, set to failure code. 603 * @return Reference to 'appendTo' parameter. 604 * @stable ICU 2.0 605 */ 606 UnicodeString& format(const Formattable* source, 607 int32_t count, 608 UnicodeString& appendTo, 609 FieldPosition& ignore, 610 UErrorCode& status) const; 611 612 /** 613 * Formats the given array of arguments into a user-readable string 614 * using the given pattern. 615 * 616 * <p>If this format uses named arguments, appendTo is unchanged and 617 * status is set to U_ILLEGAL_ARGUMENT_ERROR. 618 * 619 * @param pattern The pattern. 620 * @param arguments An array of objects to be formatted. 621 * @param count The number of elements of 'source'. 622 * @param appendTo Output parameter to receive result. 623 * Result is appended to existing contents. 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 static UnicodeString& format(const UnicodeString& pattern, 630 const Formattable* arguments, 631 int32_t count, 632 UnicodeString& appendTo, 633 UErrorCode& status); 634 635 /** 636 * Formats the given array of arguments into a user-readable 637 * string. The array must be stored within a single Formattable 638 * object of type kArray. If the Formattable object type is not of 639 * type kArray, then returns a failing UErrorCode. 640 * 641 * <p>If this format uses named arguments, appendTo is unchanged and 642 * status is set to U_ILLEGAL_ARGUMENT_ERROR. 643 * 644 * @param obj A Formattable of type kArray containing 645 * arguments to be formatted. 646 * @param appendTo Output parameter to receive result. 647 * Result is appended to existing contents. 648 * @param pos On input: an alignment field, if desired. 649 * On output: the offsets of the alignment field. 650 * @param status Input/output error code. If the 651 * pattern cannot be parsed, set to failure code. 652 * @return Reference to 'appendTo' parameter. 653 * @stable ICU 2.0 654 */ 655 virtual UnicodeString& format(const Formattable& obj, 656 UnicodeString& appendTo, 657 FieldPosition& pos, 658 UErrorCode& status) const; 659 660 /** 661 * Formats the given array of arguments into a user-readable 662 * string. The array must be stored within a single Formattable 663 * object of type kArray. If the Formattable object type is not of 664 * type kArray, then returns a failing UErrorCode. 665 * 666 * @param obj The object to format 667 * @param appendTo Output parameter to receive result. 668 * Result is appended to existing contents. 669 * @param status Input/output error code. If the 670 * pattern cannot be parsed, set to failure code. 671 * @return Reference to 'appendTo' parameter. 672 * @stable ICU 2.0 673 */ 674 UnicodeString& format(const Formattable& obj, 675 UnicodeString& appendTo, 676 UErrorCode& status) const; 677 678 679 /** 680 * Formats the given array of arguments into a user-defined argument name 681 * array. This function supports both named and numbered 682 * arguments-- if numbered, the formatName is the 683 * corresponding UnicodeStrings (e.g. "0", "1", "2"...). 684 * 685 * @param argumentNames argument name array 686 * @param arguments An array of objects to be formatted. 687 * @param count The number of elements of 'argumentNames' and 688 * arguments. The number of argumentNames and arguments 689 * must be the same. 690 * @param appendTo Output parameter to receive result. 691 * Result is appended to existing contents. 692 * @param status Input/output error code. If the 693 * pattern cannot be parsed, set to failure code. 694 * @return Reference to 'appendTo' parameter. 695 * @stable ICU 4.0 696 */ 697 UnicodeString& format(const UnicodeString* argumentNames, 698 const Formattable* arguments, 699 int32_t count, 700 UnicodeString& appendTo, 701 UErrorCode& status) const; 702 /** 703 * Parses the given string into an array of output arguments. 704 * 705 * @param source String to be parsed. 706 * @param pos On input, starting position for parse. On output, 707 * final position after parse. Unchanged if parse 708 * fails. 709 * @param count Output parameter to receive the number of arguments 710 * parsed. 711 * @return an array of parsed arguments. The caller owns both 712 * the array and its contents. 713 * @stable ICU 2.0 714 */ 715 virtual Formattable* parse(const UnicodeString& source, 716 ParsePosition& pos, 717 int32_t& count) const; 718 719 /** 720 * Parses the given string into an array of output arguments. 721 * 722 * <p>If this format uses named arguments, status is set to 723 * U_ARGUMENT_TYPE_MISMATCH. 724 * 725 * @param source String to be parsed. 726 * @param count Output param to receive size of returned array. 727 * @param status Input/output error code. If the 728 * pattern cannot be parsed, set to failure code. 729 * @return an array of parsed arguments. The caller owns both 730 * the array and its contents. Returns NULL if status is not U_ZERO_ERROR. 731 * 732 * @stable ICU 2.0 733 */ 734 virtual Formattable* parse(const UnicodeString& source, 735 int32_t& count, 736 UErrorCode& status) const; 737 738 /** 739 * Parses the given string into an array of output arguments 740 * stored within a single Formattable of type kArray. 741 * 742 * @param source The string to be parsed into an object. 743 * @param result Formattable to be set to the parse result. 744 * If parse fails, return contents are undefined. 745 * @param pos On input, starting position for parse. On output, 746 * final position after parse. Unchanged if parse 747 * fails. 748 * @stable ICU 2.0 749 */ 750 virtual void parseObject(const UnicodeString& source, 751 Formattable& result, 752 ParsePosition& pos) const; 753 754 /** 755 * Convert an 'apostrophe-friendly' pattern into a standard 756 * pattern. Standard patterns treat all apostrophes as 757 * quotes, which is problematic in some languages, e.g. 758 * French, where apostrophe is commonly used. This utility 759 * assumes that only an unpaired apostrophe immediately before 760 * a brace is a true quote. Other unpaired apostrophes are paired, 761 * and the resulting standard pattern string is returned. 762 * 763 * <p><b>Note</b> it is not guaranteed that the returned pattern 764 * is indeed a valid pattern. The only effect is to convert 765 * between patterns having different quoting semantics. 766 * 767 * @param pattern the 'apostrophe-friendly' patttern to convert 768 * @param status Input/output error code. If the pattern 769 * cannot be parsed, the failure code is set. 770 * @return the standard equivalent of the original pattern 771 * @stable ICU 3.4 772 */ 773 static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern, 774 UErrorCode& status); 775 776 /** 777 * Returns true if this MessageFormat uses named arguments, 778 * and false otherwise. See class description. 779 * 780 * @return true if named arguments are used. 781 * @stable ICU 4.0 782 */ 783 UBool usesNamedArguments() const; 784 785 786 /** 787 * This API is for ICU internal use only. 788 * Please do not use it. 789 * 790 * Returns argument types count in the parsed pattern. 791 * Used to distinguish pattern "{0} d" and "d". 792 * 793 * @return The number of formattable types in the pattern 794 * @internal 795 */ 796 int32_t getArgTypeCount() const; 797 798 /** 799 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. 800 * This method is to implement a simple version of RTTI, since not all 801 * C++ compilers support genuine RTTI. Polymorphic operator==() and 802 * clone() methods call this method. 803 * 804 * @return The class ID for this object. All objects of a 805 * given class have the same class ID. Objects of 806 * other classes have different class IDs. 807 * @stable ICU 2.0 808 */ 809 virtual UClassID getDynamicClassID(void) const; 810 811 /** 812 * Return the class ID for this class. This is useful only for 813 * comparing to a return value from getDynamicClassID(). For example: 814 * <pre> 815 * . Base* polymorphic_pointer = createPolymorphicObject(); 816 * . if (polymorphic_pointer->getDynamicClassID() == 817 * . Derived::getStaticClassID()) ... 818 * </pre> 819 * @return The class ID for all objects of this class. 820 * @stable ICU 2.0 821 */ 822 static UClassID U_EXPORT2 getStaticClassID(void); 823 824 private: 825 826 Locale fLocale; 827 UnicodeString fPattern; 828 Format** formatAliases; // see getFormats 829 int32_t formatAliasesCapacity; 830 UProperty idStart; 831 UProperty idContinue; 832 833 MessageFormat(); // default constructor not implemented 834 835 /* 836 * A structure representing one subformat of this MessageFormat. 837 * Each subformat has a Format object, an offset into the plain 838 * pattern text fPattern, and an argument number. The argument 839 * number corresponds to the array of arguments to be formatted. 840 * @internal 841 */ 842 class Subformat; 843 844 /** 845 * A MessageFormat contains an array of subformats. This array 846 * needs to grow dynamically if the MessageFormat is modified. 847 */ 848 Subformat* subformats; 849 int32_t subformatCount; 850 int32_t subformatCapacity; 851 852 /** 853 * A MessageFormat formats an array of arguments. Each argument 854 * has an expected type, based on the pattern. For example, if 855 * the pattern contains the subformat "{3,number,integer}", then 856 * we expect argument 3 to have type Formattable::kLong. This 857 * array needs to grow dynamically if the MessageFormat is 858 * modified. 859 */ 860 Formattable::Type* argTypes; 861 int32_t argTypeCount; 862 int32_t argTypeCapacity; 863 864 /** 865 * Is true iff all argument names are non-negative numbers. 866 * 867 */ 868 UBool isArgNumeric; 869 870 // Variable-size array management 871 UBool allocateSubformats(int32_t capacity); 872 UBool allocateArgTypes(int32_t capacity); 873 874 /** 875 * Default Format objects used when no format is specified and a 876 * numeric or date argument is formatted. These are volatile 877 * cache objects maintained only for performance. They do not 878 * participate in operator=(), copy constructor(), nor 879 * operator==(). 880 */ 881 NumberFormat* defaultNumberFormat; 882 DateFormat* defaultDateFormat; 883 884 /** 885 * Method to retrieve default formats (or NULL on failure). 886 * These are semantically const, but may modify *this. 887 */ 888 const NumberFormat* getDefaultNumberFormat(UErrorCode&) const; 889 const DateFormat* getDefaultDateFormat(UErrorCode&) const; 890 891 /** 892 * Finds the word s, in the keyword list and returns the located index. 893 * @param s the keyword to be searched for. 894 * @param list the list of keywords to be searched with. 895 * @return the index of the list which matches the keyword s. 896 */ 897 static int32_t findKeyword( const UnicodeString& s, 898 const UChar * const *list); 899 900 /** 901 * Formats the array of arguments and copies the result into the 902 * result buffer, updates the field position. 903 * 904 * @param arguments The formattable objects array. 905 * @param cnt The array count. 906 * @param appendTo Output parameter to receive result. 907 * Result is appended to existing contents. 908 * @param status Field position status. 909 * @param recursionProtection 910 * Initially zero. Bits 0..9 are used to indicate 911 * that a parameter has already been seen, to 912 * avoid recursion. Currently unused. 913 * @param success The error code status. 914 * @return Reference to 'appendTo' parameter. 915 */ 916 UnicodeString& format( const Formattable* arguments, 917 int32_t cnt, 918 UnicodeString& appendTo, 919 FieldPosition& status, 920 int32_t recursionProtection, 921 UErrorCode& success) const; 922 923 UnicodeString& format( const Formattable* arguments, 924 const UnicodeString *argumentNames, 925 int32_t cnt, 926 UnicodeString& appendTo, 927 FieldPosition& status, 928 int32_t recursionProtection, 929 UErrorCode& success) const; 930 931 void makeFormat(int32_t offsetNumber, 932 UnicodeString* segments, 933 UParseError& parseError, 934 UErrorCode& success); 935 936 /** 937 * Convenience method that ought to be in NumberFormat 938 */ 939 NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const; 940 941 /** 942 * Checks the range of the source text to quote the special 943 * characters, { and ' and copy to target buffer. 944 * @param source 945 * @param start the text offset to start the process of in the source string 946 * @param end the text offset to end the process of in the source string 947 * @param appendTo Output parameter to receive result. 948 * Result is appended to existing contents. 949 */ 950 static void copyAndFixQuotes(const UnicodeString& appendTo, int32_t start, int32_t end, UnicodeString& target); 951 952 /** 953 * Returns array of argument types in the parsed pattern 954 * for use in C API. Only for the use of umsg_vformat(). Not 955 * for public consumption. 956 * @param listCount Output parameter to receive the size of array 957 * @return The array of formattable types in the pattern 958 * @internal 959 */ 960 const Formattable::Type* getArgTypeList(int32_t& listCount) const { 961 listCount = argTypeCount; 962 return argTypes; 963 } 964 965 /** 966 * Returns FALSE if the argument name is not legal. 967 * @param argName argument name. 968 * @return TRUE if the argument name is legal, otherwise return FALSE. 969 */ 970 UBool isLegalArgName(const UnicodeString& argName) const; 971 972 friend class MessageFormatAdapter; // getFormatTypeList() access 973 }; 974 975 inline UnicodeString& 976 MessageFormat::format(const Formattable& obj, 977 UnicodeString& appendTo, 978 UErrorCode& status) const { 979 return Format::format(obj, appendTo, status); 980 } 981 982 U_NAMESPACE_END 983 984 #endif /* #if !UCONFIG_NO_FORMATTING */ 985 986 #endif // _MSGFMT 987 //eof 988
