class MessageFormat

Defined at line 345 of file ../../third_party/icu/latest/source/i18n/unicode/msgfmt.h

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 {

Public Methods

void 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. ICU 2.0

void 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. ICU 2.0

void 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. ICU 2.0

void MessageFormat (const MessageFormat & )

Constructs a new MessageFormat from an existing one.

ICU 2.0

const MessageFormat & operator= (const MessageFormat & )

Assignment operator.

ICU 2.0

void ~MessageFormat ()

Destructor.

ICU 2.0

MessageFormat * clone ()

Clones this Format object polymorphically. The caller owns the

result and should delete it when done.

ICU 2.0

bool operator== (const Format & other)

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.

ICU 2.0

void setLocale (const Locale & theLocale)

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

Parameters

theLocale the new locale value to be set. ICU 2.0

const Locale & getLocale ()

Gets the locale used for creating argument Format objects.

format information.

Returns

the locale of the object.

ICU 2.0

void applyPattern (const UnicodeString & pattern, UErrorCode & status)

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. ICU 2.0

void applyPattern (const UnicodeString & pattern, UParseError & parseError, UErrorCode & status)

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. ICU 2.0

void applyPattern (const UnicodeString & pattern, UMessagePatternApostropheMode aposMode, UParseError * parseError, UErrorCode & status)

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. ICU 4.8

UMessagePatternApostropheMode getApostropheMode ()

Returns

this instance's UMessagePatternApostropheMode.

ICU 4.8

Defined at line 500 of file ../../third_party/icu/latest/source/i18n/unicode/msgfmt.h

UnicodeString & toPattern (UnicodeString & appendTo)

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.

ICU 2.0

void adoptFormats (Format ** formatsToAdopt, int32_t count)

Sets subformats.

See the class description about format numbering.

The caller should not delete the Format objects after this call.

<EM

>The array formatsToAdopt is not itself adopted.

</EM

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

ICU 2.0

Parameters

formatsToAdopt the format to be adopted.

count the size of the array.

void setFormats (const Format ** newFormats, int32_t cnt)

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.

ICU 2.0

Parameters

newFormats the new format to be set.

cnt the size of the array.

void adoptFormat (int32_t formatNumber, Format * formatToAdopt)

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.

ICU 2.0

Parameters

formatNumber index of the subformat.

formatToAdopt the format to be adopted.

void setFormat (int32_t formatNumber, const Format & format)

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. ICU 2.0

StringEnumeration * getFormatNames (UErrorCode & status)

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. ICU 4.0

Format * getFormat (const UnicodeString & formatName, UErrorCode & status)

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. ICU 4.0

void setFormat (const UnicodeString & formatName, const Format & format, UErrorCode & status)

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. ICU 4.0

void adoptFormat (const UnicodeString & formatName, Format * formatToAdopt, UErrorCode & status)

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. ICU 4.0

const Format ** getFormats (int32_t & count)

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.

ICU 2.0

UnicodeString & format (const Formattable * source, int32_t count, UnicodeString & appendTo, FieldPosition & ignore, UErrorCode & status)

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.

ICU 2.0

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.

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.

ICU 2.0

UnicodeString & format (const Formattable & obj, UnicodeString & appendTo, FieldPosition & pos, UErrorCode & status)

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.

ICU 2.0

UnicodeString & format (const UnicodeString * argumentNames, const Formattable * arguments, int32_t count, UnicodeString & appendTo, UErrorCode & status)

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.

ICU 4.0

Formattable * parse (const UnicodeString & source, ParsePosition & pos, int32_t & count)

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.

ICU 2.0

Formattable * parse (const UnicodeString & source, int32_t & count, UErrorCode & status)

Parses the given string into an array of output arguments.

If this format uses named arguments, status is set to

U_ARGUMENT_TYPE_MISMATCH.

ICU 2.0

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.

void parseObject (const UnicodeString & source, Formattable & result, ParsePosition & pos)

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. ICU 2.0

UnicodeString autoQuoteApostrophe (const UnicodeString & pattern, UErrorCode & status)

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

ICU 3.4

UBool usesNamedArguments ()

Returns true if this MessageFormat uses named arguments,

and false otherwise. See class description.

Returns

true if named arguments are used.

ICU 4.0

int32_t getArgTypeCount ()

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

UClassID getDynamicClassID ()

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.

ICU 2.0

UClassID getStaticClassID ()

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.

ICU 2.0

UBool equalFormats (const void * left, const void * right)

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

Enumerations

enum EFormatNumber

Name	Value
kMaxFormat	10

Enum type for kMaxFormat.

ICU 3.0. The 10-argument limit was removed as of ICU 2.6,

rendering this enum type obsolete.

Defined at line 353 of file ../../third_party/icu/latest/source/i18n/unicode/msgfmt.h

Friends

class MessageFormatAdapter