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