1 /* 2 * Copyright (C) 2007-2009, 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** formatsToAdopt, 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& count)}, 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 * @stable 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 * @stable 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 * @stable 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 * @stable 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 * @stable ICU 4.0 748 */ 749 UBool usesNamedArguments() const; 750 751 752 /** 753 * This API is for ICU internal use only. 754 * Please do not use it. 755 * 756 * Returns argument types count in the parsed pattern. 757 * Used to distinguish pattern "{0} d" and "d". 758 * 759 * @return The number of formattable types in the pattern 760 * @internal 761 */ 762 int32_t getArgTypeCount() const; 763 764 /** 765 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. 766 * This method is to implement a simple version of RTTI, since not all 767 * C++ compilers support genuine RTTI. Polymorphic operator==() and 768 * clone() methods call this method. 769 * 770 * @return The class ID for this object. All objects of a 771 * given class have the same class ID. Objects of 772 * other classes have different class IDs. 773 * @stable ICU 2.0 774 */ 775 virtual UClassID getDynamicClassID(void) const; 776 777 /** 778 * Return the class ID for this class. This is useful only for 779 * comparing to a return value from getDynamicClassID(). For example: 780 * <pre> 781 * . Base* polymorphic_pointer = createPolymorphicObject(); 782 * . if (polymorphic_pointer->getDynamicClassID() == 783 * . Derived::getStaticClassID()) ... 784 * </pre> 785 * @return The class ID for all objects of this class. 786 * @stable ICU 2.0 787 */ 788 static UClassID U_EXPORT2 getStaticClassID(void); 789 790 private: 791 792 Locale fLocale; 793 UnicodeString fPattern; 794 Format** formatAliases; // see getFormats 795 int32_t formatAliasesCapacity; 796 UProperty idStart; 797 UProperty idContinue; 798 799 MessageFormat(); // default constructor not implemented 800 801 /* 802 * A structure representing one subformat of this MessageFormat. 803 * Each subformat has a Format object, an offset into the plain 804 * pattern text fPattern, and an argument number. The argument 805 * number corresponds to the array of arguments to be formatted. 806 * @internal 807 */ 808 class Subformat; 809 810 /** 811 * A MessageFormat contains an array of subformats. This array 812 * needs to grow dynamically if the MessageFormat is modified. 813 */ 814 Subformat* subformats; 815 int32_t subformatCount; 816 int32_t subformatCapacity; 817 818 /** 819 * A MessageFormat formats an array of arguments. Each argument 820 * has an expected type, based on the pattern. For example, if 821 * the pattern contains the subformat "{3,number,integer}", then 822 * we expect argument 3 to have type Formattable::kLong. This 823 * array needs to grow dynamically if the MessageFormat is 824 * modified. 825 */ 826 Formattable::Type* argTypes; 827 int32_t argTypeCount; 828 int32_t argTypeCapacity; 829 830 /** 831 * Is true iff all argument names are non-negative numbers. 832 * 833 */ 834 UBool isArgNumeric; 835 836 // Variable-size array management 837 UBool allocateSubformats(int32_t capacity); 838 UBool allocateArgTypes(int32_t capacity); 839 840 /** 841 * Default Format objects used when no format is specified and a 842 * numeric or date argument is formatted. These are volatile 843 * cache objects maintained only for performance. They do not 844 * participate in operator=(), copy constructor(), nor 845 * operator==(). 846 */ 847 NumberFormat* defaultNumberFormat; 848 DateFormat* defaultDateFormat; 849 850 /** 851 * Method to retrieve default formats (or NULL on failure). 852 * These are semantically const, but may modify *this. 853 */ 854 const NumberFormat* getDefaultNumberFormat(UErrorCode&) const; 855 const DateFormat* getDefaultDateFormat(UErrorCode&) const; 856 857 /** 858 * Finds the word s, in the keyword list and returns the located index. 859 * @param s the keyword to be searched for. 860 * @param list the list of keywords to be searched with. 861 * @return the index of the list which matches the keyword s. 862 */ 863 static int32_t findKeyword( const UnicodeString& s, 864 const UChar * const *list); 865 866 /** 867 * Formats the array of arguments and copies the result into the 868 * result buffer, updates the field position. 869 * 870 * @param arguments The formattable objects array. 871 * @param cnt The array count. 872 * @param appendTo Output parameter to receive result. 873 * Result is appended to existing contents. 874 * @param status Field position status. 875 * @param recursionProtection 876 * Initially zero. Bits 0..9 are used to indicate 877 * that a parameter has already been seen, to 878 * avoid recursion. Currently unused. 879 * @param success The error code status. 880 * @return Reference to 'appendTo' parameter. 881 */ 882 UnicodeString& format( const Formattable* arguments, 883 int32_t cnt, 884 UnicodeString& appendTo, 885 FieldPosition& status, 886 int32_t recursionProtection, 887 UErrorCode& success) const; 888 889 UnicodeString& format( const Formattable* arguments, 890 const UnicodeString *argumentNames, 891 int32_t cnt, 892 UnicodeString& appendTo, 893 FieldPosition& status, 894 int32_t recursionProtection, 895 UErrorCode& success) const; 896 897 void makeFormat(int32_t offsetNumber, 898 UnicodeString* segments, 899 UParseError& parseError, 900 UErrorCode& success); 901 902 /** 903 * Convenience method that ought to be in NumberFormat 904 */ 905 NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const; 906 907 /** 908 * Checks the range of the source text to quote the special 909 * characters, { and ' and copy to target buffer. 910 * @param source 911 * @param start the text offset to start the process of in the source string 912 * @param end the text offset to end the process of in the source string 913 * @param appendTo Output parameter to receive result. 914 * Result is appended to existing contents. 915 */ 916 static void copyAndFixQuotes(const UnicodeString& appendTo, int32_t start, int32_t end, UnicodeString& target); 917 918 /** 919 * Returns array of argument types in the parsed pattern 920 * for use in C API. Only for the use of umsg_vformat(). Not 921 * for public consumption. 922 * @param listCount Output parameter to receive the size of array 923 * @return The array of formattable types in the pattern 924 * @internal 925 */ 926 const Formattable::Type* getArgTypeList(int32_t& listCount) const { 927 listCount = argTypeCount; 928 return argTypes; 929 } 930 931 /** 932 * Returns FALSE if the argument name is not legal. 933 * @param argName argument name. 934 * @return TRUE if the argument name is legal, otherwise return FALSE. 935 */ 936 UBool isLegalArgName(const UnicodeString& argName) const; 937 938 friend class MessageFormatAdapter; // getFormatTypeList() access 939 }; 940 941 inline UnicodeString& 942 MessageFormat::format(const Formattable& obj, 943 UnicodeString& appendTo, 944 UErrorCode& status) const { 945 return Format::format(obj, appendTo, status); 946 } 947 U_NAMESPACE_END 948 949 #endif /* #if !UCONFIG_NO_FORMATTING */ 950 951 #endif // _MSGFMT 952 //eof 953 954
