class MessagePattern

Defined at line 362 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

Parses and represents ICU MessageFormat patterns.

Also handles patterns for ChoiceFormat, PluralFormat and SelectFormat.

Used in the implementations of those classes as well as in tools

for message validation, translation and format conversion.

The parser handles all syntax relevant for identifying message arguments.

This includes "complex" arguments whose style strings contain

nested MessageFormat pattern substrings.

For "simple" arguments (with no nested MessageFormat pattern substrings),

the argument style is not parsed any further.

The parser handles named and numbered message arguments and allows both in one message.

Once a pattern has been parsed successfully, iterate through the parsed data

with countParts(), getPart() and related methods.

The data logically represents a parse tree, but is stored and accessed

as a list of "parts" for fast and simple parsing and to minimize object allocations.

Arguments and nested messages are best handled via recursion.

For every _START "part", MessagePattern.getLimitPartIndex() efficiently returns

the index of the corresponding _LIMIT "part".

List of "parts":

message = MSG_START (SKIP_SYNTAX | INSERT_CHAR | REPLACE_NUMBER | argument)* MSG_LIMIT

argument = noneArg | simpleArg | complexArg

complexArg = choiceArg | pluralArg | selectArg

noneArg = ARG_START.NONE (ARG_NAME | ARG_NUMBER) ARG_LIMIT.NONE

simpleArg = ARG_START.SIMPLE (ARG_NAME | ARG_NUMBER) ARG_TYPE [ARG_STYLE] ARG_LIMIT.SIMPLE

choiceArg = ARG_START.CHOICE (ARG_NAME | ARG_NUMBER) choiceStyle ARG_LIMIT.CHOICE

pluralArg = ARG_START.PLURAL (ARG_NAME | ARG_NUMBER) pluralStyle ARG_LIMIT.PLURAL

selectArg = ARG_START.SELECT (ARG_NAME | ARG_NUMBER) selectStyle ARG_LIMIT.SELECT

choiceStyle = ((ARG_INT | ARG_DOUBLE) ARG_SELECTOR message)+

pluralStyle = [ARG_INT | ARG_DOUBLE] (ARG_SELECTOR [ARG_INT | ARG_DOUBLE] message)+

selectStyle = (ARG_SELECTOR message)+

Literal output text is not represented directly by "parts" but accessed

between parts of a message, from one part's getLimit() to the next part's getIndex().

ARG_START.CHOICE

stands for an ARG_START Part with ArgType CHOICE.

In the choiceStyle, the ARG_SELECTOR has the '

', the '#' or

the less-than-or-equal-to sign (U+2264).

In the pluralStyle, the first, optional numeric Part has the "offset:" value.

The optional numeric Part between each (ARG_SELECTOR, message) pair

is the value of an explicit-number selector like "=2",

otherwise the selector is a non-numeric identifier.

The REPLACE_NUMBER Part can occur only in an immediate sub-message of the pluralStyle.

This class is not intended for public subclassing.

ICU 4.8

Public Methods

void MessagePattern (UErrorCode & errorCode)

Constructs an empty MessagePattern with default UMessagePatternApostropheMode.

Parameters

errorCode Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.) ICU 4.8

void MessagePattern (UMessagePatternApostropheMode mode, UErrorCode & errorCode)

Constructs an empty MessagePattern.

Parameters

mode Explicit UMessagePatternApostropheMode.

void MessagePattern (const UnicodeString & pattern, UParseError * parseError, UErrorCode & errorCode)

Constructs a MessagePattern with default UMessagePatternApostropheMode and

parses the MessageFormat pattern string.

Parameters

pattern a MessageFormat pattern string

parseError Struct to receive information on the position of an error within the pattern. Can be nullptr.

Throws

into UErrorCode specifics?

IllegalArgumentException for syntax errors in the pattern string

IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

NumberFormatException if a number could not be parsed ICU 4.8

void MessagePattern (const MessagePattern & other)

Copy constructor.

Parameters

other Object to copy. ICU 4.8

void clear ()

Clears this MessagePattern.

countParts() will return 0.

ICU 4.8

UnicodeString autoQuoteApostropheDeep ()

Returns a version of the parsed pattern string where each ASCII apostrophe

is doubled (escaped) if it is not already, and if it is not interpreted as quoting syntax.

For example, this turns "I don't '{know}' {gender,select,female{h''er}other{h'im}}."

into "I don''t '{know}' {gender,select,female{h''er}other{h''im}}."

Returns

the deep-auto-quoted version of the parsed pattern string.

void clearPatternAndSetApostropheMode (UMessagePatternApostropheMode mode)

Clears this MessagePattern and sets the UMessagePatternApostropheMode.

countParts() will return 0.

Parameters

mode The new UMessagePatternApostropheMode. ICU 4.8

Defined at line 519 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

bool operator!= (const MessagePattern & other)

Parameters

other another object to compare with.

Returns

false if this object is equivalent to the other one.

ICU 4.8

Defined at line 536 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

UMessagePatternApostropheMode getApostropheMode ()

Returns

this instance's UMessagePatternApostropheMode.

ICU 4.8

Defined at line 550 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

const UnicodeString & getPatternString ()

Returns

the parsed pattern string (null if none was parsed).

ICU 4.8

Defined at line 561 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

UBool hasNamedArguments ()

Does the parsed pattern have named arguments like {first_name}?

Returns

true if the parsed pattern has at least one named argument.

ICU 4.8

Defined at line 570 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

UBool hasNumberedArguments ()

Does the parsed pattern have numbered arguments like {2}?

Returns

true if the parsed pattern has at least one numbered argument.

ICU 4.8

Defined at line 579 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

int32_t countParts ()

Returns the number of "parts" created by parsing the pattern string.

Returns 0 if no pattern has been parsed or clear() was called.

Returns

the number of pattern parts.

ICU 4.8

Defined at line 616 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

const Part & getPart (int32_t i)

Gets the i-th pattern "part".

Parameters

i The index of the Part data. (0..countParts()-1)

Returns

the i-th pattern "part".

ICU 4.8

Defined at line 626 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

UMessagePatternPartType getPartType (int32_t i)

Returns the UMessagePatternPartType of the i-th pattern "part".

Convenience method for getPart(i).getType().

Parameters

i The index of the Part data. (0..countParts()-1)

Returns

The UMessagePatternPartType of the i-th Part.

ICU 4.8

Defined at line 637 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

int32_t getPatternIndex (int32_t partIndex)

Returns the pattern index of the specified pattern "part".

Convenience method for getPart(partIndex).getIndex().

Parameters

partIndex The index of the Part data. (0..countParts()-1)

Returns

The pattern index of this Part.

ICU 4.8

Defined at line 648 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

UnicodeString getSubstring (const Part & part)

Returns the substring of the pattern string indicated by the Part.

Convenience method for getPatternString().substring(part.getIndex(), part.getLimit()).

Parameters

part a part of this MessagePattern.

Returns

the substring associated with part.

ICU 4.8

Defined at line 659 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

MessagePattern & operator= (const MessagePattern & other)

Assignment operator.

Parameters

other Object to copy.

Returns

*this=other

ICU 4.8

void ~MessagePattern ()

Destructor.

ICU 4.8

MessagePattern & parse (const UnicodeString & pattern, UParseError * parseError, UErrorCode & errorCode)

Parses a MessageFormat pattern string.

Parameters

pattern a MessageFormat pattern string

parseError Struct to receive information on the position of an error within the pattern. Can be nullptr.

Returns

*this

Throws

IllegalArgumentException for syntax errors in the pattern string

IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

NumberFormatException if a number could not be parsed ICU 4.8

MessagePattern & parseChoiceStyle (const UnicodeString & pattern, UParseError * parseError, UErrorCode & errorCode)

Parses a ChoiceFormat pattern string.

Parameters

pattern a ChoiceFormat pattern string

parseError Struct to receive information on the position of an error within the pattern. Can be nullptr.

Returns

*this

Throws

IllegalArgumentException for syntax errors in the pattern string

IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

NumberFormatException if a number could not be parsed ICU 4.8

MessagePattern & parsePluralStyle (const UnicodeString & pattern, UParseError * parseError, UErrorCode & errorCode)

Parses a PluralFormat pattern string.

Parameters

pattern a PluralFormat pattern string

parseError Struct to receive information on the position of an error within the pattern. Can be nullptr.

Returns

*this

Throws

IllegalArgumentException for syntax errors in the pattern string

IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

NumberFormatException if a number could not be parsed ICU 4.8

MessagePattern & parseSelectStyle (const UnicodeString & pattern, UParseError * parseError, UErrorCode & errorCode)

Parses a SelectFormat pattern string.

Parameters

pattern a SelectFormat pattern string

parseError Struct to receive information on the position of an error within the pattern. Can be nullptr.

Returns

*this

Throws

IllegalArgumentException for syntax errors in the pattern string

IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

NumberFormatException if a number could not be parsed ICU 4.8

bool operator== (const MessagePattern & other)

Parameters

other another object to compare with.

Returns

true if this object is equivalent to the other one.

ICU 4.8

int32_t hashCode ()

Returns

A hash code for this object.

ICU 4.8

UBool partSubstringMatches (const Part & part, const UnicodeString & s)

Compares the part's substring with the input string s.

Parameters

part a part of this MessagePattern.

s a string.

Returns

true if getSubstring(part).equals(s).

ICU 4.8

Defined at line 670 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

int32_t getLimitPartIndex (int32_t start)

Returns the index of the ARG|MSG_LIMIT part corresponding to the ARG|MSG_START at start.

Parameters

start The index of some Part data (0..countParts()-1); this Part should be of Type ARG_START or MSG_START.

Returns

The first i>start where getPart(i).getType()==ARG|MSG_LIMIT at the same nesting level,

or start itself if getPartType(msgStart)!=ARG|MSG_START.

ICU 4.8

Defined at line 698 of file ../../third_party/icu/latest/source/common/unicode/messagepattern.h

int32_t validateArgumentName (const UnicodeString & name)

Validates and parses an argument name or argument number string.

An argument name must be a "pattern identifier", that is, it must contain

no Unicode Pattern_Syntax or Pattern_White_Space characters.

If it only contains ASCII digits, then it must be a small integer with no leading zero.

Parameters

name Input string.

Returns

=0 if the name is a valid number,

ARG_NAME_NOT_NUMBER (-1) if it is a "pattern identifier" but not all ASCII digits,

ARG_NAME_NOT_VALID (-2) if it is neither.

ICU 4.8

double getNumericValue (const Part & part)

Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.

Parameters

part a part of this MessagePattern.

Returns

the part's numeric value, or UMSGPAT_NO_NUMERIC_VALUE if this is not a numeric part.

ICU 4.8

double getPluralOffset (int32_t pluralStart)

Returns the "offset:" value of a PluralFormat argument, or 0 if none is specified.

Parameters

pluralStart the index of the first PluralFormat argument style part. (0..countParts()-1)

Returns

the "offset:" value.

ICU 4.8

Records

```
class Part
```