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