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, UErrorCode& status)},
74 * {@link #adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status)},
75 * {@link #format(const UnicodeString* argumentNames, const Formattable* arguments,
76 * int32_t count, UnicodeString& appendTo,UErrorCode& status)}.
77 * These methods are all compatible with patterns that do not used named arguments--
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& appendTo, FieldPosition& ignore, UErrorCode& success)},
92 * {@link #format(const UnicodeString& pattern,const Formattable* arguments,int32_t cnt,UnicodeString& appendTo,UErrorCode& success)},
93 * {@link #format(const Formattable& source, UnicodeString& appendTo, FieldPosition& ignore, UErrorCode& success)},
94 * {@link #format(const Formattable* arguments, int32_t cnt, UnicodeString& appendTo, 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 { "," elementFormat }
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 pattern
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 StringEnumerations
492 * which can be used with getFormat() and setFormat() to export formattable
493 * array from current MessageFormat to another. It is caller's resposibility
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& status);
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* formatToAdopt, 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, int32_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 */
getArgTypeList(int32_t & listCount)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&
format(const Formattable & obj,UnicodeString & appendTo,UErrorCode & status)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
962