#include <msgfmt.h>
Inheritance diagram for MessageFormat:
Public Types | |
enum | EFormatNumber { kMaxFormat = 10 } |
Enum type for kMaxFormat. More... | |
Public Member Functions | |
MessageFormat (const UnicodeString &pattern, UErrorCode &status) | |
Constructs a new MessageFormat using the given pattern and the default locale. | |
MessageFormat (const UnicodeString &pattern, const Locale &newLocale, UErrorCode &status) | |
Constructs a new MessageFormat using the given pattern and locale. | |
MessageFormat (const UnicodeString &pattern, const Locale &newLocale, UParseError &parseError, UErrorCode &status) | |
Constructs a new MessageFormat using the given pattern and locale. | |
MessageFormat (const MessageFormat &) | |
Constructs a new MessageFormat from an existing one. | |
const MessageFormat & | operator= (const MessageFormat &) |
Assignment operator. | |
virtual | ~MessageFormat () |
Destructor. | |
virtual Format * | clone (void) const |
Clones this Format object polymorphically. | |
virtual UBool | operator== (const Format &other) const |
Returns true if the given Format objects are semantically equal. | |
virtual void | setLocale (const Locale &theLocale) |
Sets the locale. | |
virtual const Locale & | getLocale (void) const |
Gets the locale. | |
virtual void | applyPattern (const UnicodeString &pattern, UErrorCode &status) |
Applies the given pattern string to this message format. | |
virtual void | applyPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status) |
Applies the given pattern string to this message format. | |
virtual UnicodeString & | toPattern (UnicodeString &appendTo) const |
Returns a pattern that can be used to recreate this object. | |
virtual void | adoptFormats (Format **formatsToAdopt, int32_t count) |
Sets subformats. | |
virtual void | setFormats (const Format **newFormats, int32_t cnt) |
Sets subformats. | |
virtual void | adoptFormat (int32_t formatNumber, Format *formatToAdopt) |
Sets one subformat. | |
virtual void | setFormat (int32_t formatNumber, const Format &format) |
Sets one subformat. | |
virtual const Format ** | getFormats (int32_t &count) const |
Gets an array of subformats of this object. | |
UnicodeString & | format (const Formattable *source, int32_t count, UnicodeString &appendTo, FieldPosition &ignore, UErrorCode &status) const |
Formats the given array of arguments into a user-readable string. | |
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const |
Formats the given array of arguments into a user-readable string. | |
UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const |
Formats the given array of arguments into a user-readable string. | |
virtual Formattable * | parse (const UnicodeString &source, ParsePosition &pos, int32_t &count) const |
Parses the given string into an array of output arguments. | |
virtual Formattable * | parse (const UnicodeString &source, int32_t &count, UErrorCode &status) const |
Parses the given string into an array of output arguments. | |
virtual void | parseObject (const UnicodeString &source, Formattable &result, ParsePosition &pos) const |
Parses the given string into an array of output arguments stored within a single Formattable of type kArray. | |
virtual UClassID | getDynamicClassID (void) const |
Returns a unique class ID POLYMORPHICALLY. | |
Static Public Member Functions | |
static UnicodeString & | format (const UnicodeString &pattern, const Formattable *arguments, int32_t count, UnicodeString &appendTo, UErrorCode &status) |
Formats the given array of arguments into a user-readable string using the given pattern. | |
static UnicodeString | autoQuoteApostrophe (const UnicodeString &pattern, UErrorCode &status) |
Convert an 'apostrophe-friendly' pattern into a standard pattern. | |
static UClassID | getStaticClassID (void) |
Return the class ID for this class. | |
Friends | |
class | MessageFormatAdapter |
Data Structures | |
class | Subformat |
It should be used for all string concatenations that are visible to end users.
A MessageFormat contains an array of subformats arranged within a template string. Together, the subformats and template string determine how the MessageFormat will operate during formatting and parsing.
Typically, both the subformats and the template string are specified at once in a pattern. By using different patterns for different locales, messages may be localized.
During formatting, the MessageFormat takes an array of arguments and produces a user-readable string. Each argument is a Formattable object; they may be passed in in an array, or as a single Formattable object which itself contains an array. Each argument is matched up with its corresponding subformat, which then formats it into a string. The resultant strings are then assembled within the string template of the MessageFormat to produce the final output string.
During parsing, an input string is matched against the string template of the MessageFormat to produce an array of Formattable objects. Plain text of the template string is matched directly against intput text. At each position in the template string where a subformat is located, the subformat is called to parse the corresponding segment of input text to produce an output argument. In this way, an array of arguments is created which together constitute the parse result.
Parsing may fail or produce unexpected results in a number of circumstances.
Example 1:
Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.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( "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).
The pattern is of the following form. Legend:
Do not confuse optional items with items inside quotes braces, such as this: "{". Quoted braces are literals.{optional item} (group that may be repeated)*
If 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::createInstance(), DateFormat::createTimeInstance(DateFormat::kDefault, ...) or DateFormat::createDateInstance(DateFormat::kDefault, ...). For a ChoiceFormat, the pattern must always be specified, since there is no default.messageFormatPattern := string ( "{" messageFormatElement "}" string )* messageFormatElement := argumentIndex { "," 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 syntax characters. A literal single quote is represented by '', both within and outside of single-quoted segments. 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 argumentIndex is a non-negative integer, which corresponds to the index of the arguments presented in an array to be formatted. The first argument has argumentIndex 0.
It is acceptable 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:
You can either do this programmatically, as in the above example, or by using a pattern (see ChoiceFormat for more information) as in:UErrorCode success = U_ZERO_ERROR; MessageFormat* form("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; occurences 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: Subformats are numbered by their order in the pattern. This is not the same as the argumentIndex.
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}
User subclasses are not supported. While clients may write subclasses, such code will not necessarily work and will not be guaranteed to work stably from release to release.
Definition at line 267 of file msgfmt.h.
MessageFormat::MessageFormat | ( | const UnicodeString & | pattern, | |
UErrorCode & | status | |||
) |
Constructs a new MessageFormat using the given pattern and the default locale.
pattern | Pattern used to construct object. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
MessageFormat::MessageFormat | ( | const UnicodeString & | pattern, | |
const Locale & | newLocale, | |||
UErrorCode & | status | |||
) |
Constructs a new MessageFormat using the given pattern and locale.
pattern | Pattern used to construct object. | |
newLocale | The locale to use for formatting dates and numbers. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
MessageFormat::MessageFormat | ( | const UnicodeString & | pattern, | |
const Locale & | newLocale, | |||
UParseError & | parseError, | |||
UErrorCode & | status | |||
) |
Constructs a new MessageFormat using the given pattern and locale.
pattern | Pattern used to construct object. | |
newLocale | The locale to use for formatting dates and numbers. | |
parseError | Struct to recieve information on position of error within the pattern. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
MessageFormat::MessageFormat | ( | const MessageFormat & | ) |
virtual MessageFormat::~MessageFormat | ( | ) | [virtual] |
const MessageFormat& MessageFormat::operator= | ( | const MessageFormat & | ) |
virtual Format* MessageFormat::clone | ( | void | ) | const [virtual] |
virtual void MessageFormat::setLocale | ( | const Locale & | theLocale | ) | [virtual] |
Sets the locale.
This locale is used for fetching default number or date format information.
theLocale | the new locale value to be set. |
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] |
Applies the given pattern string to this message format.
pattern | The pattern to be applied. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
virtual void MessageFormat::applyPattern | ( | const UnicodeString & | pattern, | |
UParseError & | parseError, | |||
UErrorCode & | status | |||
) | [virtual] |
Applies the given pattern string to this message format.
pattern | The pattern to be applied. | |
parseError | Struct to recieve information on position of error within pattern. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
virtual UnicodeString& MessageFormat::toPattern | ( | UnicodeString & | appendTo | ) | const [virtual] |
Returns a pattern that can be used to recreate this object.
appendTo | Output parameter to receive the pattern. Result is appended to existing contents. |
Sets subformats.
See the class description about format numbering. The caller should not delete the Format objects after this call. The array formatsToAdopt is not itself adopted. Its ownership is retained by the caller. If the call fails because memory cannot be allocated, then the formats will be deleted by this method, and this object will remain unchanged.
formatsToAdopt | the format to be adopted. | |
count | the size of the array. |
Sets subformats.
See the class description about format numbering. Each item in the array is cloned into the internal array. If the call fails because memory cannot be allocated, then this object will remain unchanged.
newFormats | the new format to be set. | |
cnt | the size of the array. |
Sets one subformat.
See the class description about format numbering. The caller should not delete the Format object after this call. If the number is over the number of formats already set, the item will be deleted and ignored.
formatNumber | index of the subformat. | |
formatToAdopt | the format to be adopted. |
Sets one subformat.
See the class description about format numbering. If the number is over the number of formats already set, the item will be ignored.
formatNumber | index of the subformat. | |
format | the format to be set. |
Gets an array of subformats of this object.
The returned array should not be deleted by the caller, nor should the pointers within the array. The array and its contents remain valid only until the next call to any method of this class is made with this object. See the class description about format numbering.
count | output parameter to receive the size of the array |
UnicodeString& MessageFormat::format | ( | const Formattable * | source, | |
int32_t | count, | |||
UnicodeString & | appendTo, | |||
FieldPosition & | ignore, | |||
UErrorCode & | status | |||
) | const |
Formats the given array of arguments into a user-readable string.
Does not take ownership of the Formattable* array or its contents.
source | An array of objects to be formatted. | |
count | The number of elements of 'source'. | |
appendTo | Output parameter to receive result. Result is appended to existing contents. | |
ignore | Not used; inherited from base class API. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
static UnicodeString& MessageFormat::format | ( | const UnicodeString & | pattern, | |
const Formattable * | arguments, | |||
int32_t | count, | |||
UnicodeString & | appendTo, | |||
UErrorCode & | status | |||
) | [static] |
Formats the given array of arguments into a user-readable string using the given pattern.
pattern | The pattern. | |
arguments | An array of objects to be formatted. | |
count | The number of elements of 'source'. | |
appendTo | Output parameter to receive result. Result is appended to existing contents. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
virtual UnicodeString& MessageFormat::format | ( | const Formattable & | obj, | |
UnicodeString & | appendTo, | |||
FieldPosition & | pos, | |||
UErrorCode & | status | |||
) | const [virtual] |
Formats the given array of arguments into a user-readable string.
The array must be stored within a single Formattable object of type kArray. If the Formattable object type is not of type kArray, then returns a failing UErrorCode.
obj | A Formattable of type kArray containing arguments to be formatted. | |
appendTo | Output parameter to receive result. Result is appended to existing contents. | |
pos | On input: an alignment field, if desired. On output: the offsets of the alignment field. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
Implements Format.
UnicodeString & MessageFormat::format | ( | const Formattable & | obj, | |
UnicodeString & | appendTo, | |||
UErrorCode & | status | |||
) | const [inline] |
Formats the given array of arguments into a user-readable string.
The array must be stored within a single Formattable object of type kArray. If the Formattable object type is not of type kArray, then returns a failing UErrorCode.
obj | The object to format | |
appendTo | Output parameter to receive result. Result is appended to existing contents. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
Reimplemented from Format.
Definition at line 818 of file msgfmt.h.
References Format::format().
virtual Formattable* MessageFormat::parse | ( | const UnicodeString & | source, | |
ParsePosition & | pos, | |||
int32_t & | count | |||
) | const [virtual] |
Parses the given string into an array of output arguments.
source | String to be parsed. | |
pos | On input, starting position for parse. On output, final position after parse. Unchanged if parse fails. | |
count | Output parameter to receive the number of arguments parsed. |
virtual Formattable* MessageFormat::parse | ( | const UnicodeString & | source, | |
int32_t & | count, | |||
UErrorCode & | status | |||
) | const [virtual] |
Parses the given string into an array of output arguments.
source | String to be parsed. | |
count | Output param to receive size of returned array. | |
status | Input/output error code. If the pattern cannot be parsed, set to failure code. |
virtual void MessageFormat::parseObject | ( | const UnicodeString & | source, | |
Formattable & | result, | |||
ParsePosition & | pos | |||
) | const [virtual] |
Parses the given string into an array of output arguments stored within a single Formattable of type kArray.
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. | |
pos | On input, starting position for parse. On output, final position after parse. Unchanged if parse fails. |
Implements Format.
static UnicodeString MessageFormat::autoQuoteApostrophe | ( | const UnicodeString & | pattern, | |
UErrorCode & | status | |||
) | [static] |
Convert an 'apostrophe-friendly' pattern into a standard pattern.
Standard patterns treat all apostrophes as quotes, which is problematic in some languages, e.g. French, where apostrophe is commonly used. This utility assumes that only an unpaired apostrophe immediately before a brace is a true quote. Other unpaired apostrophes are paired, and the resulting standard pattern string is returned.
Note it is not guaranteed that the returned pattern is indeed a valid pattern. The only effect is to convert between patterns having different quoting semantics.
pattern | the 'apostrophe-friendly' patttern to convert | |
status | Input/output error code. If the pattern cannot be parsed, the failure code is set. |
virtual UClassID MessageFormat::getDynamicClassID | ( | void | ) | const [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.
Implements Format.
static UClassID MessageFormat::getStaticClassID | ( | void | ) | [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()) ...