1 /* 2 * Copyright (C) 2007-2011, 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/messagepattern.h" 32 #include "unicode/parseerr.h" 33 #include "unicode/plurfmt.h" 34 #include "unicode/plurrule.h" 35 36 U_CDECL_BEGIN 37 // Forward declaration. 38 struct UHashtable; 39 typedef struct UHashtable UHashtable; 40 U_CDECL_END 41 42 U_NAMESPACE_BEGIN 43 44 class AppendableWrapper; 45 class DateFormat; 46 class NumberFormat; 47 48 /** 49 * <p>MessageFormat prepares strings for display to users, 50 * with optional arguments (variables/placeholders). 51 * The arguments can occur in any order, which is necessary for translation 52 * into languages with different grammars. 53 * 54 * <p>A MessageFormat is constructed from a <em>pattern</em> string 55 * with arguments in {curly braces} which will be replaced by formatted values. 56 * 57 * <p><code>MessageFormat</code> differs from the other <code>Format</code> 58 * classes in that you create a <code>MessageFormat</code> object with one 59 * of its constructors (not with a <code>createInstance</code> style factory 60 * method). Factory methods aren't necessary because <code>MessageFormat</code> 61 * itself doesn't implement locale-specific behavior. Any locale-specific 62 * behavior is defined by the pattern that you provide and the 63 * subformats used for inserted arguments. 64 * 65 * <p>Arguments can be named (using identifiers) or numbered (using small ASCII-digit integers). 66 * Some of the API methods work only with argument numbers and throw an exception 67 * if the pattern has named arguments (see {@link #usesNamedArguments()}). 68 * 69 * <p>An argument might not specify any format type. In this case, 70 * a Number value is formatted with a default (for the locale) NumberFormat, 71 * a Date value is formatted with a default (for the locale) DateFormat, 72 * and for any other value its toString() value is used. 73 * 74 * <p>An argument might specify a "simple" type for which the specified 75 * Format object is created, cached and used. 76 * 77 * <p>An argument might have a "complex" type with nested MessageFormat sub-patterns. 78 * During formatting, one of these sub-messages is selected according to the argument value 79 * and recursively formatted. 80 * 81 * <p>After construction, a custom Format object can be set for 82 * a top-level argument, overriding the default formatting and parsing behavior 83 * for that argument. 84 * However, custom formatting can be achieved more simply by writing 85 * a typeless argument in the pattern string 86 * and supplying it with a preformatted string value. 87 * 88 * <p>When formatting, MessageFormat takes a collection of argument values 89 * and writes an output string. 90 * The argument values may be passed as an array 91 * (when the pattern contains only numbered arguments) 92 * or as an array of names and and an array of arguments (which works for both named 93 * and numbered arguments). 94 * 95 * <p>Each argument is matched with one of the input values by array index or argument name 96 * and formatted according to its pattern specification 97 * (or using a custom Format object if one was set). 98 * A numbered pattern argument is matched with an argument name that contains that number 99 * as an ASCII-decimal-digit string (without leading zero). 100 * 101 * <h4><a name="patterns">Patterns and Their Interpretation</a></h4> 102 * 103 * <code>MessageFormat</code> uses patterns of the following form: 104 * <pre> 105 * message = messageText (argument messageText)* 106 * argument = noneArg | simpleArg | complexArg 107 * complexArg = choiceArg | pluralArg | selectArg 108 * 109 * noneArg = '{' argNameOrNumber '}' 110 * simpleArg = '{' argNameOrNumber ',' argType [',' argStyle] '}' 111 * choiceArg = '{' argNameOrNumber ',' "choice" ',' choiceStyle '}' 112 * pluralArg = '{' argNameOrNumber ',' "plural" ',' pluralStyle '}' 113 * selectArg = '{' argNameOrNumber ',' "select" ',' selectStyle '}' 114 * 115 * choiceStyle: see {@link ChoiceFormat} 116 * pluralStyle: see {@link PluralFormat} 117 * selectStyle: see {@link SelectFormat} 118 * 119 * argNameOrNumber = argName | argNumber 120 * argName = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+ 121 * argNumber = '0' | ('1'..'9' ('0'..'9')*) 122 * 123 * argType = "number" | "date" | "time" | "spellout" | "ordinal" | "duration" 124 * argStyle = "short" | "medium" | "long" | "full" | "integer" | "currency" | "percent" | argStyleText 125 * </pre> 126 * 127 * <ul> 128 * <li>messageText can contain quoted literal strings including syntax characters. 129 * A quoted literal string begins with an ASCII apostrophe and a syntax character 130 * (usually a {curly brace}) and continues until the next single apostrophe. 131 * A double ASCII apostrohpe inside or outside of a quoted string represents 132 * one literal apostrophe. 133 * <li>Quotable syntax characters are the {curly braces} in all messageText parts, 134 * plus the '#' sign in a messageText immediately inside a pluralStyle, 135 * and the '|' symbol in a messageText immediately inside a choiceStyle. 136 * <li>See also {@link #UMessagePatternApostropheMode} 137 * <li>In argStyleText, every single ASCII apostrophe begins and ends quoted literal text, 138 * and unquoted {curly braces} must occur in matched pairs. 139 * </ul> 140 * 141 * <p>Recommendation: Use the real apostrophe (single quote) character 142 * \htmlonly’\endhtmlonly (U+2019) for 143 * human-readable text, and use the ASCII apostrophe ' (U+0027) 144 * only in program syntax, like quoting in MessageFormat. 145 * See the annotations for U+0027 Apostrophe in The Unicode Standard. 146 * 147 * <p>The <code>argType</code> and <code>argStyle</code> values are used to create 148 * a <code>Format</code> instance for the format element. The following 149 * table shows how the values map to Format instances. Combinations not 150 * shown in the table are illegal. Any <code>argStyleText</code> must 151 * be a valid pattern string for the Format subclass used. 152 * 153 * <p><table border=1> 154 * <tr> 155 * <th>argType 156 * <th>argStyle 157 * <th>resulting Format object 158 * <tr> 159 * <td colspan=2><i>(none)</i> 160 * <td><code>null</code> 161 * <tr> 162 * <td rowspan=5><code>number</code> 163 * <td><i>(none)</i> 164 * <td><code>NumberFormat.createInstance(getLocale(), status)</code> 165 * <tr> 166 * <td><code>integer</code> 167 * <td><code>NumberFormat.createInstance(getLocale(), kNumberStyle, status)</code> 168 * <tr> 169 * <td><code>currency</code> 170 * <td><code>NumberFormat.createCurrencyInstance(getLocale(), status)</code> 171 * <tr> 172 * <td><code>percent</code> 173 * <td><code>NumberFormat.createPercentInstance(getLocale(), status)</code> 174 * <tr> 175 * <td><i>argStyleText</i> 176 * <td><code>new DecimalFormat(argStyleText, new DecimalFormatSymbols(getLocale(), status), status)</code> 177 * <tr> 178 * <td rowspan=6><code>date</code> 179 * <td><i>(none)</i> 180 * <td><code>DateFormat.createDateInstance(kDefault, getLocale(), status)</code> 181 * <tr> 182 * <td><code>short</code> 183 * <td><code>DateFormat.createDateInstance(kShort, getLocale(), status)</code> 184 * <tr> 185 * <td><code>medium</code> 186 * <td><code>DateFormat.createDateInstance(kDefault, getLocale(), status)</code> 187 * <tr> 188 * <td><code>long</code> 189 * <td><code>DateFormat.createDateInstance(kLong, getLocale(), status)</code> 190 * <tr> 191 * <td><code>full</code> 192 * <td><code>DateFormat.createDateInstance(kFull, getLocale(), status)</code> 193 * <tr> 194 * <td><i>argStyleText</i> 195 * <td><code>new SimpleDateFormat(argStyleText, getLocale(), status) 196 * <tr> 197 * <td rowspan=6><code>time</code> 198 * <td><i>(none)</i> 199 * <td><code>DateFormat.createTimeInstance(kDefault, getLocale(), status)</code> 200 * <tr> 201 * <td><code>short</code> 202 * <td><code>DateFormat.createTimeInstance(kShort, getLocale(), status)</code> 203 * <tr> 204 * <td><code>medium</code> 205 * <td><code>DateFormat.createTimeInstance(kDefault, getLocale(), status)</code> 206 * <tr> 207 * <td><code>long</code> 208 * <td><code>DateFormat.createTimeInstance(kLong, getLocale(), status)</code> 209 * <tr> 210 * <td><code>full</code> 211 * <td><code>DateFormat.createTimeInstance(kFull, getLocale(), status)</code> 212 * <tr> 213 * <td><i>argStyleText</i> 214 * <td><code>new SimpleDateFormat(argStyleText, getLocale(), status) 215 * <tr> 216 * <td><code>spellout</code> 217 * <td><i>argStyleText (optional)</i> 218 * <td><code>new RuleBasedNumberFormat(URBNF_SPELLOUT, getLocale(), status) 219 * <br/> .setDefaultRuleset(argStyleText, status);</code> 220 * <tr> 221 * <td><code>ordinal</code> 222 * <td><i>argStyleText (optional)</i> 223 * <td><code>new RuleBasedNumberFormat(URBNF_ORDINAL, getLocale(), status) 224 * <br/> .setDefaultRuleset(argStyleText, status);</code> 225 * <tr> 226 * <td><code>duration</code> 227 * <td><i>argStyleText (optional)</i> 228 * <td><code>new RuleBasedNumberFormat(URBNF_DURATION, getLocale(), status) 229 * <br/> .setDefaultRuleset(argStyleText, status);</code> 230 * </table> 231 * <p> 232 * 233 * <h4>Usage Information</h4> 234 * 235 * <p>Here are some examples of usage: 236 * Example 1: 237 * 238 * <pre> 239 * \code 240 * UErrorCode success = U_ZERO_ERROR; 241 * GregorianCalendar cal(success); 242 * Formattable arguments[] = { 243 * 7L, 244 * Formattable( (Date) cal.getTime(success), Formattable::kIsDate), 245 * "a disturbance in the Force" 246 * }; 247 * 248 * UnicodeString result; 249 * MessageFormat::format( 250 * "At {1,time} on {1,date}, there was {2} on planet {0,number}.", 251 * arguments, 3, result, success ); 252 * 253 * cout << "result: " << result << endl; 254 * //<output>: At 4:34:20 PM on 23-Mar-98, there was a disturbance 255 * // in the Force on planet 7. 256 * \endcode 257 * </pre> 258 * 259 * Typically, the message format will come from resources, and the 260 * arguments will be dynamically set at runtime. 261 * 262 * <p>Example 2: 263 * 264 * <pre> 265 * \code 266 * success = U_ZERO_ERROR; 267 * Formattable testArgs[] = {3L, "MyDisk"}; 268 * 269 * MessageFormat form( 270 * "The disk \"{1}\" contains {0} file(s).", success ); 271 * 272 * UnicodeString string; 273 * FieldPosition fpos = 0; 274 * cout << "format: " << form.format(testArgs, 2, string, fpos, success ) << endl; 275 * 276 * // output, with different testArgs: 277 * // output: The disk "MyDisk" contains 0 file(s). 278 * // output: The disk "MyDisk" contains 1 file(s). 279 * // output: The disk "MyDisk" contains 1,273 file(s). 280 * \endcode 281 * </pre> 282 * 283 * 284 * <p>For messages that include plural forms, you can use a plural argument: 285 * <pre> 286 * \code 287 * success = U_ZERO_ERROR; 288 * MessageFormat msgFmt( 289 * "{num_files, plural, " 290 * "=0{There are no files on disk \"{disk_name}\".}" 291 * "=1{There is one file on disk \"{disk_name}\".}" 292 * "other{There are # files on disk \"{disk_name}\".}}", 293 * Locale("en"), 294 * success); 295 * FieldPosition fpos = 0; 296 * Formattable testArgs[] = {0L, "MyDisk"}; 297 * UnicodeString testArgsNames[] = {"num_files", "disk_name"}; 298 * UnicodeString result; 299 * cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success); 300 * testArgs[0] = 3L; 301 * cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success); 302 * \endcode 303 * <em>output</em>: 304 * There are no files on disk "MyDisk". 305 * There are 3 files on "MyDisk". 306 * </pre> 307 * See {@link PluralFormat} and {@link PluralRules} for details. 308 * 309 * <h4><a name="synchronization">Synchronization</a></h4> 310 * 311 * <p>MessageFormats are not synchronized. 312 * It is recommended to create separate format instances for each thread. 313 * If multiple threads access a format concurrently, it must be synchronized 314 * externally. 315 * 316 * @stable ICU 2.0 317 */ 318 class U_I18N_API MessageFormat : public Format { 319 public: 320 /** 321 * Enum type for kMaxFormat. 322 * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6, 323 * rendering this enum type obsolete. 324 */ 325 enum EFormatNumber { 326 /** 327 * The maximum number of arguments. 328 * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6, 329 * rendering this constant obsolete. 330 */ 331 kMaxFormat = 10 332 }; 333 334 /** 335 * Constructs a new MessageFormat using the given pattern and the 336 * default locale. 337 * 338 * @param pattern Pattern used to construct object. 339 * @param status Input/output error code. If the 340 * pattern cannot be parsed, set to failure code. 341 * @stable ICU 2.0 342 */ 343 MessageFormat(const UnicodeString& pattern, 344 UErrorCode &status); 345 346 /** 347 * Constructs a new MessageFormat using the given pattern and locale. 348 * @param pattern Pattern used to construct object. 349 * @param newLocale The locale to use for formatting dates and numbers. 350 * @param status Input/output error code. If the 351 * pattern cannot be parsed, set to failure code. 352 * @stable ICU 2.0 353 */ 354 MessageFormat(const UnicodeString& pattern, 355 const Locale& newLocale, 356 UErrorCode& status); 357 /** 358 * Constructs a new MessageFormat using the given pattern and locale. 359 * @param pattern Pattern used to construct object. 360 * @param newLocale The locale to use for formatting dates and numbers. 361 * @param parseError Struct to receive information on the position 362 * of an error within the pattern. 363 * @param status Input/output error code. If the 364 * pattern cannot be parsed, set to failure code. 365 * @stable ICU 2.0 366 */ 367 MessageFormat(const UnicodeString& pattern, 368 const Locale& newLocale, 369 UParseError& parseError, 370 UErrorCode& status); 371 /** 372 * Constructs a new MessageFormat from an existing one. 373 * @stable ICU 2.0 374 */ 375 MessageFormat(const MessageFormat&); 376 377 /** 378 * Assignment operator. 379 * @stable ICU 2.0 380 */ 381 const MessageFormat& operator=(const MessageFormat&); 382 383 /** 384 * Destructor. 385 * @stable ICU 2.0 386 */ 387 virtual ~MessageFormat(); 388 389 /** 390 * Clones this Format object polymorphically. The caller owns the 391 * result and should delete it when done. 392 * @stable ICU 2.0 393 */ 394 virtual Format* clone(void) const; 395 396 /** 397 * Returns true if the given Format objects are semantically equal. 398 * Objects of different subclasses are considered unequal. 399 * @param other the object to be compared with. 400 * @return true if the given Format objects are semantically equal. 401 * @stable ICU 2.0 402 */ 403 virtual UBool operator==(const Format& other) const; 404 405 /** 406 * Sets the locale to be used for creating argument Format objects. 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 used for creating argument Format objects. 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 receive information on the position 435 * of an error within the 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 * Sets the UMessagePatternApostropheMode and the pattern used by this message format. 446 * Parses the pattern and caches Format objects for simple argument types. 447 * Patterns and their interpretation are specified in the 448 * <a href="#patterns">class description</a>. 449 * <p> 450 * This method is best used only once on a given object to avoid confusion about the mode, 451 * and after constructing the object with an empty pattern string to minimize overhead. 452 * 453 * @param pattern The pattern to be applied. 454 * @param aposMode The new apostrophe mode. 455 * @param parseError Struct to receive information on the position 456 * of an error within the pattern. 457 * Can be NULL. 458 * @param status Input/output error code. If the 459 * pattern cannot be parsed, set to failure code. 460 * @draft ICU 4.8 461 */ 462 virtual void applyPattern(const UnicodeString& pattern, 463 UMessagePatternApostropheMode aposMode, 464 UParseError* parseError, 465 UErrorCode& status); 466 467 /** 468 * @return this instance's UMessagePatternApostropheMode. 469 * @draft ICU 4.8 470 */ 471 UMessagePatternApostropheMode getApostropheMode() const { 472 return msgPattern.getApostropheMode(); 473 } 474 475 /** 476 * Returns a pattern that can be used to recreate this object. 477 * 478 * @param appendTo Output parameter to receive the pattern. 479 * Result is appended to existing contents. 480 * @return Reference to 'appendTo' parameter. 481 * @stable ICU 2.0 482 */ 483 virtual UnicodeString& toPattern(UnicodeString& appendTo) const; 484 485 /** 486 * Sets subformats. 487 * See the class description about format numbering. 488 * The caller should not delete the Format objects after this call. 489 * <EM>The array formatsToAdopt is not itself adopted.</EM> Its 490 * ownership is retained by the caller. If the call fails because 491 * memory cannot be allocated, then the formats will be deleted 492 * by this method, and this object will remain unchanged. 493 * 494 * <p>If this format uses named arguments, the new formats are discarded 495 * and this format remains unchanged. 496 * 497 * @stable ICU 2.0 498 * @param formatsToAdopt the format to be adopted. 499 * @param count the size of the array. 500 */ 501 virtual void adoptFormats(Format** formatsToAdopt, int32_t count); 502 503 /** 504 * Sets subformats. 505 * See the class description about format numbering. 506 * Each item in the array is cloned into the internal array. 507 * If the call fails because memory cannot be allocated, then this 508 * object will remain unchanged. 509 * 510 * <p>If this format uses named arguments, the new formats are discarded 511 * and this format remains unchanged. 512 * 513 * @stable ICU 2.0 514 * @param newFormats the new format to be set. 515 * @param cnt the size of the array. 516 */ 517 virtual void setFormats(const Format** newFormats, int32_t cnt); 518 519 520 /** 521 * Sets one subformat. 522 * See the class description about format numbering. 523 * The caller should not delete the Format object after this call. 524 * If the number is over the number of formats already set, 525 * the item will be deleted and ignored. 526 * 527 * <p>If this format uses named arguments, the new format is discarded 528 * and this format remains unchanged. 529 * 530 * @stable ICU 2.0 531 * @param formatNumber index of the subformat. 532 * @param formatToAdopt the format to be adopted. 533 */ 534 virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt); 535 536 /** 537 * Sets one subformat. 538 * See the class description about format numbering. 539 * If the number is over the number of formats already set, 540 * the item will be ignored. 541 * @param formatNumber index of the subformat. 542 * @param format the format to be set. 543 * @stable ICU 2.0 544 */ 545 virtual void setFormat(int32_t formatNumber, const Format& format); 546 547 /** 548 * Gets format names. This function returns formatNames in StringEnumerations 549 * which can be used with getFormat() and setFormat() to export formattable 550 * array from current MessageFormat to another. It is the caller's responsibility 551 * to delete the returned formatNames. 552 * @param status output param set to success/failure code. 553 * @stable ICU 4.0 554 */ 555 virtual StringEnumeration* getFormatNames(UErrorCode& status); 556 557 /** 558 * Gets subformat pointer for given 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 * The returned Format object should not be deleted by the caller, 563 * nor should the ponter of other object . The pointer and its 564 * contents remain valid only until the next call to any method 565 * of this class is made with this object. 566 * @param formatName the name or number specifying a format 567 * @param status output param set to success/failure code. 568 * @stable ICU 4.0 569 */ 570 virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status); 571 572 /** 573 * Sets one subformat for given format name. 574 * See the class description about format name. 575 * This function supports both named and numbered 576 * arguments-- if numbered, the formatName is the 577 * corresponding UnicodeStrings (e.g. "0", "1", "2"...). 578 * If there is no matched formatName or wrong type, 579 * the item will be ignored. 580 * @param formatName Name of the subformat. 581 * @param format the format to be set. 582 * @param status output param set to success/failure code. 583 * @stable ICU 4.0 584 */ 585 virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status); 586 587 /** 588 * Sets one subformat for given format name. 589 * See the class description about format name. 590 * This function supports both named and numbered 591 * arguments-- if numbered, the formatName is the 592 * corresponding UnicodeStrings (e.g. "0", "1", "2"...). 593 * If there is no matched formatName or wrong type, 594 * the item will be ignored. 595 * The caller should not delete the Format object after this call. 596 * @param formatName Name of the subformat. 597 * @param formatToAdopt Format to be adopted. 598 * @param status output param set to success/failure code. 599 * @stable ICU 4.0 600 */ 601 virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status); 602 603 /** 604 * Gets an array of subformats of this object. The returned array 605 * should not be deleted by the caller, nor should the pointers 606 * within the array. The array and its contents remain valid only 607 * until the next call to this format. See the class description 608 * about format numbering. 609 * 610 * @param count output parameter to receive the size of the array 611 * @return an array of count Format* objects, or NULL if out of 612 * memory. Any or all of the array elements may be NULL. 613 * @stable ICU 2.0 614 */ 615 virtual const Format** getFormats(int32_t& count) const; 616 617 618 using Format::format; 619 620 /** 621 * Formats the given array of arguments into a user-readable string. 622 * Does not take ownership of the Formattable* array or its contents. 623 * 624 * <p>If this format uses named arguments, appendTo is unchanged and 625 * status is set to U_ILLEGAL_ARGUMENT_ERROR. 626 * 627 * @param source An array of objects to be formatted. 628 * @param count The number of elements of 'source'. 629 * @param appendTo Output parameter to receive result. 630 * Result is appended to existing contents. 631 * @param ignore Not used; inherited from base class API. 632 * @param status Input/output error code. If the 633 * pattern cannot be parsed, set to failure code. 634 * @return Reference to 'appendTo' parameter. 635 * @stable ICU 2.0 636 */ 637 UnicodeString& format(const Formattable* source, 638 int32_t count, 639 UnicodeString& appendTo, 640 FieldPosition& ignore, 641 UErrorCode& status) const; 642 643 /** 644 * Formats the given array of arguments into a user-readable string 645 * using the given pattern. 646 * 647 * <p>If this format uses named arguments, appendTo is unchanged and 648 * status is set to U_ILLEGAL_ARGUMENT_ERROR. 649 * 650 * @param pattern The pattern. 651 * @param arguments An array of objects to be formatted. 652 * @param count The number of elements of 'source'. 653 * @param appendTo Output parameter to receive result. 654 * Result is appended to existing contents. 655 * @param status Input/output error code. If the 656 * pattern cannot be parsed, set to failure code. 657 * @return Reference to 'appendTo' parameter. 658 * @stable ICU 2.0 659 */ 660 static UnicodeString& format(const UnicodeString& pattern, 661 const Formattable* arguments, 662 int32_t count, 663 UnicodeString& appendTo, 664 UErrorCode& status); 665 666 /** 667 * Formats the given array of arguments into a user-readable 668 * string. The array must be stored within a single Formattable 669 * object of type kArray. If the Formattable object type is not of 670 * type kArray, then returns a failing UErrorCode. 671 * 672 * <p>If this format uses named arguments, appendTo is unchanged and 673 * status is set to U_ILLEGAL_ARGUMENT_ERROR. 674 * 675 * @param obj A Formattable of type kArray containing 676 * arguments to be formatted. 677 * @param appendTo Output parameter to receive result. 678 * Result is appended to existing contents. 679 * @param pos On input: an alignment field, if desired. 680 * On output: the offsets of the alignment field. 681 * @param status Input/output error code. If the 682 * pattern cannot be parsed, set to failure code. 683 * @return Reference to 'appendTo' parameter. 684 * @stable ICU 2.0 685 */ 686 virtual UnicodeString& format(const Formattable& obj, 687 UnicodeString& appendTo, 688 FieldPosition& pos, 689 UErrorCode& status) const; 690 691 /** 692 * Formats the given array of arguments into a user-readable 693 * string. The array must be stored within a single Formattable 694 * object of type kArray. If the Formattable object type is not of 695 * type kArray, then returns a failing UErrorCode. 696 * 697 * @param obj The object to format 698 * @param appendTo Output parameter to receive result. 699 * Result is appended to existing contents. 700 * @param status Input/output error code. If the 701 * pattern cannot be parsed, set to failure code. 702 * @return Reference to 'appendTo' parameter. 703 * @stable ICU 2.0 704 */ 705 UnicodeString& format(const Formattable& obj, 706 UnicodeString& appendTo, 707 UErrorCode& status) const; 708 709 710 /** 711 * Formats the given array of arguments into a user-defined argument name 712 * array. This function supports both named and numbered 713 * arguments-- if numbered, the formatName is the 714 * corresponding UnicodeStrings (e.g. "0", "1", "2"...). 715 * 716 * @param argumentNames argument name array 717 * @param arguments An array of objects to be formatted. 718 * @param count The number of elements of 'argumentNames' and 719 * arguments. The number of argumentNames and arguments 720 * must be the same. 721 * @param appendTo Output parameter to receive result. 722 * Result is appended to existing contents. 723 * @param status Input/output error code. If the 724 * pattern cannot be parsed, set to failure code. 725 * @return Reference to 'appendTo' parameter. 726 * @stable ICU 4.0 727 */ 728 UnicodeString& format(const UnicodeString* argumentNames, 729 const Formattable* arguments, 730 int32_t count, 731 UnicodeString& appendTo, 732 UErrorCode& status) const; 733 /** 734 * Parses the given string into an array of output arguments. 735 * 736 * @param source String to be parsed. 737 * @param pos On input, starting position for parse. On output, 738 * final position after parse. Unchanged if parse 739 * fails. 740 * @param count Output parameter to receive the number of arguments 741 * parsed. 742 * @return an array of parsed arguments. The caller owns both 743 * the array and its contents. 744 * @stable ICU 2.0 745 */ 746 virtual Formattable* parse(const UnicodeString& source, 747 ParsePosition& pos, 748 int32_t& count) const; 749 750 /** 751 * Parses the given string into an array of output arguments. 752 * 753 * <p>If this format uses named arguments, status is set to 754 * U_ARGUMENT_TYPE_MISMATCH. 755 * 756 * @param source String to be parsed. 757 * @param count Output param to receive size of returned array. 758 * @param status Input/output error code. If the 759 * pattern cannot be parsed, set to failure code. 760 * @return an array of parsed arguments. The caller owns both 761 * the array and its contents. Returns NULL if status is not U_ZERO_ERROR. 762 * 763 * @stable ICU 2.0 764 */ 765 virtual Formattable* parse(const UnicodeString& source, 766 int32_t& count, 767 UErrorCode& status) const; 768 769 /** 770 * Parses the given string into an array of output arguments 771 * stored within a single Formattable of type kArray. 772 * 773 * @param source The string to be parsed into an object. 774 * @param result Formattable to be set to the parse result. 775 * If parse fails, return contents are undefined. 776 * @param pos On input, starting position for parse. On output, 777 * final position after parse. Unchanged if parse 778 * fails. 779 * @stable ICU 2.0 780 */ 781 virtual void parseObject(const UnicodeString& source, 782 Formattable& result, 783 ParsePosition& pos) const; 784 785 /** 786 * Convert an 'apostrophe-friendly' pattern into a standard 787 * pattern. Standard patterns treat all apostrophes as 788 * quotes, which is problematic in some languages, e.g. 789 * French, where apostrophe is commonly used. This utility 790 * assumes that only an unpaired apostrophe immediately before 791 * a brace is a true quote. Other unpaired apostrophes are paired, 792 * and the resulting standard pattern string is returned. 793 * 794 * <p><b>Note</b> it is not guaranteed that the returned pattern 795 * is indeed a valid pattern. The only effect is to convert 796 * between patterns having different quoting semantics. 797 * 798 * @param pattern the 'apostrophe-friendly' patttern to convert 799 * @param status Input/output error code. If the pattern 800 * cannot be parsed, the failure code is set. 801 * @return the standard equivalent of the original pattern 802 * @stable ICU 3.4 803 */ 804 static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern, 805 UErrorCode& status); 806 807 808 /** 809 * Returns true if this MessageFormat uses named arguments, 810 * and false otherwise. See class description. 811 * 812 * @return true if named arguments are used. 813 * @stable ICU 4.0 814 */ 815 UBool usesNamedArguments() const; 816 817 818 /** 819 * This API is for ICU internal use only. 820 * Please do not use it. 821 * 822 * Returns argument types count in the parsed pattern. 823 * Used to distinguish pattern "{0} d" and "d". 824 * 825 * @return The number of formattable types in the pattern 826 * @internal 827 */ 828 int32_t getArgTypeCount() const; 829 830 /** 831 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. 832 * This method is to implement a simple version of RTTI, since not all 833 * C++ compilers support genuine RTTI. Polymorphic operator==() and 834 * clone() methods call this method. 835 * 836 * @return The class ID for this object. All objects of a 837 * given class have the same class ID. Objects of 838 * other classes have different class IDs. 839 * @stable ICU 2.0 840 */ 841 virtual UClassID getDynamicClassID(void) const; 842 843 /** 844 * Return the class ID for this class. This is useful only for 845 * comparing to a return value from getDynamicClassID(). For example: 846 * <pre> 847 * . Base* polymorphic_pointer = createPolymorphicObject(); 848 * . if (polymorphic_pointer->getDynamicClassID() == 849 * . Derived::getStaticClassID()) ... 850 * </pre> 851 * @return The class ID for all objects of this class. 852 * @stable ICU 2.0 853 */ 854 static UClassID U_EXPORT2 getStaticClassID(void); 855 856 /** 857 * Compares two Format objects. This is used for constructing the hash 858 * tables. 859 * 860 * @param left pointer to a Format object. Must not be NULL. 861 * @param right pointer to a Format object. Must not be NULL. 862 * 863 * @return whether the two objects are the same 864 * @internal 865 */ 866 static UBool equalFormats(const void* left, const void* right); 867 868 private: 869 870 Locale fLocale; 871 MessagePattern msgPattern; 872 Format** formatAliases; // see getFormats 873 int32_t formatAliasesCapacity; 874 875 MessageFormat(); // default constructor not implemented 876 877 /** 878 * This provider helps defer instantiation of a PluralRules object 879 * until we actually need to select a keyword. 880 * For example, if the number matches an explicit-value selector like "=1" 881 * we do not need any PluralRules. 882 */ 883 class U_I18N_API PluralSelectorProvider : public PluralFormat::PluralSelector { 884 public: 885 PluralSelectorProvider(const Locale* loc); 886 virtual ~PluralSelectorProvider(); 887 virtual UnicodeString select(double number, UErrorCode& ec) const; 888 889 void reset(const Locale* loc); 890 private: 891 const Locale* locale; 892 PluralRules* rules; 893 }; 894 895 /** 896 * A MessageFormat formats an array of arguments. Each argument 897 * has an expected type, based on the pattern. For example, if 898 * the pattern contains the subformat "{3,number,integer}", then 899 * we expect argument 3 to have type Formattable::kLong. This 900 * array needs to grow dynamically if the MessageFormat is 901 * modified. 902 */ 903 Formattable::Type* argTypes; 904 int32_t argTypeCount; 905 int32_t argTypeCapacity; 906 907 /** 908 * TRUE if there are different argTypes for the same argument. 909 * This only matters when the MessageFormat is used in the plain C (umsg_xxx) API 910 * where the pattern argTypes determine how the va_arg list is read. 911 */ 912 UBool hasArgTypeConflicts; 913 914 // Variable-size array management 915 UBool allocateArgTypes(int32_t capacity, UErrorCode& status); 916 917 /** 918 * Default Format objects used when no format is specified and a 919 * numeric or date argument is formatted. These are volatile 920 * cache objects maintained only for performance. They do not 921 * participate in operator=(), copy constructor(), nor 922 * operator==(). 923 */ 924 NumberFormat* defaultNumberFormat; 925 DateFormat* defaultDateFormat; 926 927 UHashtable* cachedFormatters; 928 UHashtable* customFormatArgStarts; 929 930 PluralSelectorProvider pluralProvider; 931 932 /** 933 * Method to retrieve default formats (or NULL on failure). 934 * These are semantically const, but may modify *this. 935 */ 936 const NumberFormat* getDefaultNumberFormat(UErrorCode&) const; 937 const DateFormat* getDefaultDateFormat(UErrorCode&) const; 938 939 /** 940 * Finds the word s, in the keyword list and returns the located index. 941 * @param s the keyword to be searched for. 942 * @param list the list of keywords to be searched with. 943 * @return the index of the list which matches the keyword s. 944 */ 945 static int32_t findKeyword( const UnicodeString& s, 946 const UChar * const *list); 947 948 /** 949 * Thin wrapper around the format(... AppendableWrapper ...) variant. 950 * Wraps the destination UnicodeString into an AppendableWrapper and 951 * supplies default values for some other parameters. 952 */ 953 UnicodeString& format(const Formattable* arguments, 954 const UnicodeString *argumentNames, 955 int32_t cnt, 956 UnicodeString& appendTo, 957 FieldPosition* pos, 958 UErrorCode& status) const; 959 960 /** 961 * Formats the arguments and writes the result into the 962 * AppendableWrapper, updates the field position. 963 * 964 * @param msgStart Index to msgPattern part to start formatting from. 965 * @param pluralNumber Zero except when formatting a plural argument sub-message 966 * where a '#' is replaced by the format string for this number. 967 * @param arguments The formattable objects array. (Must not be NULL.) 968 * @param argumentNames NULL if numbered values are used. Otherwise the same 969 * length as "arguments", and each entry is the name of the 970 * corresponding argument in "arguments". 971 * @param cnt The length of arguments (and of argumentNames if that is not NULL). 972 * @param appendTo Output parameter to receive the result. 973 * The result string is appended to existing contents. 974 * @param pos Field position status. 975 * @param success The error code status. 976 */ 977 void format(int32_t msgStart, 978 double pluralNumber, 979 const Formattable* arguments, 980 const UnicodeString *argumentNames, 981 int32_t cnt, 982 AppendableWrapper& appendTo, 983 FieldPosition* pos, 984 UErrorCode& success) const; 985 986 UnicodeString getArgName(int32_t partIndex); 987 988 void setArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status); 989 990 void setCustomArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status); 991 992 int32_t nextTopLevelArgStart(int32_t partIndex) const; 993 994 UBool argNameMatches(int32_t partIndex, const UnicodeString& argName, int32_t argNumber); 995 996 void cacheExplicitFormats(UErrorCode& status); 997 998 Format* createAppropriateFormat(UnicodeString& type, 999 UnicodeString& style, 1000 Formattable::Type& formattableType, 1001 UParseError& parseError, 1002 UErrorCode& ec); 1003 1004 const Formattable* getArgFromListByName(const Formattable* arguments, 1005 const UnicodeString *argumentNames, 1006 int32_t cnt, UnicodeString& name) const; 1007 1008 Formattable* parse(int32_t msgStart, 1009 const UnicodeString& source, 1010 ParsePosition& pos, 1011 int32_t& count, 1012 UErrorCode& ec) const; 1013 1014 FieldPosition* updateMetaData(AppendableWrapper& dest, int32_t prevLength, 1015 FieldPosition* fp, const Formattable* argId) const; 1016 1017 Format* getCachedFormatter(int32_t argumentNumber) const; 1018 1019 UnicodeString getLiteralStringUntilNextArgument(int32_t from) const; 1020 1021 void copyObjects(const MessageFormat& that, UErrorCode& ec); 1022 1023 void formatComplexSubMessage(int32_t msgStart, 1024 double pluralNumber, 1025 const Formattable* arguments, 1026 const UnicodeString *argumentNames, 1027 int32_t cnt, 1028 AppendableWrapper& appendTo, 1029 UErrorCode& success) const; 1030 1031 /** 1032 * Convenience method that ought to be in NumberFormat 1033 */ 1034 NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const; 1035 1036 /** 1037 * Returns array of argument types in the parsed pattern 1038 * for use in C API. Only for the use of umsg_vformat(). Not 1039 * for public consumption. 1040 * @param listCount Output parameter to receive the size of array 1041 * @return The array of formattable types in the pattern 1042 * @internal 1043 */ 1044 const Formattable::Type* getArgTypeList(int32_t& listCount) const { 1045 listCount = argTypeCount; 1046 return argTypes; 1047 } 1048 1049 /** 1050 * Resets the internal MessagePattern, and other associated caches. 1051 */ 1052 void resetPattern(); 1053 1054 /** 1055 * A DummyFormatter that we use solely to store a NULL value. UHash does 1056 * not support storing NULL values. 1057 * @internal 1058 */ 1059 class U_I18N_API DummyFormat : public Format { 1060 public: 1061 virtual UBool operator==(const Format&) const; 1062 virtual Format* clone() const; 1063 virtual UnicodeString& format(const Formattable&, 1064 UnicodeString& appendTo, 1065 FieldPosition&, 1066 UErrorCode& status) const; 1067 virtual void parseObject(const UnicodeString&, 1068 Formattable&, 1069 ParsePosition&) const; 1070 virtual UClassID getDynamicClassID() const; 1071 }; 1072 1073 friend class MessageFormatAdapter; // getFormatTypeList() access 1074 }; 1075 1076 inline UnicodeString& 1077 MessageFormat::format(const Formattable& obj, 1078 UnicodeString& appendTo, 1079 UErrorCode& status) const { 1080 return Format::format(obj, appendTo, status); 1081 } 1082 1083 1084 U_NAMESPACE_END 1085 1086 #endif /* #if !UCONFIG_NO_FORMATTING */ 1087 1088 #endif // _MSGFMT 1089 //eof 1090
