Line data Source code
1 : /*
2 : * Copyright (C) 2007-2009, International Business Machines Corporation and others. All Rights Reserved.
3 : ********************************************************************************
4 : *
5 : * File MSGFMT.H
6 : *
7 : * Modification History:
8 : *
9 : * Date Name Description
10 : * 02/19/97 aliu Converted from java.
11 : * 03/20/97 helena Finished first cut of implementation.
12 : * 07/22/98 stephen Removed operator!= (defined in Format)
13 : * 08/19/2002 srl Removing Javaisms
14 : ********************************************************************************
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 : * A MessageFormat produces concatenated messages in a
42 : * language-neutral way. It should be used for all string
43 : * concatenations that are visible to end users.
44 : * <P>
45 : * 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 : * <P>
50 : * 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 : * <P>
54 : * During formatting, the 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 resultant strings are then assembled
60 : * within the string template of the MessageFormat to produce the
61 : * final output string.
62 : * <p>
63 : * <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 : * <p>
70 : * 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 Formattable* arguments, const UnicodeString *argumentNames, int32_t cnt, UnicodeString& appendTo, FieldPosition& status, int32_t recursionProtection, UErrorCode& success)},
76 : * {@link #format(const UnicodeString* argumentNames, const Formattable* arguments, 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 : * <p>
81 : * When named arguments are used, certain methods on MessageFormat 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. UErrorCode is set to
84 : * U_ARGUMENT_TYPE_MISMATCH if there is a status/success field in the method.
85 : * These methods are
86 : * {@link #adoptFormats(Format** formatsToAdopt, int32_t count)},
87 : * {@link #setFormats(const Format** newFormats,int32_t count)},
88 : * {@link #adoptFormat(int32_t n, Format *newFormat)},
89 : * {@link #getFormats(int32_t& count)},
90 : * {@link #format(const Formattable* source,int32_t cnt,UnicodeString& appendTo, FieldPosition& ignore, UErrorCode& success)},
91 : * {@link #format(const UnicodeString& pattern,const Formattable* arguments,int32_t cnt,UnicodeString& appendTo,UErrorCode& success)},
92 : * {@link #format(const Formattable& source, UnicodeString& appendTo,FieldPosition& ignore, UErrorCode& success)},
93 : * {@link #format(const Formattable* arguments, int32_t cnt, UnicodeString& appendTo, FieldPosition& status, int32_t recursionProtection,UErrorCode& success)},
94 : * {@link #parse(const UnicodeString& source, ParsePosition& pos,int32_t& count)},
95 : * {@link #parse(const UnicodeString& source, int32_t& cnt, UErrorCode& status)}
96 : * <p>
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 intput 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 is 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 quotes 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 : *
194 : * datetimeStyle := "short"
195 : * | "medium"
196 : * | "long"
197 : * | "full"
198 : * | dateFormatPattern
199 : *
200 : * numberStyle := "currency"
201 : * | "percent"
202 : * | "integer"
203 : * | numberFormatPattern
204 : *
205 : * choiceStyle := choiceFormatPattern
206 : *
207 : * pluralStyle := pluralFormatPattern
208 : * \endcode
209 : * </pre>
210 : * If there is no elementFormat, then the argument must be a string,
211 : * which is substituted. If there is no dateTimeStyle or numberStyle,
212 : * then the default format is used (e.g. NumberFormat::createInstance(),
213 : * DateFormat::createTimeInstance(DateFormat::kDefault, ...) or DateFormat::createDateInstance(DateFormat::kDefault, ...). For
214 : * a ChoiceFormat, the pattern must always be specified, since there
215 : * is no default.
216 : * <P>
217 : * In strings, single quotes can be used to quote syntax characters.
218 : * A literal single quote is represented by '', both within and outside
219 : * of single-quoted segments. Inside a
220 : * messageFormatElement, quotes are <EM>not</EM> removed. For example,
221 : * {1,number,$'#',##} will produce a number format with the pound-sign
222 : * quoted, with a result such as: "$#31,45".
223 : * <P>
224 : * If a pattern is used, then unquoted braces in the pattern, if any,
225 : * must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab
226 : * {0'}' de" and "ab } de" are not.
227 : * <p>
228 : * <dl><dt><b>Warning:</b><dd>The rules for using quotes within message
229 : * format patterns unfortunately have shown to be somewhat confusing.
230 : * In particular, it isn't always obvious to localizers whether single
231 : * quotes need to be doubled or not. Make sure to inform localizers about
232 : * the rules, and tell them (for example, by using comments in resource
233 : * bundle source files) which strings will be processed by MessageFormat.
234 : * Note that localizers may need to use single quotes in translated
235 : * strings where the original version doesn't have them.
236 : * <br>Note also that the simplest way to avoid the problem is to
237 : * use the real apostrophe (single quote) character U+2019 (') for
238 : * human-readable text, and to use the ASCII apostrophe (U+0027 ' )
239 : * only in program syntax, like quoting in MessageFormat.
240 : * See the annotations for U+0027 Apostrophe in The Unicode Standard.</p>
241 : * </dl>
242 : * <P>
243 : * The argumentIndex is a non-negative integer, which corresponds to the
244 : * index of the arguments presented in an array to be formatted. The
245 : * first argument has argumentIndex 0.
246 : * <P>
247 : * It is acceptable to have unused arguments in the array. With missing
248 : * arguments or arguments that are not of the right class for the
249 : * specified format, a failing UErrorCode result is set.
250 : * <P>
251 : * For more sophisticated patterns, you can use a ChoiceFormat to get
252 : * output:
253 : * <pre>
254 : * \code
255 : * UErrorCode success = U_ZERO_ERROR;
256 : * MessageFormat* form("The disk \"{1}\" contains {0}.", success);
257 : * double filelimits[] = {0,1,2};
258 : * UnicodeString filepart[] = {"no files","one file","{0,number} files"};
259 : * ChoiceFormat* fileform = new ChoiceFormat(filelimits, filepart, 3);
260 : * form.setFormat(1, *fileform); // NOT zero, see below
261 : *
262 : * Formattable testArgs[] = {1273L, "MyDisk"};
263 : *
264 : * UnicodeString string;
265 : * FieldPosition fpos = 0;
266 : * cout << form.format(testArgs, 2, string, fpos, success) << endl;
267 : *
268 : * // output, with different testArgs
269 : * // output: The disk "MyDisk" contains no files.
270 : * // output: The disk "MyDisk" contains one file.
271 : * // output: The disk "MyDisk" contains 1,273 files.
272 : * \endcode
273 : * </pre>
274 : * You can either do this programmatically, as in the above example,
275 : * or by using a pattern (see ChoiceFormat for more information) as in:
276 : * <pre>
277 : * \code
278 : * form.applyPattern(
279 : * "There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.");
280 : * \endcode
281 : * </pre>
282 : * <P>
283 : * <EM>Note:</EM> As we see above, the string produced by a ChoiceFormat in
284 : * MessageFormat is treated specially; occurences of '{' are used to
285 : * indicated subformats, and cause recursion. If you create both a
286 : * MessageFormat and ChoiceFormat programmatically (instead of using
287 : * the string patterns), then be careful not to produce a format that
288 : * recurses on itself, which will cause an infinite loop.
289 : * <P>
290 : * <EM>Note:</EM> Subformats are numbered by their order in the pattern.
291 : * This is <EM>not</EM> the same as the argumentIndex.
292 : * <pre>
293 : * \code
294 : * For example: with "abc{2}def{3}ghi{0}...",
295 : *
296 : * format0 affects the first variable {2}
297 : * format1 affects the second variable {3}
298 : * format2 affects the second variable {0}
299 : * \endcode
300 : * </pre>
301 : *
302 : * <p><em>User subclasses are not supported.</em> While clients may write
303 : * subclasses, such code will not necessarily work and will not be
304 : * guaranteed to work stably from release to release.
305 : */
306 : class U_I18N_API MessageFormat : public Format {
307 : public:
308 : /**
309 : * Enum type for kMaxFormat.
310 : * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6,
311 : * rendering this enum type obsolete.
312 : */
313 : enum EFormatNumber {
314 : /**
315 : * The maximum number of arguments.
316 : * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6,
317 : * rendering this constant obsolete.
318 : */
319 : kMaxFormat = 10
320 : };
321 :
322 : /**
323 : * Constructs a new MessageFormat using the given pattern and the
324 : * default locale.
325 : *
326 : * @param pattern Pattern used to construct object.
327 : * @param status Input/output error code. If the
328 : * pattern cannot be parsed, set to failure code.
329 : * @stable ICU 2.0
330 : */
331 : MessageFormat(const UnicodeString& pattern,
332 : UErrorCode &status);
333 :
334 : /**
335 : * Constructs a new MessageFormat using the given pattern and locale.
336 : * @param pattern Pattern used to construct object.
337 : * @param newLocale The locale to use for formatting dates and numbers.
338 : * @param status Input/output error code. If the
339 : * pattern cannot be parsed, set to failure code.
340 : * @stable ICU 2.0
341 : */
342 : MessageFormat(const UnicodeString& pattern,
343 : const Locale& newLocale,
344 : UErrorCode& status);
345 : /**
346 : * Constructs a new MessageFormat using the given pattern and locale.
347 : * @param pattern Pattern used to construct object.
348 : * @param newLocale The locale to use for formatting dates and numbers.
349 : * @param parseError Struct to recieve information on position
350 : * of error within the pattern.
351 : * @param status Input/output error code. If the
352 : * pattern cannot be parsed, set to failure code.
353 : * @stable ICU 2.0
354 : */
355 : MessageFormat(const UnicodeString& pattern,
356 : const Locale& newLocale,
357 : UParseError& parseError,
358 : UErrorCode& status);
359 : /**
360 : * Constructs a new MessageFormat from an existing one.
361 : * @stable ICU 2.0
362 : */
363 : MessageFormat(const MessageFormat&);
364 :
365 : /**
366 : * Assignment operator.
367 : * @stable ICU 2.0
368 : */
369 : const MessageFormat& operator=(const MessageFormat&);
370 :
371 : /**
372 : * Destructor.
373 : * @stable ICU 2.0
374 : */
375 : virtual ~MessageFormat();
376 :
377 : /**
378 : * Clones this Format object polymorphically. The caller owns the
379 : * result and should delete it when done.
380 : * @stable ICU 2.0
381 : */
382 : virtual Format* clone(void) const;
383 :
384 : /**
385 : * Returns true if the given Format objects are semantically equal.
386 : * Objects of different subclasses are considered unequal.
387 : * @param other the object to be compared with.
388 : * @return true if the given Format objects are semantically equal.
389 : * @stable ICU 2.0
390 : */
391 : virtual UBool operator==(const Format& other) const;
392 :
393 : /**
394 : * Sets the locale. This locale is used for fetching default number or date
395 : * format information.
396 : * @param theLocale the new locale value to be set.
397 : * @stable ICU 2.0
398 : */
399 : virtual void setLocale(const Locale& theLocale);
400 :
401 : /**
402 : * Gets the locale. This locale is used for fetching default number or date
403 : * format information.
404 : * @return the locale of the object.
405 : * @stable ICU 2.0
406 : */
407 : virtual const Locale& getLocale(void) const;
408 :
409 : /**
410 : * Applies the given pattern string to this message format.
411 : *
412 : * @param pattern The pattern to be applied.
413 : * @param status Input/output error code. If the
414 : * pattern cannot be parsed, set to failure code.
415 : * @stable ICU 2.0
416 : */
417 : virtual void applyPattern(const UnicodeString& pattern,
418 : UErrorCode& status);
419 : /**
420 : * Applies the given pattern string to this message format.
421 : *
422 : * @param pattern The pattern to be applied.
423 : * @param parseError Struct to recieve information on position
424 : * of error within pattern.
425 : * @param status Input/output error code. If the
426 : * pattern cannot be parsed, set to failure code.
427 : * @stable ICU 2.0
428 : */
429 : virtual void applyPattern(const UnicodeString& pattern,
430 : UParseError& parseError,
431 : UErrorCode& status);
432 :
433 : /**
434 : * Returns a pattern that can be used to recreate this object.
435 : *
436 : * @param appendTo Output parameter to receive the pattern.
437 : * Result is appended to existing contents.
438 : * @return Reference to 'appendTo' parameter.
439 : * @stable ICU 2.0
440 : */
441 : virtual UnicodeString& toPattern(UnicodeString& appendTo) const;
442 :
443 : /**
444 : * Sets subformats.
445 : * See the class description about format numbering.
446 : * The caller should not delete the Format objects after this call.
447 : * <EM>The array formatsToAdopt is not itself adopted.</EM> Its
448 : * ownership is retained by the caller. If the call fails because
449 : * memory cannot be allocated, then the formats will be deleted
450 : * by this method, and this object will remain unchanged.
451 : *
452 : * @stable ICU 2.0
453 : * @param formatsToAdopt the format to be adopted.
454 : * @param count the size of the array.
455 : */
456 : virtual void adoptFormats(Format** formatsToAdopt, int32_t count);
457 :
458 : /**
459 : * Sets subformats.
460 : * See the class description about format numbering.
461 : * Each item in the array is cloned into the internal array.
462 : * If the call fails because memory cannot be allocated, then this
463 : * object will remain unchanged.
464 : *
465 : * @stable ICU 2.0
466 : * @param newFormats the new format to be set.
467 : * @param cnt the size of the array.
468 : */
469 : virtual void setFormats(const Format** newFormats, int32_t cnt);
470 :
471 :
472 : /**
473 : * Sets one subformat.
474 : * See the class description about format numbering.
475 : * The caller should not delete the Format object after this call.
476 : * If the number is over the number of formats already set,
477 : * the item will be deleted and ignored.
478 : * @stable ICU 2.0
479 : * @param formatNumber index of the subformat.
480 : * @param formatToAdopt the format to be adopted.
481 : */
482 : virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt);
483 :
484 : /**
485 : * Sets one subformat.
486 : * See the class description about format numbering.
487 : * If the number is over the number of formats already set,
488 : * the item will be ignored.
489 : * @param formatNumber index of the subformat.
490 : * @param format the format to be set.
491 : * @stable ICU 2.0
492 : */
493 : virtual void setFormat(int32_t formatNumber, const Format& format);
494 :
495 : /**
496 : * Gets format names. This function returns formatNames in StringEnumerations
497 : * which can be used with getFormat() and setFormat() to export formattable
498 : * array from current MessageFormat to another. It is caller's resposibility
499 : * to delete the returned formatNames.
500 : * @param status output param set to success/failure code.
501 : * @stable ICU 4.0
502 : */
503 : virtual StringEnumeration* getFormatNames(UErrorCode& status);
504 :
505 : /**
506 : * Gets subformat pointer for given format name.
507 : * This function supports both named and numbered
508 : * arguments-- if numbered, the formatName is the
509 : * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
510 : * The returned Format object should not be deleted by the caller,
511 : * nor should the ponter of other object . The pointer and its
512 : * contents remain valid only until the next call to any method
513 : * of this class is made with this object.
514 : * @param formatName the name or number specifying a format
515 : * @param status output param set to success/failure code.
516 : * @stable ICU 4.0
517 : */
518 : virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status);
519 :
520 : /**
521 : * Sets one subformat for given format name.
522 : * See the class description about format name.
523 : * This function supports both named and numbered
524 : * arguments-- if numbered, the formatName is the
525 : * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
526 : * If there is no matched formatName or wrong type,
527 : * the item will be ignored.
528 : * @param formatName Name of the subformat.
529 : * @param format the format to be set.
530 : * @param status output param set to success/failure code.
531 : * @stable ICU 4.0
532 : */
533 : virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status);
534 :
535 : /**
536 : * Sets one subformat for given format name.
537 : * See the class description about format name.
538 : * This function supports both named and numbered
539 : * arguments-- if numbered, the formatName is the
540 : * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
541 : * If there is no matched formatName or wrong type,
542 : * the item will be ignored.
543 : * The caller should not delete the Format object after this call.
544 : * @param formatName Name of the subformat.
545 : * @param formatToAdopt Format to be adopted.
546 : * @param status output param set to success/failure code.
547 : * @stable ICU 4.0
548 : */
549 : virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status);
550 :
551 :
552 : /**
553 : * Gets an array of subformats of this object. The returned array
554 : * should not be deleted by the caller, nor should the pointers
555 : * within the array. The array and its contents remain valid only
556 : * until the next call to any method of this class is made with
557 : * this object. See the class description about format numbering.
558 : * @param count output parameter to receive the size of the array
559 : * @return an array of count Format* objects, or NULL if out of
560 : * memory. Any or all of the array elements may be NULL.
561 : * @stable ICU 2.0
562 : */
563 : virtual const Format** getFormats(int32_t& count) const;
564 :
565 : /**
566 : * Formats the given array of arguments into a user-readable string.
567 : * Does not take ownership of the Formattable* array or its contents.
568 : *
569 : * @param source An array of objects to be formatted.
570 : * @param count The number of elements of 'source'.
571 : * @param appendTo Output parameter to receive result.
572 : * Result is appended to existing contents.
573 : * @param ignore Not used; inherited from base class API.
574 : * @param status Input/output error code. If the
575 : * pattern cannot be parsed, set to failure code.
576 : * @return Reference to 'appendTo' parameter.
577 : * @stable ICU 2.0
578 : */
579 : UnicodeString& format( const Formattable* source,
580 : int32_t count,
581 : UnicodeString& appendTo,
582 : FieldPosition& ignore,
583 : UErrorCode& status) const;
584 :
585 : /**
586 : * Formats the given array of arguments into a user-readable string
587 : * using the given pattern.
588 : *
589 : * @param pattern The pattern.
590 : * @param arguments An array of objects to be formatted.
591 : * @param count The number of elements of 'source'.
592 : * @param appendTo Output parameter to receive result.
593 : * Result is appended to existing contents.
594 : * @param status Input/output error code. If the
595 : * pattern cannot be parsed, set to failure code.
596 : * @return Reference to 'appendTo' parameter.
597 : * @stable ICU 2.0
598 : */
599 : static UnicodeString& format(const UnicodeString& pattern,
600 : const Formattable* arguments,
601 : int32_t count,
602 : UnicodeString& appendTo,
603 : UErrorCode& status);
604 :
605 : /**
606 : * Formats the given array of arguments into a user-readable
607 : * string. The array must be stored within a single Formattable
608 : * object of type kArray. If the Formattable object type is not of
609 : * type kArray, then returns a failing UErrorCode.
610 : *
611 : * @param obj A Formattable of type kArray containing
612 : * arguments to be formatted.
613 : * @param appendTo Output parameter to receive result.
614 : * Result is appended to existing contents.
615 : * @param pos On input: an alignment field, if desired.
616 : * On output: the offsets of the alignment field.
617 : * @param status Input/output error code. If the
618 : * pattern cannot be parsed, set to failure code.
619 : * @return Reference to 'appendTo' parameter.
620 : * @stable ICU 2.0
621 : */
622 : virtual UnicodeString& format(const Formattable& obj,
623 : UnicodeString& appendTo,
624 : FieldPosition& pos,
625 : UErrorCode& status) const;
626 :
627 : /**
628 : * Formats the given array of arguments into a user-readable
629 : * string. The array must be stored within a single Formattable
630 : * object of type kArray. If the Formattable object type is not of
631 : * type kArray, then returns a failing UErrorCode.
632 : *
633 : * @param obj The object to format
634 : * @param appendTo Output parameter to receive result.
635 : * Result is appended to existing contents.
636 : * @param status Input/output error code. If the
637 : * pattern cannot be parsed, set to failure code.
638 : * @return Reference to 'appendTo' parameter.
639 : * @stable ICU 2.0
640 : */
641 : UnicodeString& format(const Formattable& obj,
642 : UnicodeString& appendTo,
643 : UErrorCode& status) const;
644 :
645 :
646 : /**
647 : * Formats the given array of arguments into a user-defined argument name
648 : * array. This function supports both named and numbered
649 : * arguments-- if numbered, the formatName is the
650 : * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
651 : *
652 : * @param argumentNames argument name array
653 : * @param arguments An array of objects to be formatted.
654 : * @param count The number of elements of 'argumentNames' and
655 : * arguments. The number of argumentNames and arguments
656 : * must be the same.
657 : * @param appendTo Output parameter to receive result.
658 : * Result is appended to existing contents.
659 : * @param status Input/output error code. If the
660 : * pattern cannot be parsed, set to failure code.
661 : * @return Reference to 'appendTo' parameter.
662 : * @stable ICU 4.0
663 : */
664 : UnicodeString& format(const UnicodeString* argumentNames,
665 : const Formattable* arguments,
666 : int32_t count,
667 : UnicodeString& appendTo,
668 : UErrorCode& status) const;
669 : /**
670 : * Parses the given string into an array of output arguments.
671 : *
672 : * @param source String to be parsed.
673 : * @param pos On input, starting position for parse. On output,
674 : * final position after parse. Unchanged if parse
675 : * fails.
676 : * @param count Output parameter to receive the number of arguments
677 : * parsed.
678 : * @return an array of parsed arguments. The caller owns both
679 : * the array and its contents.
680 : * @stable ICU 2.0
681 : */
682 : virtual Formattable* parse( const UnicodeString& source,
683 : ParsePosition& pos,
684 : int32_t& count) const;
685 :
686 : /**
687 : * Parses the given string into an array of output arguments.
688 : *
689 : * @param source String to be parsed.
690 : * @param count Output param to receive size of returned array.
691 : * @param status Input/output error code. If the
692 : * pattern cannot be parsed, set to failure code.
693 : * If the MessageFormat is named argument, the status is
694 : * set to U_ARGUMENT_TYPE_MISMATCH.
695 : * @return an array of parsed arguments. The caller owns both
696 : * the array and its contents. Return NULL if status is not U_ZERO_ERROR.
697 : *
698 : * @stable ICU 2.0
699 : */
700 : virtual Formattable* parse( const UnicodeString& source,
701 : int32_t& count,
702 : UErrorCode& status) const;
703 :
704 : /**
705 : * Parses the given string into an array of output arguments
706 : * stored within a single Formattable of type kArray.
707 : *
708 : * @param source The string to be parsed into an object.
709 : * @param result Formattable to be set to the parse result.
710 : * If parse fails, return contents are undefined.
711 : * @param pos On input, starting position for parse. On output,
712 : * final position after parse. Unchanged if parse
713 : * fails.
714 : * @stable ICU 2.0
715 : */
716 : virtual void parseObject(const UnicodeString& source,
717 : Formattable& result,
718 : ParsePosition& pos) const;
719 :
720 : /**
721 : * Convert an 'apostrophe-friendly' pattern into a standard
722 : * pattern. Standard patterns treat all apostrophes as
723 : * quotes, which is problematic in some languages, e.g.
724 : * French, where apostrophe is commonly used. This utility
725 : * assumes that only an unpaired apostrophe immediately before
726 : * a brace is a true quote. Other unpaired apostrophes are paired,
727 : * and the resulting standard pattern string is returned.
728 : *
729 : * <p><b>Note</b> it is not guaranteed that the returned pattern
730 : * is indeed a valid pattern. The only effect is to convert
731 : * between patterns having different quoting semantics.
732 : *
733 : * @param pattern the 'apostrophe-friendly' patttern to convert
734 : * @param status Input/output error code. If the pattern
735 : * cannot be parsed, the failure code is set.
736 : * @return the standard equivalent of the original pattern
737 : * @stable ICU 3.4
738 : */
739 : static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern,
740 : UErrorCode& status);
741 :
742 : /**
743 : * Returns true if this MessageFormat uses named arguments,
744 : * and false otherwise. See class description.
745 : *
746 : * @return true if named arguments are used.
747 : * @stable ICU 4.0
748 : */
749 : UBool usesNamedArguments() const;
750 :
751 :
752 : /**
753 : * This API is for ICU internal use only.
754 : * Please do not use it.
755 : *
756 : * Returns argument types count in the parsed pattern.
757 : * Used to distinguish pattern "{0} d" and "d".
758 : *
759 : * @return The number of formattable types in the pattern
760 : * @internal
761 : */
762 : int32_t getArgTypeCount() const;
763 :
764 : /**
765 : * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
766 : * This method is to implement a simple version of RTTI, since not all
767 : * C++ compilers support genuine RTTI. Polymorphic operator==() and
768 : * clone() methods call this method.
769 : *
770 : * @return The class ID for this object. All objects of a
771 : * given class have the same class ID. Objects of
772 : * other classes have different class IDs.
773 : * @stable ICU 2.0
774 : */
775 : virtual UClassID getDynamicClassID(void) const;
776 :
777 : /**
778 : * Return the class ID for this class. This is useful only for
779 : * comparing to a return value from getDynamicClassID(). For example:
780 : * <pre>
781 : * . Base* polymorphic_pointer = createPolymorphicObject();
782 : * . if (polymorphic_pointer->getDynamicClassID() ==
783 : * . Derived::getStaticClassID()) ...
784 : * </pre>
785 : * @return The class ID for all objects of this class.
786 : * @stable ICU 2.0
787 : */
788 : static UClassID U_EXPORT2 getStaticClassID(void);
789 :
790 : private:
791 :
792 : Locale fLocale;
793 : UnicodeString fPattern;
794 : Format** formatAliases; // see getFormats
795 : int32_t formatAliasesCapacity;
796 : UProperty idStart;
797 : UProperty idContinue;
798 :
799 : MessageFormat(); // default constructor not implemented
800 :
801 : /*
802 : * A structure representing one subformat of this MessageFormat.
803 : * Each subformat has a Format object, an offset into the plain
804 : * pattern text fPattern, and an argument number. The argument
805 : * number corresponds to the array of arguments to be formatted.
806 : * @internal
807 : */
808 : class Subformat;
809 :
810 : /**
811 : * A MessageFormat contains an array of subformats. This array
812 : * needs to grow dynamically if the MessageFormat is modified.
813 : */
814 : Subformat* subformats;
815 : int32_t subformatCount;
816 : int32_t subformatCapacity;
817 :
818 : /**
819 : * A MessageFormat formats an array of arguments. Each argument
820 : * has an expected type, based on the pattern. For example, if
821 : * the pattern contains the subformat "{3,number,integer}", then
822 : * we expect argument 3 to have type Formattable::kLong. This
823 : * array needs to grow dynamically if the MessageFormat is
824 : * modified.
825 : */
826 : Formattable::Type* argTypes;
827 : int32_t argTypeCount;
828 : int32_t argTypeCapacity;
829 :
830 : /**
831 : * Is true iff all argument names are non-negative numbers.
832 : *
833 : */
834 : UBool isArgNumeric;
835 :
836 : // Variable-size array management
837 : UBool allocateSubformats(int32_t capacity);
838 : UBool allocateArgTypes(int32_t capacity);
839 :
840 : /**
841 : * Default Format objects used when no format is specified and a
842 : * numeric or date argument is formatted. These are volatile
843 : * cache objects maintained only for performance. They do not
844 : * participate in operator=(), copy constructor(), nor
845 : * operator==().
846 : */
847 : NumberFormat* defaultNumberFormat;
848 : DateFormat* defaultDateFormat;
849 :
850 : /**
851 : * Method to retrieve default formats (or NULL on failure).
852 : * These are semantically const, but may modify *this.
853 : */
854 : const NumberFormat* getDefaultNumberFormat(UErrorCode&) const;
855 : const DateFormat* getDefaultDateFormat(UErrorCode&) const;
856 :
857 : /**
858 : * Finds the word s, in the keyword list and returns the located index.
859 : * @param s the keyword to be searched for.
860 : * @param list the list of keywords to be searched with.
861 : * @return the index of the list which matches the keyword s.
862 : */
863 : static int32_t findKeyword( const UnicodeString& s,
864 : const UChar * const *list);
865 :
866 : /**
867 : * Formats the array of arguments and copies the result into the
868 : * result buffer, updates the field position.
869 : *
870 : * @param arguments The formattable objects array.
871 : * @param cnt The array count.
872 : * @param appendTo Output parameter to receive result.
873 : * Result is appended to existing contents.
874 : * @param status Field position status.
875 : * @param recursionProtection
876 : * Initially zero. Bits 0..9 are used to indicate
877 : * that a parameter has already been seen, to
878 : * avoid recursion. Currently unused.
879 : * @param success The error code status.
880 : * @return Reference to 'appendTo' parameter.
881 : */
882 : UnicodeString& format( const Formattable* arguments,
883 : int32_t cnt,
884 : UnicodeString& appendTo,
885 : FieldPosition& status,
886 : int32_t recursionProtection,
887 : UErrorCode& success) const;
888 :
889 : UnicodeString& format( const Formattable* arguments,
890 : const UnicodeString *argumentNames,
891 : int32_t cnt,
892 : UnicodeString& appendTo,
893 : FieldPosition& status,
894 : int32_t recursionProtection,
895 : UErrorCode& success) const;
896 :
897 : void makeFormat(int32_t offsetNumber,
898 : UnicodeString* segments,
899 : UParseError& parseError,
900 : UErrorCode& success);
901 :
902 : /**
903 : * Convenience method that ought to be in NumberFormat
904 : */
905 : NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const;
906 :
907 : /**
908 : * Checks the range of the source text to quote the special
909 : * characters, { and ' and copy to target buffer.
910 : * @param source
911 : * @param start the text offset to start the process of in the source string
912 : * @param end the text offset to end the process of in the source string
913 : * @param appendTo Output parameter to receive result.
914 : * Result is appended to existing contents.
915 : */
916 : static void copyAndFixQuotes(const UnicodeString& appendTo, int32_t start, int32_t end, UnicodeString& target);
917 :
918 : /**
919 : * Returns array of argument types in the parsed pattern
920 : * for use in C API. Only for the use of umsg_vformat(). Not
921 : * for public consumption.
922 : * @param listCount Output parameter to receive the size of array
923 : * @return The array of formattable types in the pattern
924 : * @internal
925 : */
926 36 : const Formattable::Type* getArgTypeList(int32_t& listCount) const {
927 36 : listCount = argTypeCount;
928 36 : return argTypes;
929 : }
930 :
931 : /**
932 : * Returns FALSE if the argument name is not legal.
933 : * @param argName argument name.
934 : * @return TRUE if the argument name is legal, otherwise return FALSE.
935 : */
936 : UBool isLegalArgName(const UnicodeString& argName) const;
937 :
938 : friend class MessageFormatAdapter; // getFormatTypeList() access
939 : };
940 :
941 : inline UnicodeString&
942 : MessageFormat::format(const Formattable& obj,
943 : UnicodeString& appendTo,
944 : UErrorCode& status) const {
945 : return Format::format(obj, appendTo, status);
946 : }
947 : U_NAMESPACE_END
948 :
949 : #endif /* #if !UCONFIG_NO_FORMATTING */
950 :
951 : #endif // _MSGFMT
952 : //eof
953 :
|
