#include <msgfmt.h>
Class diagram for MessageFormat:
Public Members | |||
![]() | ![]() | enum | EFormatNumber { kMaxFormat } |
![]() | ![]() | MessageFormat (const UnicodeString& pattern, UErrorCode &status) | |
![]() | ![]() | Construct a new MessageFormat using the given pattern. More... | |
![]() | ![]() | MessageFormat (const UnicodeString& pattern, const Locale& newLocale, UErrorCode& success) | |
![]() | ![]() | Constructor that allows locale specification. More... | |
![]() | ![]() | MessageFormat (const MessageFormat&) | |
![]() | ![]() | Copy constructor. More... | |
![]() | ![]() | const MessageFormat& | operator= (const MessageFormat&) |
![]() | ![]() | Assignment operator. More... | |
![]() | ![]() | virtual | ~MessageFormat () |
![]() | ![]() | Destructor. More... | |
![]() | ![]() | virtual Format* | clone (void) const |
![]() | ![]() | Clone this Format object polymorphically. More... | |
![]() | ![]() | virtual UBool | operator== (const Format& other) const |
![]() | ![]() | Return true if the given Format objects are semantically equal. More... | |
![]() | ![]() | virtual void | setLocale (const Locale& theLocale) |
![]() | ![]() | Sets the locale. More... | |
![]() | ![]() | virtual const Locale& | getLocale (void) const |
![]() | ![]() | Gets the locale. More... | |
![]() | ![]() | virtual void | applyPattern (const UnicodeString& pattern, UErrorCode& status) |
![]() | ![]() | Apply the given pattern string to this message format. More... | |
![]() | ![]() | virtual UnicodeString& | toPattern (UnicodeString& result) const |
![]() | ![]() | Gets the pattern. More... | |
![]() | ![]() | virtual void | adoptFormats (Format** formatsToAdopt, int32_t count) |
![]() | ![]() | Sets formats to use on parameters. More... | |
![]() | ![]() | virtual void | setFormats (const Format** newFormats,int32_t cnt) |
![]() | ![]() | Sets formats to use on parameters. More... | |
![]() | ![]() | virtual void | adoptFormat (int32_t formatNumber, Format* formatToAdopt) |
![]() | ![]() | Sets formats individually to use on parameters. More... | |
![]() | ![]() | virtual void | setFormat (int32_t variable, const Format& newFormat) |
![]() | ![]() | Sets formats individually to use on parameters. More... | |
![]() | ![]() | virtual const Format** | getFormats (int32_t& count) const |
![]() | ![]() | Gets formats that were set with setFormats. More... | |
![]() | ![]() | UnicodeString& | format ( const Formattable* source, int32_t count, UnicodeString& result, FieldPosition& ignore, UErrorCode& success) const |
![]() | ![]() | Returns pattern with formatted objects. More... | |
![]() | ![]() | virtual UnicodeString& | format (const Formattable& obj, UnicodeString& toAppendTo, FieldPosition& pos, UErrorCode& status) const |
![]() | ![]() | Format an object to produce a message. More... | |
![]() | ![]() | UnicodeString& | format (const Formattable& obj, UnicodeString& result, UErrorCode& status) const |
![]() | ![]() | Redeclared Format method. More... | |
![]() | ![]() | virtual Formattable* | parse ( const UnicodeString& source, ParsePosition& status, int32_t& count) const |
![]() | ![]() | Parses the string. More... | |
![]() | ![]() | virtual Formattable* | parse ( const UnicodeString& source, int32_t& count, UErrorCode& status) const |
![]() | ![]() | Parses the string. More... | |
![]() | ![]() | virtual void | parseObject (const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const |
![]() | ![]() | Parse a string to produce an object. More... | |
![]() | ![]() | virtual UClassID | getDynamicClassID (void) const |
![]() | ![]() | Returns a unique class ID POLYMORPHICALLY. More... | |
Static Public Members | |||
![]() | ![]() | UnicodeString& | format ( const UnicodeString& pattern, const Formattable* arguments, int32_t count, UnicodeString& result, UErrorCode& success) |
![]() | ![]() | Convenience routine. More... | |
![]() | ![]() | UClassID | getStaticClassID (void) |
![]() | ![]() | Return the class ID for this class. More... |
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 = U_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.
Example 2:
. success = U_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)*
. 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 := choiceFormatPattern
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 = U_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.
. 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}
Definition at line 176 of file msgfmt.h.
enum MessageFormat::EFormatNumber |
MessageFormat::MessageFormat (const UnicodeString & pattern, UErrorCode & status) |
Construct a new MessageFormat using the given pattern.
pattern | Pattern used to construct object. |
status | Output param to receive success code. If the pattern cannot be parsed, set to failure code. |
MessageFormat::MessageFormat (const UnicodeString & pattern, const Locale & newLocale, UErrorCode & success) |
Constructor that allows locale specification.
pattern | Pattern used to construct object. |
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::MessageFormat (const MessageFormat &) |
Copy constructor.
const MessageFormat & MessageFormat::operator= (const MessageFormat &) |
Assignment operator.
virtual MessageFormat::~MessageFormat () [virtual]
|
Destructor.
virtual Format * MessageFormat::clone (void) const [virtual]
|
Clone this Format object polymorphically.
The caller owns the result and should delete it when done.
Reimplemented from Format.
virtual UBool MessageFormat::operator== (const Format & other) const [virtual]
|
Return true if the given Format objects are semantically equal.
Objects of different subclasses are considered unequal.
Reimplemented from Format.
virtual void MessageFormat::setLocale (const Locale & theLocale) [virtual]
|
Sets the locale.
This locale is used for fetching default number or date format information.
virtual const Locale & MessageFormat::getLocale (void) const [virtual]
|
Gets the locale.
This locale is used for fetching default number or date format information.
virtual void MessageFormat::applyPattern (const UnicodeString & pattern, UErrorCode & status) [virtual]
|
Apply the given pattern string to this message format.
pattern | The pattern to be applied. |
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 & MessageFormat::toPattern (UnicodeString & result) const [virtual]
|
Gets the pattern.
See the class description.
virtual void MessageFormat::adoptFormats (Format ** formatsToAdopt, int32_t count) [virtual]
|
Sets formats to use on parameters.
See the class description about format numbering. The caller should not delete the Format objects after this call.
virtual void MessageFormat::setFormats (const Format ** newFormats, int32_t cnt) [virtual]
|
Sets formats to use on parameters.
See the class description about format numbering.
virtual void MessageFormat::adoptFormat (int32_t formatNumber, Format * formatToAdopt) [virtual]
|
Sets formats individually to use on parameters.
See the class description about format numbering. The caller should not delete the Format object after this call.
virtual void MessageFormat::setFormat (int32_t variable, const Format & newFormat) [virtual]
|
Sets formats individually to use on parameters.
See the class description about format numbering.
virtual const Format ** MessageFormat::getFormats (int32_t & count) const [virtual]
|
Gets formats that were set with setFormats.
See the class description about format numbering.
UnicodeString & MessageFormat::format (const Formattable * source, int32_t count, UnicodeString & result, FieldPosition & ignore, UErrorCode & success) const |
Returns pattern with formatted objects.
Does not take ownership of the Formattable* array; just reads it and uses it to generate the format string.
source | An array of objects to be formatted & substituted. |
result | Where text is appended. |
ignore | No useful status is returned. |
virtual UnicodeString & MessageFormat::format (const Formattable & obj, UnicodeString & toAppendTo, FieldPosition & pos, UErrorCode & status) const [virtual]
|
Format an object to produce a message.
This method handles Formattable objects of type kArray. If the Formattable object type is not of type kArray, then it returns a failing UErrorCode.
obj | The object to format |
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. |
Reimplemented from Format.
UnicodeString & MessageFormat::format (const Formattable & obj, UnicodeString & result, UErrorCode & status) const [inline]
|
virtual Formattable * MessageFormat::parse (const UnicodeString & source, ParsePosition & status, int32_t & count) const [virtual]
|
Parses the string.
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.
source | String to be parsed. |
status | On input, starting position for parse. On output, final position after parse. |
count | Output param to receive size of returned array. |
virtual Formattable * MessageFormat::parse (const UnicodeString & source, int32_t & count, UErrorCode & status) const [virtual]
|
Parses the string.
Does not yet handle recursion (where the substituted strings contain {n} references.)
source | String to be parsed. |
count | Output param to receive size of returned array. |
status | Output param to receive success/error code. |
virtual void MessageFormat::parseObject (const UnicodeString & source, Formattable & result, ParsePosition & parse_pos) const [virtual]
|
Parse a string to produce an object.
This methods handles parsing of message strings into arrays of Formattable objects. Does not yet handle recursion (where the substituted strings contain n references.)
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.
source | The string to be parsed into an object. |
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. |
Reimplemented from Format.
UClassID MessageFormat::getDynamicClassID (void) const [inline, virtual]
|
Returns a unique class ID POLYMORPHICALLY.
Pure virtual override. This method is to implement a simple version of RTTI, since not all C++ compilers support genuine RTTI. Polymorphic operator==() and clone() methods call this method.
Reimplemented from Format.
UnicodeString & MessageFormat::format (const UnicodeString & pattern, const Formattable * arguments, int32_t count, UnicodeString & result, UErrorCode & success) [static]
|
Convenience routine.
Avoids explicit creation of MessageFormat, but doesn't allow future optimizations.
UClassID MessageFormat::getStaticClassID (void) [inline, static]
|
Return the class ID for this class.
This is useful only for comparing to a return value from getDynamicClassID(). For example:
. Base* polymorphic_pointer = createPolymorphicObject(); . if (polymorphic_pointer->getDynamicClassID() == . Derived::getStaticClassID()) ...