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