Logo Search packages:      
Sourcecode: icu version File versions

MessageFormat Class Reference

#include <msgfmt.h>

Inheritance diagram for MessageFormat:

Format

List of all members.


Detailed Description

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 = 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.
Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.

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 &lt;&lt; "format: " &lt;&lt; form->format(testArgs, 2, string, fpos, success ) &lt;&lt; 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).
     delete 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 :=   choiceFormatPattern
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.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 = 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.
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.

Definition at line 194 of file msgfmt.h.


Public Types

enum  EFormatNumber { kMaxFormat = 10 }

Public Member Functions

virtual void adoptFormat (int32_t formatNumber, Format *formatToAdopt)
virtual void adoptFormats (Format **formatsToAdopt, int32_t count)
virtual void applyPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
virtual void applyPattern (const UnicodeString &pattern, UErrorCode &status)
virtual Formatclone (void) const
UnicodeStringformat (const Formattable &obj, UnicodeString &result, UErrorCode &status) const
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &toAppendTo, FieldPosition &pos, UErrorCode &status) const
UnicodeStringformat (const Formattable *source, int32_t count, UnicodeString &result, FieldPosition &ignore, UErrorCode &success) const
virtual UClassID getDynamicClassID (void) const
virtual const Format ** getFormats (int32_t &count) const
const Formattable::TypegetFormatTypeList (int32_t &listCount)
virtual const Locale & getLocale (void) const
 MessageFormat (const MessageFormat &)
 MessageFormat (const UnicodeString &pattern, const Locale &newLocale, UParseError &parseError, UErrorCode &success)
 MessageFormat (const UnicodeString &pattern, const Locale &newLocale, UErrorCode &success)
 MessageFormat (const UnicodeString &pattern, UErrorCode &status)
UBool operator!= (const Format &other) const
const MessageFormatoperator= (const MessageFormat &)
virtual UBool operator== (const Format &other) const
virtual Formattableparse (const UnicodeString &source, int32_t &count, UErrorCode &status) const
virtual Formattableparse (const UnicodeString &source, ParsePosition &status, int32_t &count) const
void parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
virtual void parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const
virtual void setFormat (int32_t variable, const Format &newFormat)
virtual void setFormats (const Format **newFormats, int32_t cnt)
virtual void setLocale (const Locale &theLocale)
virtual UnicodeStringtoPattern (UnicodeString &result) const
virtual ~MessageFormat ()

Static Public Member Functions

static UnicodeStringformat (const UnicodeString &pattern, const Formattable *arguments, int32_t count, UnicodeString &result, UErrorCode &success)
static UClassID getStaticClassID (void)

Protected Member Functions

void syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)

Private Member Functions

NumberFormatcreateIntegerFormat (const Locale &locale, UErrorCode &status) const
UnicodeStringformat (const Formattable *arguments, int32_t cnt, UnicodeString &result, FieldPosition &status, int32_t recursionProtection, UErrorCode &success) const
int32_t makeFormat (int32_t offsetNumber, UnicodeString *segments, UParseError &parseError, UErrorCode &success)

Static Private Member Functions

static void copyAndFixQuotes (const UnicodeString &source, int32_t start, int32_t end, UnicodeString &target)
static int32_t findKeyword (const UnicodeString &s, const UChar *const *list)
static NumberFormatgetNumberFormat (UErrorCode &status)
static UnicodeStringitos (int32_t i, UnicodeString &string)
static void releaseNumberFormat (NumberFormat *adopt)
static int32_t stoi (const UnicodeString &string)

Private Attributes

int32_t * fArgumentNumbers
int32_t fCount
FormatfFormats [kMaxFormat]
Formattable::Type fFormatTypeList [kMaxFormat]
int32_t fListCount
Locale fLocale
int32_t fMaxOffset
int32_t * fOffsets
UnicodeString fPattern

Static Private Attributes

static const char fgClassID = 0

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index