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 |