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