Provides means to produce concatenated messages in language-neutral way
Provides means to produce concatenated messages in language-neutral way. Use this for all concatenations that show up to end users.Takes a set of objects, formats them, then inserts the formatted strings into the pattern at the appropriate places.
Here are some examples of usage: Example 1:
. UErrorCode success = ZERO_ERROR; . GregorianCalendar cal(success); . Formattable arguments[] = { . 7L, . Formattable( (Date) cal.getTime(success), Formattable::kIsDate), . "a disturbance in the Force" . }; . . UnicodeString result; . MessageFormat::format( . "At {1,time} on {1,date}, there was {2} on planet {0,number}.", . arguments, 3, result, success ); . . cout << "result: " << result << endl; . //<output>: At 4:34:20 PM on 23-Mar-98, there was a disturbance . // in the Force on planet 7.Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.Example 2:
. success = ZERO_ERROR; . Formattable testArgs[] = {3L, "MyDisk"}; . . MessageFormat* form = new MessageFormat( . "The disk \"{1}\" contains {0} file(s).", success ); . . UnicodeString string; . FieldPosition fpos = 0; . cout << "format: " << form->format(testArgs, 2, string, fpos, success ) << endl; . . // output, with different testArgs: . // output: The disk "MyDisk" contains 0 file(s). . // output: The disk "MyDisk" contains 1 file(s). . // output: The disk "MyDisk" contains 1,273 file(s). . de lete form;The pattern is of the following form. Legend:. {optional item} . (group that may be repeated)*Do not confuse optional items with items inside quotes braces, such as this: "{". Quoted braces are literals.. messageFormatPattern := string ( "{" messageFormatElement "}" string )* . . messageFormatElement := argument { "," elementFormat } . . elementFormat := "time" { "," datetimeStyle } . | "date" { "," datetimeStyle } . | "number" { "," numberStyle } . | "choice" "," choiceStyle . . datetimeStyle := "short" . | "medium" . | "long" . | "full" . | dateFormatPattern . . numberStyle := "currency" . | "percent" . | "integer" . | numberFormatPattern . . choiceStyle := choiceFormatPatternIf there is no elementFormat, then the argument must be a string, which is substituted. If there is no dateTimeStyle or numberStyle, then the default format is used (e.g. NumberFormat.getInstance(), DateFormat.getDefaultTime() or DateFormat.getDefaultDate(). For a ChoiceFormat, the pattern must always be specified, since there is no default.In strings, single quotes can be used to quote the "{" sign if necessary. A real single quote is represented by ''. Inside a messageFormatElement, quotes are [not] removed. For example, {1,number,$'#',##} will produce a number format with the pound-sign quoted, with a result such as: "$#31,45".
If a pattern is used, then unquoted braces in the pattern, if any, must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab {0'}' de" and "ab } de" are not.
The argument is a number from 0 to 9, which corresponds to the arguments presented in an array to be formatted.
It is ok to have unused arguments in the array. With missing arguments or arguments that are not of the right class for the specified format, a failing UErrorCode result is set.
For more sophisticated patterns, you can use a ChoiceFormat to get output such as:
. UErrorCode success = ZERO_ERROR; . MessageFormat* form = new MessageFormat("The disk \"{1}\" contains {0}.", success); . double filelimits[] = {0,1,2}; . UnicodeString filepart[] = {"no files","one file","{0,number} files"}; . ChoiceFormat* fileform = new ChoiceFormat(filelimits, filepart, 3); . form->setFormat(1, *fileform); // NOT zero, see below . . Formattable testArgs[] = {1273L, "MyDisk"}; . . UnicodeString string; . FieldPosition fpos = 0; . cout << form->format(testArgs, 2, string, fpos, success) << endl; . . // output, with different testArgs . // output: The disk "MyDisk" contains no files. . // output: The disk "MyDisk" contains one file. . // output: The disk "MyDisk" contains 1,273 files.You can either do this programmatically, as in the above example, or by using a pattern (see ChoiceFormat for more information) as in:. form->applyPattern( . "There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.");[Note:] As we see above, the string produced by a ChoiceFormat in MessageFormat is treated specially; occurances of '{' are used to indicated subformats, and cause recursion. If you create both a MessageFormat and ChoiceFormat programmatically (instead of using the string patterns), then be careful not to produce a format that recurses on itself, which will cause an infinite loop.
[Note:] Formats are numbered by order of variable in the string. This is [not] the same as the argument numbering!
. For example: with "abc{2}def{3}ghi{0}...", . . format0 affects the first variable {2} . format1 affects the second variable {3} . format2 affects the second variable {0}and so on.
Caveats: The parse may fail in a number of circumstances. For
example:
If one of the arguments does not occur in the pattern.
If the format of an argument is loses information, such as with
a choice format where a large number formats to "many".
Does not yet handle recursion (where the substituted strings
contain {n} references.)
Will not always find a match (or the correct match) if some
part of the parse is ambiguous. For example, if the pattern
"{1},{2}" is used with the string arguments {"a,b", "c"}, it
will format as "a,b,c". When the result is parsed, it will
return {"a", "b,c"}.
If a single argument is formatted twice in the string, then the
later parse wins.
Before calling, set parse_pos.index to the offset you want to
start parsing at in the source. After calling, parse_pos.index
is the end of the text you parsed. If error occurs, index is
unchanged.
When parsing, leading whitespace is discarded (with successful
parse), while trailing whitespace is left as is.
See Format::parseObject() for more.
static const Locale FRANCE
Locale()
Locale( const UnicodeString& language, const UnicodeString& country, const UnicodeString& variant )
country - Uppercase two-letter ISO-3166 code. (optional)
variant - Uppercase vendor and browser specific code. See class
description. (optional) Locale(const Locale& other)
~Locale()
Locale& operator=(const Locale& other)
bool_t operator==(const Locale& other) const
bool_t operator!=(const Locale& other) const
static Locale& getDefault(void)
static void setDefault(const Locale& newLocale, UErrorCode& success)
UnicodeString& getLanguage( UnicodeString& lang) const
UnicodeString& getCountry( UnicodeString& cntry) const
UnicodeString& getVariant( UnicodeString& var) const
UnicodeString& getName( UnicodeString& name) const
UnicodeString& getISO3Language(UnicodeString& name, UErrorCode& status) const
status - An UErrorCode to receive any MISSING_RESOURCE_ERRORs
UnicodeString& getISO3Country( UnicodeString& name, UErrorCode& status) const
status - An UErrorCode to receive any MISSING_RESOURCE_ERRORs
uint32_t getLCID(void) const
UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const
UnicodeString& getDisplayLanguage( const Locale& inLocale, UnicodeString& dispLang) const
dispLang - Receives the language's display name.
UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const
UnicodeString& getDisplayCountry( const Locale& inLocale, UnicodeString& dispCountry) const
dispCountry - Receives the country's display name.
UnicodeString& getDisplayVariant( UnicodeString& dispVar) const
UnicodeString& getDisplayVariant( const Locale& inLocale, UnicodeString& dispVar) const
dispVar - Receives the variant's display name.
UnicodeString& getDisplayName( UnicodeString& name) const
UnicodeString& getDisplayName( const Locale& inLocale, UnicodeString& name) const
name - Receives the locale's display name.
int32_t hashCode(void) const
static const Locale* getAvailableLocales(int32_t& count)
static const UnicodeString* getISOCountries(int32_t& count)
static const UnicodeString* getISOLanguages(int32_t& count)
static const char* getDataDirectory(void)
static void setDataDirectory(const char* path)
static const UnicodeString* getLanguagesForCountry( const UnicodeString& country, int32_t& count)
count - Receives the number of languages in the list.
MessageFormat(const UnicodeString& pattern, UErrorCode &status)
status - Output param to receive success code. If the
pattern cannot be parsed, set to failure code. MessageFormat(const UnicodeString& pattern, const Locale& newLocale, UErrorCode& success)
newLocale - The locale to use for formatting dates and numbers.
status - Output param to receive success code. If the
pattern cannot be parsed, set to failure code. MessageFormat(const MessageFormat&)
const MessageFormat& operator=(const MessageFormat&)
virtual ~MessageFormat()
virtual Format* clone(void) const
virtual bool_t operator==(const Format& other) const
virtual void setLocale(const Locale& theLocale)
virtual const Locale& getLocale(void) const
virtual void applyPattern(const UnicodeString& pattern, UErrorCode& status)
status - Output param set to success/failure code on
exit. If the pattern is invalid, this will be
set to a failure result. virtual UnicodeString& toPattern(UnicodeString& result) const
virtual void adoptFormats(Format** formatsToAdopt, int32_t count)
virtual void setFormats(const Format** newFormats, int32_t cnt)
virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt)
virtual void setFormat(int32_t variable, const Format& newFormat)
virtual const Format** getFormats(int32_t& count) const
UnicodeString& format( const Formattable* source, int32_t count, UnicodeString& result, FieldPosition& ignore, UErrorCode& success) const
result - Where text is appended.
ignore - No useful status is returned. static UnicodeString& format( const UnicodeString& pattern, const Formattable* arguments, int32_t count, UnicodeString& result, UErrorCode& success)
virtual UnicodeString& format(const Formattable& obj, UnicodeString& toAppendTo, FieldPosition& pos, UErrorCode& status) const
toAppendTo - Where the text is to be appended
pos - On input: an alignment field, if desired.
On output: the offsets of the alignment field.
status - Output param filled with success/failure status.
virtual Formattable* parse( const UnicodeString& source, ParsePosition& status, int32_t& count) const
status - On input, starting position for parse. On output,
final position after parse.
count - Output param to receive size of returned array.
@result Array of Formattable objects, with length
'count', owned by the caller. virtual Formattable* parse( const UnicodeString& source, int32_t& count, UErrorCode& status) const
count - Output param to receive size of returned array.
status - Output param to receive success/error code.
@result Array of Formattable objects, with length
'count', owned by the caller. virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const
result - Formattable to be set to the parse result.
If parse fails, return contents are undefined.
parse_pos - The position to start parsing at. Upon return
this param is set to the position after the
last character successfully parsed. If the
source is not parsed successfully, this param
will remain unchanged.
virtual ClassID getDynamicClassID(void) const
static ClassID getStaticClassID(void)
. Base* polymorphic_pointer = createPolymorphicObject();
. if (polymorphic_pointer->getDynamicClassID() ==
. Derived::getStaticClassID()) ...
alphabetic index hierarchy of classes
this page has been generated automatically by doc++
(c)opyright by Malte Zöckler, Roland Wunderling
contact: doc++@zib.de