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