ICU 76.1: icu::MessagePattern Class Reference

ICU 76.1 76.1

Data Structures | Public Member Functions | Static Public Member Functions
icu::MessagePattern Class Reference

Parses and represents ICU MessageFormat patterns. More...

`#include <messagepattern.h>`

Inheritance diagram for icu::MessagePattern:

## Data Structures
class | Part
| A message pattern "part", representing a pattern parsing event. More...

## Public Member Functions
| MessagePattern (UErrorCode &errorCode)
| Constructs an empty MessagePattern with default UMessagePatternApostropheMode.
| MessagePattern (UMessagePatternApostropheMode mode, UErrorCode &errorCode)
| Constructs an empty MessagePattern.
| MessagePattern (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
| Constructs a MessagePattern with default UMessagePatternApostropheMode and parses the MessageFormat pattern string.
| MessagePattern (const MessagePattern &other)
| Copy constructor.
MessagePattern & | operator= (const MessagePattern &other)
| Assignment operator.
virtual | ~MessagePattern ()
| Destructor.
MessagePattern & | parse (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
| Parses a MessageFormat pattern string.
MessagePattern & | parseChoiceStyle (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
| Parses a ChoiceFormat pattern string.
MessagePattern & | parsePluralStyle (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
| Parses a PluralFormat pattern string.
MessagePattern & | parseSelectStyle (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
| Parses a SelectFormat pattern string.
void | clear ()
| Clears this MessagePattern.
void | clearPatternAndSetApostropheMode (UMessagePatternApostropheMode mode)
| Clears this MessagePattern and sets the UMessagePatternApostropheMode.
bool | operator== (const MessagePattern &other) const
bool | operator!= (const MessagePattern &other) const
int32_t | hashCode () const
UMessagePatternApostropheMode | getApostropheMode () const
const UnicodeString & | getPatternString () const
UBool | hasNamedArguments () const
| Does the parsed pattern have named arguments like {first_name}?
UBool | hasNumberedArguments () const
| Does the parsed pattern have numbered arguments like {2}?
UnicodeString | autoQuoteApostropheDeep () const
| 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.
int32_t | countParts () const
| Returns the number of "parts" created by parsing the pattern string.
const Part & | getPart (int32_t i) const
| Gets the i-th pattern "part".
UMessagePatternPartType | getPartType (int32_t i) const
| Returns the UMessagePatternPartType of the i-th pattern "part".
int32_t | getPatternIndex (int32_t partIndex) const
| Returns the pattern index of the specified pattern "part".
UnicodeString | getSubstring (const Part &part) const
| Returns the substring of the pattern string indicated by the Part.
UBool | partSubstringMatches (const Part &part, const UnicodeString &s) const
| Compares the part's substring with the input string s.
double | getNumericValue (const Part &part) const
| Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.
double | getPluralOffset (int32_t pluralStart) const
| Returns the "offset:" value of a PluralFormat argument, or 0 if none is specified.
int32_t | getLimitPartIndex (int32_t start) const
| Returns the index of the ARG|MSG_LIMIT part corresponding to the ARG|MSG_START at start.
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.
virtual UClassID | getDynamicClassID () const
| ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.

## Static Public Member Functions
static int32_t | validateArgumentName (const UnicodeString &name)
| Validates and parses an argument name or argument number string.

## Detailed Description

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.

Stable
  ICU 4.8

Definition at line 362 of file messagepattern.h.

## Constructor & Destructor Documentation

## ◆ MessagePattern() [1/4]

icu::MessagePattern::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.)

Stable
  ICU 4.8

## ◆ MessagePattern() [2/4]

icu::MessagePattern::MessagePattern | ( | UMessagePatternApostropheMode | mode,
|  | UErrorCode & | errorCode )

Constructs an empty MessagePattern.

Parameters

  mode | Explicit UMessagePatternApostropheMode.
  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.)

Stable
  ICU 4.8

## ◆ MessagePattern() [3/4]

icu::MessagePattern::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.
  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.) TODO: turn

Exceptions

  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

Stable
  ICU 4.8

## ◆ MessagePattern() [4/4]

icu::MessagePattern::MessagePattern | ( | const MessagePattern & | other | ) |

Copy constructor.

Parameters

  other | Object to copy.

Stable
  ICU 4.8

## ◆ ~MessagePattern()

virtual icu::MessagePattern::~MessagePattern | ( |  | ) |
| virtual

Destructor.

Stable
  ICU 4.8

## Member Function Documentation

## ◆ autoQuoteApostropheDeep()

UnicodeString icu::MessagePattern::autoQuoteApostropheDeep | ( |  | ) | const

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.

See also
  MessageFormat.autoQuoteApostrophe()

Stable
  ICU 4.8

## ◆ clear()

void icu::MessagePattern::clear | ( |  | ) |

Clears this MessagePattern.

countParts() will return 0.

Stable
  ICU 4.8

## ◆ clearPatternAndSetApostropheMode()

void icu::MessagePattern::clearPatternAndSetApostropheMode | ( | UMessagePatternApostropheMode | mode | ) |
| inline

Clears this MessagePattern and sets the UMessagePatternApostropheMode.

countParts() will return 0.

Parameters

  mode | The new UMessagePatternApostropheMode.

Stable
  ICU 4.8

Definition at line 519 of file messagepattern.h.

## ◆ countParts()

int32_t icu::MessagePattern::countParts | ( |  | ) | const
| inline

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.

Stable
  ICU 4.8

Definition at line 616 of file messagepattern.h.

## ◆ getApostropheMode()

UMessagePatternApostropheMode icu::MessagePattern::getApostropheMode | ( |  | ) | const
| inline

Returns
  this instance's UMessagePatternApostropheMode.

Stable
  ICU 4.8

Definition at line 550 of file messagepattern.h.

## ◆ getLimitPartIndex()

int32_t icu::MessagePattern::getLimitPartIndex | ( | int32_t | start | ) | const
| inline

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.

Stable
  ICU 4.8

Definition at line 698 of file messagepattern.h.

## ◆ getNumericValue()

double icu::MessagePattern::getNumericValue | ( | const Part & | part | ) | const

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.

Stable
  ICU 4.8

## ◆ getPart()

const Part & icu::MessagePattern::getPart | ( | int32_t | i | ) | const
| inline

Gets the i-th pattern "part".

Parameters

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

Returns
  the i-th pattern "part".

Stable
  ICU 4.8

Definition at line 626 of file messagepattern.h.

## ◆ getPartType()

UMessagePatternPartType icu::MessagePattern::getPartType | ( | int32_t | i | ) | const
| inline

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.

Stable
  ICU 4.8

Definition at line 637 of file messagepattern.h.

## ◆ getPatternIndex()

int32_t icu::MessagePattern::getPatternIndex | ( | int32_t | partIndex | ) | const
| inline

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.

Stable
  ICU 4.8

Definition at line 648 of file messagepattern.h.

## ◆ getPatternString()

const UnicodeString & icu::MessagePattern::getPatternString | ( |  | ) | const
| inline

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

Stable
  ICU 4.8

Definition at line 561 of file messagepattern.h.

## ◆ getPluralOffset()

double icu::MessagePattern::getPluralOffset | ( | int32_t | pluralStart | ) | const

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.

Stable
  ICU 4.8

## ◆ getSubstring()

UnicodeString icu::MessagePattern::getSubstring | ( | const Part & | part | ) | const
| inline

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.

Stable
  ICU 4.8

Definition at line 659 of file messagepattern.h.

References icu::UnicodeString::tempSubString().

## ◆ hashCode()

int32_t icu::MessagePattern::hashCode | ( |  | ) | const

Returns
  A hash code for this object.

Stable
  ICU 4.8

## ◆ hasNamedArguments()

UBool icu::MessagePattern::hasNamedArguments | ( |  | ) | const
| inline

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

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

Stable
  ICU 4.8

Definition at line 570 of file messagepattern.h.

## ◆ hasNumberedArguments()

UBool icu::MessagePattern::hasNumberedArguments | ( |  | ) | const
| inline

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

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

Stable
  ICU 4.8

Definition at line 579 of file messagepattern.h.

## ◆ operator!=()

bool icu::MessagePattern::operator!= | ( | const MessagePattern & | other | ) | const
| inline

Parameters

  other | another object to compare with.

Returns
  false if this object is equivalent to the other one.

Stable
  ICU 4.8

Definition at line 536 of file messagepattern.h.

References icu::operator==().

## ◆ operator=()

MessagePattern & icu::MessagePattern::operator= | ( | const MessagePattern & | other | ) |

Assignment operator.

Parameters

  other | Object to copy.

Returns
  *this=other

Stable
  ICU 4.8

## ◆ operator==()

bool icu::MessagePattern::operator== | ( | const MessagePattern & | other | ) | const

Parameters

  other | another object to compare with.

Returns
  true if this object is equivalent to the other one.

Stable
  ICU 4.8

## ◆ parse()

MessagePattern & icu::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.
  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.)

Returns
  *this

Exceptions

  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

Stable
  ICU 4.8

## ◆ parseChoiceStyle()

MessagePattern & icu::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.
  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.)

Returns
  *this

Exceptions

  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

Stable
  ICU 4.8

## ◆ parsePluralStyle()

MessagePattern & icu::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.
  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.)

Returns
  *this

Exceptions

  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

Stable
  ICU 4.8

## ◆ parseSelectStyle()

MessagePattern & icu::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.
  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.)

Returns
  *this

Exceptions

  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

Stable
  ICU 4.8

## ◆ partSubstringMatches()

UBool icu::MessagePattern::partSubstringMatches | ( | const Part & | part,
|  | const UnicodeString & | s ) const
| inline

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

Stable
  ICU 4.8

Definition at line 670 of file messagepattern.h.

## ◆ validateArgumentName()

static int32_t icu::MessagePattern::validateArgumentName | ( | const UnicodeString & | name | ) |
| static

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.

Stable
  ICU 4.8

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

- common/unicode/messagepattern.h