Loading...
Searching...
No Matches
icu::MessageFormat Class Reference

`#include <msgfmt.h>`

Inheritance diagram for icu::MessageFormat:

## Public Types

enum | EFormatNumber { kMaxFormat = 10 }
| Enum type for kMaxFormat. More...

## Public Member Functions

U_I18N_API | MessageFormat (const UnicodeString &pattern, UErrorCode &status)
| Constructs a new MessageFormat using the given pattern and the default locale.
U_I18N_API | MessageFormat (const UnicodeString &pattern, const Locale &newLocale, UErrorCode &status)
| Constructs a new MessageFormat using the given pattern and locale.
U_I18N_API | MessageFormat (const UnicodeString &pattern, const Locale &newLocale, UParseError &parseError, UErrorCode &status)
| Constructs a new MessageFormat using the given pattern and locale.
U_I18N_API | MessageFormat (const MessageFormat &)
| Constructs a new MessageFormat from an existing one.
U_I18N_API const MessageFormat & | operator= (const MessageFormat &)
| Assignment operator.
virtual U_I18N_API | ~MessageFormat ()
| Destructor.
virtual U_I18N_API MessageFormat * | clone () const override
| Clones this Format object polymorphically.
virtual U_I18N_API bool | operator== (const Format &other) const override
| Returns true if the given Format objects are semantically equal.
virtual U_I18N_API void | setLocale (const Locale &theLocale)
| Sets the locale to be used for creating argument Format objects.
virtual U_I18N_API const Locale & | getLocale () const
| Gets the locale used for creating argument Format objects.
virtual U_I18N_API void | applyPattern (const UnicodeString &pattern, UErrorCode &status)
| Applies the given pattern string to this message format.
virtual U_I18N_API void | applyPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
| Applies the given pattern string to this message format.
virtual U_I18N_API void | applyPattern (const UnicodeString &pattern, UMessagePatternApostropheMode aposMode, UParseError *parseError, UErrorCode &status)
| Sets the UMessagePatternApostropheMode and the pattern used by this message format.
U_I18N_API UMessagePatternApostropheMode | getApostropheMode () const
virtual U_I18N_API UnicodeString & | toPattern (UnicodeString &appendTo) const
| Returns a pattern that can be used to recreate this object.
virtual U_I18N_API void | adoptFormats (Format **formatsToAdopt, int32_t count)
| Sets subformats.
virtual U_I18N_API void | setFormats (const Format **newFormats, int32_t cnt)
| Sets subformats.
virtual U_I18N_API void | adoptFormat (int32_t formatNumber, Format *formatToAdopt)
| Sets one subformat.
virtual U_I18N_API void | setFormat (int32_t formatNumber, const Format &format)
| Sets one subformat.
virtual U_I18N_API StringEnumeration * | getFormatNames (UErrorCode &status)
| Gets format names.
virtual U_I18N_API Format * | getFormat (const UnicodeString &formatName, UErrorCode &status)
| Gets subformat pointer for given format name.
virtual U_I18N_API void | setFormat (const UnicodeString &formatName, const Format &format, UErrorCode &status)
| Sets one subformat for given format name.
virtual U_I18N_API void | adoptFormat (const UnicodeString &formatName, Format *formatToAdopt, UErrorCode &status)
| Sets one subformat for given format name.
virtual U_I18N_API const Format ** | getFormats (int32_t &count) const
| Gets an array of subformats of this object.
U_I18N_API 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 U_I18N_API UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const override
| Formats the given array of arguments into a user-readable string.
U_I18N_API UnicodeString & | format (const UnicodeString *argumentNames, const Formattable *arguments, int32_t count, UnicodeString &appendTo, UErrorCode &status) const
| Formats the given array of arguments into a user-defined argument name array.
virtual U_I18N_API Formattable * | parse (const UnicodeString &source, ParsePosition &pos, int32_t &count) const
| Parses the given string into an array of output arguments.
virtual U_I18N_API Formattable * | parse (const UnicodeString &source, int32_t &count, UErrorCode &status) const
| Parses the given string into an array of output arguments.
virtual U_I18N_API void | parseObject (const UnicodeString &source, Formattable &result, ParsePosition &pos) const override
| Parses the given string into an array of output arguments stored within a single Formattable of type kArray.
U_I18N_API UBool | usesNamedArguments () const
| Returns true if this MessageFormat uses named arguments, and false otherwise.
U_I18N_API int32_t | getArgTypeCount () const
| This API is for ICU internal use only.
virtual U_I18N_API UClassID | getDynamicClassID () const override
| Returns a unique class ID POLYMORPHICALLY.
U_I18N_API UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Formats an object to produce a string.
virtual U_I18N_API UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format an object to produce a string.
Public Member Functions inherited from icu::Format
virtual U_I18N_API | ~Format ()
| Destructor.
U_I18N_API bool | operator!= (const Format &other) const
| Return true if the given Format objects are not semantically equal.
U_I18N_API UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Formats an object to produce a string.
U_I18N_API void | parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
| Parses a string to produce an object.
U_I18N_API Locale | getLocale (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object.
U_I18N_API const char * | getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object.
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.

## Static Public Member Functions

static U_I18N_API 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 U_I18N_API UnicodeString | autoQuoteApostrophe (const UnicodeString &pattern, UErrorCode &status)
| Convert an 'apostrophe-friendly' pattern into a standard pattern.
static U_I18N_API UClassID | getStaticClassID ()
| Return the class ID for this class.
static U_I18N_API UBool | equalFormats (const void *left, const void *right)
| Compares two Format objects.

## Friends

class | MessageFormatAdapter

## Additional Inherited Members

Protected Member Functions inherited from icu::Format
U_I18N_API void | setLocaleIDs (const char *valid, const char *actual)
U_I18N_API | Format ()
| Default constructor for subclass use only.
U_I18N_API | Format (const Format &)
U_I18N_API Format & | operator= (const Format &)
Static Protected Member Functions inherited from icu::Format
static U_I18N_API void | syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)
| Simple function for initializing a UParseError from a UnicodeString.

## Detailed Description

MessageFormat prepares strings for display to users, with optional arguments (variables/placeholders). The arguments can occur in any order, which is necessary for translation into languages with different grammars.

A MessageFormat is constructed from a pattern string with arguments in {curly braces} which will be replaced by formatted values.

`MessageFormat` differs from the other `Format` classes in that you create a `MessageFormat` object with one of its constructors (not with a `createInstance` style factory method). Factory methods aren't necessary because `MessageFormat` itself doesn't implement locale-specific behavior. Any locale-specific behavior is defined by the pattern that you provide and the subformats used for inserted arguments.

Arguments can be named (using identifiers) or numbered (using small ASCII-digit integers). Some of the API methods work only with argument numbers and throw an exception if the pattern has named arguments (see `usesNamedArguments()`).

An argument might not specify any format type. In this case, a numeric value is formatted with a default (for the locale) NumberFormat, and a date/time value is formatted with a default (for the locale) DateFormat.

An argument might specify a "simple" type for which the specified Format object is created, cached and used.

An argument might have a "complex" type with nested MessageFormat sub-patterns. During formatting, one of these sub-messages is selected according to the argument value and recursively formatted.

After construction, a custom Format object can be set for a top-level argument, overriding the default formatting and parsing behavior for that argument. However, custom formatting can be achieved more simply by writing a typeless argument in the pattern string and supplying it with a preformatted string value.

When formatting, MessageFormat takes a collection of argument values and writes an output string. The argument values may be passed as an array (when the pattern contains only numbered arguments) or as an array of names and and an array of arguments (which works for both named and numbered arguments).

Each argument is matched with one of the input values by array index or argument name and formatted according to its pattern specification (or using a custom Format object if one was set). A numbered pattern argument is matched with an argument name that contains that number as an ASCII-decimal-digit string (without leading zero).

#### Patterns and Their Interpretation

`MessageFormat` uses patterns of the following form:

    message = messageText (argument messageText)*
    argument = noneArg | simpleArg | complexArg
    complexArg = choiceArg | pluralArg | selectArg | selectordinalArg

    noneArg = '{' argNameOrNumber '}'
    simpleArg = '{' argNameOrNumber ',' argType [',' argStyle] '}'
    choiceArg = '{' argNameOrNumber ',' "choice" ',' choiceStyle '}'
    pluralArg = '{' argNameOrNumber ',' "plural" ',' pluralStyle '}'
    selectArg = '{' argNameOrNumber ',' "select" ',' selectStyle '}'
    selectordinalArg = '{' argNameOrNumber ',' "selectordinal" ',' pluralStyle '}'

    choiceStyle: see ChoiceFormat pluralStyle: see PluralFormat selectStyle: see SelectFormat argNameOrNumber = argName | argNumber argName = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+ argNumber = '0' | ('1'..'9' ('0'..'9')*) argType = "number" | "date" | "time" | "spellout" | "ordinal" | "duration" argStyle = "short" | "medium" | "long" | "full" | "integer" | "currency" | "percent" | argStyleText | "::" argSkeletonText

- messageText can contain quoted literal strings including syntax characters. A quoted literal string begins with an ASCII apostrophe and a syntax character (usually a {curly brace}) and continues until the next single apostrophe. A double ASCII apostrophe inside or outside of a quoted string represents one literal apostrophe.
- Quotable syntax characters are the {curly braces} in all messageText parts, plus the '#' sign in a messageText immediately inside a pluralStyle, and the '|' symbol in a messageText immediately inside a choiceStyle.
- See also `UMessagePatternApostropheMode`
- In argStyleText, every single ASCII apostrophe begins and ends quoted literal text, and unquoted {curly braces} must occur in matched pairs.

Recommendation: Use the real apostrophe (single quote) character ’ (U+2019) for human-readable text, and use the ASCII apostrophe ' (U+0027) only in program syntax, like quoting in MessageFormat. See the annotations for U+0027 Apostrophe in The Unicode Standard.

The `choice` argument type is deprecated. Use `plural` arguments for proper plural selection, and `select` arguments for simple selection among a fixed set of choices.

The `argType` and `argStyle` values are used to create a `Format` instance for the format element. The following table shows how the values map to Format instances. Combinations not shown in the table are illegal. Any `argStyleText` must be a valid pattern string for the Format subclass used.

argType | argStyle | resulting Format object
--- | --- | ---
(none) | `null`
`number` | (none) | `NumberFormat.createInstance(getLocale(), status)`
`integer` | `NumberFormat.createInstance(getLocale(), kNumberStyle, status)`
`currency` | `NumberFormat.createCurrencyInstance(getLocale(), status)`
`percent` | `NumberFormat.createPercentInstance(getLocale(), status)`
argStyleText | `new DecimalFormat(argStyleText, new DecimalFormatSymbols(getLocale(), status), status)`
argSkeletonText | `NumberFormatter::forSkeleton(argSkeletonText, status).locale(getLocale()).toFormat(status)`
`date` | (none) | `DateFormat.createDateInstance(kDefault, getLocale(), status)`
`short` | `DateFormat.createDateInstance(kShort, getLocale(), status)`
`medium` | `DateFormat.createDateInstance(kDefault, getLocale(), status)`
`long` | `DateFormat.createDateInstance(kLong, getLocale(), status)`
`full` | `DateFormat.createDateInstance(kFull, getLocale(), status)`
argStyleText | `new SimpleDateFormat(argStyleText, getLocale(), status)`
argSkeletonText | `DateFormat::createInstanceForSkeleton(argSkeletonText, getLocale(), status)`
`time` | (none) | `DateFormat.createTimeInstance(kDefault, getLocale(), status)`
`short` | `DateFormat.createTimeInstance(kShort, getLocale(), status)`
`medium` | `DateFormat.createTimeInstance(kDefault, getLocale(), status)`
`long` | `DateFormat.createTimeInstance(kLong, getLocale(), status)`
`full` | `DateFormat.createTimeInstance(kFull, getLocale(), status)`
argStyleText | `new SimpleDateFormat(argStyleText, getLocale(), status)`
`spellout` | argStyleText (optional) | `new RuleBasedNumberFormat(URBNF_SPELLOUT, getLocale(), status) .setDefaultRuleset(argStyleText, status);`
`ordinal` | argStyleText (optional) | `new RuleBasedNumberFormat(URBNF_ORDINAL, getLocale(), status) .setDefaultRuleset(argStyleText, status);`
`duration` | argStyleText (optional) | `new RuleBasedNumberFormat(URBNF_DURATION, getLocale(), status) .setDefaultRuleset(argStyleText, status);`

#### Argument formatting

Arguments are formatted according to their type, using the default ICU formatters for those types, unless otherwise specified.

There are also several ways to control the formatting.

We recommend you use default styles, predefined style values, skeletons, or preformatted values, but not pattern strings or custom format objects.

For more details, see the ICU User Guide.

#### Usage Information

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,::jmm} on {1,date,::dMMMM}, there was {2} on planet {0,number}.",
         arguments, 3, result, success );

    cout << "result: " << result << endl;
    //<output>: At 4:34 PM on March 23, there was a disturbance
    //             in the Force on planet 7.
    icu::FormattableFormattable objects can be passed to the Format class or its subclasses for formatting.Definition fmtable.h:63
    icu::GregorianCalendarConcrete class which provides the standard calendar used by most of the world.Definition gregocal.h:153
    icu::MessageFormat::formatU_I18N_API UnicodeString & format(const Formattable *source, int32_t count, UnicodeString &appendTo, FieldPosition &ignore, UErrorCode &status) constFormats the given array of arguments into a user-readable string.
    icu::UnicodeStringUnicodeString is a string class that stores Unicode characters directly and provides similar function...Definition unistr.h:303
    UErrorCodeUErrorCodeStandard ICU4C error code type, a substitute for exceptions.Definition utypes.h:509
    U_ZERO_ERROR@ U_ZERO_ERRORNo error, no warning.Definition utypes.h:544

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(
        "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).
    icu::FieldPositionFieldPosition is a simple class used by Format and its subclasses to identify fields in formatted out...Definition fieldpos.h:110
    icu::MessageFormatDefinition msgfmt.h:345

For messages that include plural forms, you can use a plural argument:

    success = U_ZERO_ERROR;
    MessageFormat msgFmt(
         "{num_files, plural, "
         "=0{There are no files on disk \"{disk_name}\".}"
         "=1{There is one file on disk \"{disk_name}\".}"
         "other{There are # files on disk \"{disk_name}\".}}",
        Locale("en"),
        success);
    FieldPosition fpos = 0;
    Formattable testArgs[] = {0L, "MyDisk"};
    UnicodeString testArgsNames[] = {"num_files", "disk_name"};
    UnicodeString result;
    cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);
    testArgs[0] = 3L;
    cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);
    icu::LocaleA Locale object represents a specific geographical, political, or cultural region.Definition locid.h:198
    icu::MessageFormat::MessageFormatU_I18N_API MessageFormat(const UnicodeString &pattern, UErrorCode &status)Constructs a new MessageFormat using the given pattern and the default locale.

    output:
    There are no files on disk "MyDisk".
    There are 3 files on "MyDisk".

See `PluralFormat` and `PluralRules` for details.

#### Synchronization

MessageFormats are not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.

Stable
  ICU 2.0

Definition at line 345 of file msgfmt.h.

## Member Enumeration Documentation

## EFormatNumber

enum icu::MessageFormat::EFormatNumber

Enum type for kMaxFormat.

Obsolete
  ICU 3.0. The 10-argument limit was removed as of ICU 2.6, rendering this enum type obsolete.

Enumerator

kMaxFormat

The maximum number of arguments.

Obsolete
  ICU 3.0. The 10-argument limit was removed as of ICU 2.6, rendering this constant obsolete.

Definition at line 353 of file msgfmt.h.

## Constructor & Destructor Documentation

## MessageFormat() [1/4]

U_I18N_API icu::MessageFormat::MessageFormat | ( | const UnicodeString & | pattern,
|  | UErrorCode & | status )

Constructs a new MessageFormat using the given pattern and the default locale.

Parameters

  pattern | Pattern used to construct object.
  status | Input/output error code. If the pattern cannot be parsed, set to failure code.

Stable
  ICU 2.0

References U_I18N_API.

Referenced by clone(), equalFormats(), MessageFormat(), and operator=().

## MessageFormat() [2/4]

U_I18N_API icu::MessageFormat::MessageFormat | ( | const UnicodeString & | pattern,
|  | const Locale & | newLocale,
|  | UErrorCode & | status )

Constructs a new MessageFormat using the given pattern and locale.

Parameters

  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.

Stable
  ICU 2.0

References U_I18N_API.

## MessageFormat() [3/4]

U_I18N_API icu::MessageFormat::MessageFormat | ( | const UnicodeString & | pattern,
|  | const Locale & | newLocale,
|  | UParseError & | parseError,
|  | UErrorCode & | status )

Constructs a new MessageFormat using the given pattern and locale.

Parameters

  pattern | Pattern used to construct object.
  newLocale | The locale to use for formatting dates and numbers.
  parseError | Struct to receive information on the position of an error within the pattern.
  status | Input/output error code. If the pattern cannot be parsed, set to failure code.

Stable
  ICU 2.0

References U_I18N_API.

## MessageFormat() [4/4]

U_I18N_API icu::MessageFormat::MessageFormat | ( | const MessageFormat & |  | ) |

Constructs a new MessageFormat from an existing one.

Stable
  ICU 2.0

References MessageFormat(), and U_I18N_API.

## ~MessageFormat()

virtual U_I18N_API icu::MessageFormat::~MessageFormat | ( |  | ) |

virtual

Destructor.

Stable
  ICU 2.0

References U_I18N_API.

## Member Function Documentation

## adoptFormat() [1/2]

virtual U_I18N_API void icu::MessageFormat::adoptFormat | ( | const UnicodeString & | formatName,
|  | Format * | formatToAdopt,
|  | UErrorCode & | status )

virtual

Sets one subformat for given format name.

See the class description about format name. This function supports both named and numbered arguments– if numbered, the formatName is the corresponding UnicodeStrings (e.g. "0", "1", "2"...). If there is no matched formatName or wrong type, the item will be ignored. The caller should not delete the Format object after this call.

Parameters

  formatName | Name of the subformat.
  formatToAdopt | Format to be adopted.
  status | output param set to success/failure code.

Stable
  ICU 4.0

References icu::Format::Format(), and U_I18N_API.

## adoptFormat() [2/2]

virtual U_I18N_API void icu::MessageFormat::adoptFormat | ( | int32_t | formatNumber,
|  | Format * | formatToAdopt )

virtual

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.

If this format uses named arguments, the new format is discarded and this format remains unchanged.

Stable
  ICU 2.0

Parameters

  formatNumber | index of the subformat.
  formatToAdopt | the format to be adopted.

References icu::Format::Format(), and U_I18N_API.

## adoptFormats()

virtual U_I18N_API void icu::MessageFormat::adoptFormats | ( | Format ** | formatsToAdopt,
|  | int32_t | count )

virtual

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.

If this format uses named arguments, the new formats are discarded and this format remains unchanged.

Stable
  ICU 2.0

Parameters

  formatsToAdopt | the format to be adopted.
  count | the size of the array.

References icu::Format::Format(), and U_I18N_API.

## applyPattern() [1/3]

virtual U_I18N_API void icu::MessageFormat::applyPattern | ( | const UnicodeString & | pattern,
|  | UErrorCode & | status )

virtual

Applies the given pattern string to this message format.

Parameters

  pattern | The pattern to be applied.
  status | Input/output error code. If the pattern cannot be parsed, set to failure code.

Stable
  ICU 2.0

References U_I18N_API.

## applyPattern() [2/3]

virtual U_I18N_API void icu::MessageFormat::applyPattern | ( | const UnicodeString & | pattern,
|  | UMessagePatternApostropheMode | aposMode,
|  | UParseError * | parseError,
|  | UErrorCode & | status )

virtual

Sets the UMessagePatternApostropheMode and the pattern used by this message format.

Parses the pattern and caches Format objects for simple argument types. Patterns and their interpretation are specified in the class description.

This method is best used only once on a given object to avoid confusion about the mode, and after constructing the object with an empty pattern string to minimize overhead.

Parameters

  pattern | The pattern to be applied.
  aposMode | The new apostrophe mode.
  parseError | Struct to receive information on the position of an error within the pattern. Can be nullptr.
  status | Input/output error code. If the pattern cannot be parsed, set to failure code.

Stable
  ICU 4.8

References U_I18N_API.

## applyPattern() [3/3]

virtual U_I18N_API void icu::MessageFormat::applyPattern | ( | const UnicodeString & | pattern,
|  | UParseError & | parseError,
|  | UErrorCode & | status )

virtual

Applies the given pattern string to this message format.

Parameters

  pattern | The pattern to be applied.
  parseError | Struct to receive information on the position of an error within the pattern.
  status | Input/output error code. If the pattern cannot be parsed, set to failure code.

Stable
  ICU 2.0

References U_I18N_API.

## autoQuoteApostrophe()

U_I18N_API UnicodeString icu::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.

Parameters

  pattern | the 'apostrophe-friendly' patttern to convert
  status | Input/output error code. If the pattern cannot be parsed, the failure code is set.

Returns
  the standard equivalent of the original pattern

Stable
  ICU 3.4

References U_I18N_API.

## clone()

virtual U_I18N_API MessageFormat * icu::MessageFormat::clone | ( |  | ) | const

override virtual

Clones this Format object polymorphically.

The caller owns the result and should delete it when done.

Stable
  ICU 2.0

Implements icu::Format.

References MessageFormat(), and U_I18N_API.

## equalFormats()

U_I18N_API UBool icu::MessageFormat::equalFormats | ( | const void * | left,
|  | const void * | right )

static

Compares two Format objects.

This is used for constructing the hash tables.

Parameters

  left | pointer to a Format object. Must not be nullptr.
  right | pointer to a Format object. Must not be nullptr.

Returns
  whether the two objects are the same

Internal
  Do not use. This API is for internal use only.

References icu::Format::Format(), MessageFormat(), and U_I18N_API.

## format() [1/6]

virtual U_I18N_API UnicodeString & icu::MessageFormat::format | ( | const Formattable & | obj,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status ) const

override 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.

If this format uses named arguments, appendTo is unchanged and status is set to U_ILLEGAL_ARGUMENT_ERROR.

Parameters

  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.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 2.0

Implements icu::Format.

References U_I18N_API.

## format() [2/6]

virtual U_I18N_API UnicodeString & icu::Format::format | ( | const Formattable & | obj,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status ) const

virtual

Format an object to produce a string.

Subclasses should override this method. This method allows polymorphic formatting of Formattable objects. If a subclass of Format receives a Formattable object type it doesn't handle (e.g., if a numeric Formattable is passed to a DateFormat object) then it returns a failing UErrorCode.

Parameters

  obj | The object to format.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  posIter | On return, can be used to iterate over positions of fields generated by this format call.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 4.4

Reimplemented from icu::Format.

## format() [3/6]

U_I18N_API UnicodeString & icu::Format::format | ( | const Formattable & | obj,
|  | UnicodeString & | appendTo,
|  | UErrorCode & | status ) const

Formats an object to produce a string.

Parameters

  obj | The object to format.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  status | Output parameter filled in with success or failure status.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 2.0

## format() [4/6]

U_I18N_API UnicodeString & icu::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.

If this format uses named arguments, appendTo is unchanged and status is set to U_ILLEGAL_ARGUMENT_ERROR.

Parameters

  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.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 2.0

References U_I18N_API.

Referenced by setFormat(), and setFormat().

## format() [5/6]

U_I18N_API UnicodeString & icu::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.

If this format uses named arguments, appendTo is unchanged and status is set to U_ILLEGAL_ARGUMENT_ERROR.

Parameters

  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.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 2.0

References U_I18N_API.

## format() [6/6]

U_I18N_API UnicodeString & icu::MessageFormat::format | ( | const UnicodeString * | argumentNames,
|  | const Formattable * | arguments,
|  | int32_t | count,
|  | UnicodeString & | appendTo,
|  | UErrorCode & | status ) const

Formats the given array of arguments into a user-defined argument name array.

This function supports both named and numbered arguments– if numbered, the formatName is the corresponding UnicodeStrings (e.g. "0", "1", "2"...).

Parameters

  argumentNames | argument name array
  arguments | An array of objects to be formatted.
  count | The number of elements of 'argumentNames' and arguments. The number of argumentNames and arguments must be the same.
  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.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 4.0

References U_I18N_API.

## getApostropheMode()

U_I18N_API UMessagePatternApostropheMode icu::MessageFormat::getApostropheMode | ( |  | ) | const

inline

Returns
  this instance's UMessagePatternApostropheMode.

Stable
  ICU 4.8

Definition at line 496 of file msgfmt.h.

References U_I18N_API.

## getArgTypeCount()

U_I18N_API int32_t icu::MessageFormat::getArgTypeCount | ( |  | ) | const

This API is for ICU internal use only.

Please do not use it.

Returns argument types count in the parsed pattern. Used to distinguish pattern "{0} d" and "d".

Returns
  The number of formattable types in the pattern

Internal
  Do not use. This API is for internal use only.

References U_I18N_API.

## getDynamicClassID()

virtual U_I18N_API UClassID icu::MessageFormat::getDynamicClassID | ( |  | ) | const

override 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.

Returns
  The class ID for this object. All objects of a given class have the same class ID. Objects of other classes have different class IDs.

Stable
  ICU 2.0

Reimplemented from icu::UObject.

References U_I18N_API.

## getFormat()

virtual U_I18N_API Format * icu::MessageFormat::getFormat | ( | const UnicodeString & | formatName,
|  | UErrorCode & | status )

virtual

Gets subformat pointer for given format name.

This function supports both named and numbered arguments. If numbered, the formatName is the corresponding UnicodeStrings (e.g. "0", "1", "2"...). The returned Format object should not be deleted by the caller, nor should the pointer of other object . The pointer and its contents remain valid only until the next call to any method of this class is made with this object.

Parameters

  formatName | the name or number specifying a format
  status | output param set to success/failure code.

Stable
  ICU 4.0

References icu::Format::Format(), and U_I18N_API.

## getFormatNames()

virtual U_I18N_API StringEnumeration * icu::MessageFormat::getFormatNames | ( | UErrorCode & | status | ) |

virtual

Gets format names.

This function returns formatNames in StringEnumerations which can be used with getFormat() and setFormat() to export formattable array from current MessageFormat to another. It is the caller's responsibility to delete the returned formatNames.

Parameters

  status | output param set to success/failure code.

Stable
  ICU 4.0

References U_I18N_API.

## getFormats()

virtual U_I18N_API const Format ** icu::MessageFormat::getFormats | ( | int32_t & | count | ) | const

virtual

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 this format. See the class description about format numbering.

Parameters

  count | output parameter to receive the size of the array

Returns
  an array of count Format* objects, or nullptr if out of memory. Any or all of the array elements may be nullptr.

Stable
  ICU 2.0

References icu::Format::Format(), icu::Format::format(), and U_I18N_API.

## getLocale()

virtual U_I18N_API const Locale & icu::MessageFormat::getLocale | ( |  | ) | const

virtual

Gets the locale used for creating argument Format objects.

format information.

Returns
  the locale of the object.

Stable
  ICU 2.0

References U_I18N_API.

## getStaticClassID()

U_I18N_API UClassID icu::MessageFormat::getStaticClassID | ( |  | ) |

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()) ...

Returns
  The class ID for all objects of this class.

Stable
  ICU 2.0

References U_I18N_API.

## operator=()

U_I18N_API const MessageFormat & icu::MessageFormat::operator= | ( | const MessageFormat & |  | ) |

Assignment operator.

Stable
  ICU 2.0

References MessageFormat(), and U_I18N_API.

## operator==()

virtual U_I18N_API bool icu::MessageFormat::operator== | ( | const Format & | other | ) | const

override virtual

Returns true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Parameters

  other | the object to be compared with.

Returns
  true if the given Format objects are semantically equal.

Stable
  ICU 2.0

Implements icu::Format.

References icu::Format::Format(), and U_I18N_API.

## parse() [1/2]

virtual U_I18N_API Formattable * icu::MessageFormat::parse | ( | const UnicodeString & | source,
|  | int32_t & | count,
|  | UErrorCode & | status ) const

virtual

Parses the given string into an array of output arguments.

If this format uses named arguments, status is set to U_ARGUMENT_TYPE_MISMATCH.

Parameters

  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.

Returns
  an array of parsed arguments. The caller owns both the array and its contents. Returns nullptr if status is not U_ZERO_ERROR.

Stable
  ICU 2.0

References U_I18N_API.

## parse() [2/2]

virtual U_I18N_API Formattable * icu::MessageFormat::parse | ( | const UnicodeString & | source,
|  | ParsePosition & | pos,
|  | int32_t & | count ) const

virtual

Parses the given string into an array of output arguments.

Parameters

  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.

Returns
  an array of parsed arguments. The caller owns both the array and its contents.

Stable
  ICU 2.0

References U_I18N_API.

## parseObject()

virtual U_I18N_API void icu::MessageFormat::parseObject | ( | const UnicodeString & | source,
|  | Formattable & | result,
|  | ParsePosition & | pos ) const

override virtual

Parses the given string into an array of output arguments stored within a single Formattable of type kArray.

Parameters

  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.

Stable
  ICU 2.0

Implements icu::Format.

References U_I18N_API.

## setFormat() [1/2]

virtual U_I18N_API void icu::MessageFormat::setFormat | ( | const UnicodeString & | formatName,
|  | const Format & | format,
|  | UErrorCode & | status )

virtual

Sets one subformat for given format name.

See the class description about format name. This function supports both named and numbered arguments– if numbered, the formatName is the corresponding UnicodeStrings (e.g. "0", "1", "2"...). If there is no matched formatName or wrong type, the item will be ignored.

Parameters

  formatName | Name of the subformat.
  format | the format to be set.
  status | output param set to success/failure code.

Stable
  ICU 4.0

References icu::Format::Format(), format(), and U_I18N_API.

## setFormat() [2/2]

virtual U_I18N_API void icu::MessageFormat::setFormat | ( | int32_t | formatNumber,
|  | const Format & | format )

virtual

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.

Parameters

  formatNumber | index of the subformat.
  format | the format to be set.

Stable
  ICU 2.0

References icu::Format::Format(), format(), and U_I18N_API.

## setFormats()

virtual U_I18N_API void icu::MessageFormat::setFormats | ( | const Format ** | newFormats,
|  | int32_t | cnt )

virtual

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.

If this format uses named arguments, the new formats are discarded and this format remains unchanged.

Stable
  ICU 2.0

Parameters

  newFormats | the new format to be set.
  cnt | the size of the array.

References icu::Format::Format(), and U_I18N_API.

## setLocale()

virtual U_I18N_API void icu::MessageFormat::setLocale | ( | const Locale & | theLocale | ) |

virtual

Sets the locale to be used for creating argument Format objects.

Parameters

  theLocale | the new locale value to be set.

Stable
  ICU 2.0

References U_I18N_API.

## toPattern()

virtual U_I18N_API UnicodeString & icu::MessageFormat::toPattern | ( | UnicodeString & | appendTo | ) | const

virtual

Returns a pattern that can be used to recreate this object.

Parameters

  appendTo | Output parameter to receive the pattern. Result is appended to existing contents.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 2.0

References U_I18N_API.

## usesNamedArguments()

U_I18N_API UBool icu::MessageFormat::usesNamedArguments | ( |  | ) | const

Returns true if this MessageFormat uses named arguments, and false otherwise.

See class description.

Returns
  true if named arguments are used.

Stable
  ICU 4.0

References U_I18N_API.

## Friends And Related Symbol Documentation

## MessageFormatAdapter

friend class MessageFormatAdapter

friend

Definition at line 1102 of file msgfmt.h.

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

- i18n/unicode/msgfmt.h