Added in API level 24

MessagePattern

class MessagePattern : Cloneable, Freezable<MessagePattern!>
kotlin.Any
   ↳ android.icu.text.MessagePattern

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", getLimitPartIndex(int) 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.

Summary

Nested classes

Mode for when an apostrophe starts quoted literal text for MessageFormat output.

Argument type constants.

A message pattern "part", representing a pattern parsing event.

Constants
static Int

Return value from validateArgumentName(java.lang.String) for when the string is a valid "pattern identifier" but not a number.

static Int

Return value from validateArgumentName(java.lang.String) for when the string is invalid.

static Double

Special value that is returned by getNumericValue(Part) when no numeric value is defined for a part.

Public constructors

Constructs an empty MessagePattern with default ApostropheMode.

Constructs an empty MessagePattern.

Constructs a MessagePattern with default ApostropheMode and parses the MessageFormat pattern string.

Public methods
String!

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.

Unit

Clears this MessagePattern.

Unit

Clears this MessagePattern and sets the ApostropheMode.

Any

Creates and returns a copy of this object.

MessagePattern!

Creates and returns an unfrozen copy of this object.

Int

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

Boolean
equals(other: Any?)

MessagePattern!

Freezes this object, making it immutable and thread-safe.

MessagePattern.ApostropheMode!

Int

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

Double

Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.

MessagePattern.Part!

Gets the i-th pattern "part".

MessagePattern.Part.Type!

Returns the Part.

Int
getPatternIndex(partIndex: Int)

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

String!

Double
getPluralOffset(pluralStart: Int)

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

String!

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

Boolean

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

Boolean

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

Int

Returns a hash code value for the object.

Boolean

Determines whether this object is frozen (immutable) or not.

MessagePattern!
parse(pattern: String!)

Parses a MessageFormat pattern string.

MessagePattern!

Parses a ChoiceFormat pattern string.

MessagePattern!

Parses a PluralFormat pattern string.

MessagePattern!

Parses a SelectFormat pattern string.

Boolean

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

String

Returns a string representation of the object.

static Int

Validates and parses an argument name or argument number string.

Constants

ARG_NAME_NOT_NUMBER

Added in API level 24
static val ARG_NAME_NOT_NUMBER: Int

Return value from validateArgumentName(java.lang.String) for when the string is a valid "pattern identifier" but not a number.

Value: -1

ARG_NAME_NOT_VALID

Added in API level 24
static val ARG_NAME_NOT_VALID: Int

Return value from validateArgumentName(java.lang.String) for when the string is invalid. It might not be a valid "pattern identifier", or it have only ASCII digits but there is a leading zero or the number is too large.

Value: -2

NO_NUMERIC_VALUE

Added in API level 24
static val NO_NUMERIC_VALUE: Double

Special value that is returned by getNumericValue(Part) when no numeric value is defined for a part.

Value: -1.23456789E8

See Also

Public constructors

MessagePattern

Added in API level 24
MessagePattern()

Constructs an empty MessagePattern with default ApostropheMode.

MessagePattern

Added in API level 24
MessagePattern(mode: MessagePattern.ApostropheMode!)

Constructs an empty MessagePattern.

Parameters
mode MessagePattern.ApostropheMode!: Explicit ApostropheMode.

MessagePattern

Added in API level 24
MessagePattern(pattern: String!)

Constructs a MessagePattern with default ApostropheMode and parses the MessageFormat pattern string.

Parameters
pattern String!: a MessageFormat pattern string
Exceptions
java.lang.IllegalArgumentException for syntax errors in the pattern string
java.lang.IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
java.lang.NumberFormatException if a number could not be parsed

Public methods

autoQuoteApostropheDeep

Added in API level 24
fun autoQuoteApostropheDeep(): String!

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

Return
String! the deep-auto-quoted version of the parsed pattern string.

clear

Added in API level 24
fun clear(): Unit

Clears this MessagePattern. countParts() will return 0.

clearPatternAndSetApostropheMode

Added in API level 24
fun clearPatternAndSetApostropheMode(mode: MessagePattern.ApostropheMode!): Unit

Clears this MessagePattern and sets the ApostropheMode. countParts() will return 0.

Parameters
mode MessagePattern.ApostropheMode!: The new ApostropheMode.

clone

Added in API level 24
fun clone(): Any

Creates and returns a copy of this object.

Return
Any a copy of this object (or itself if frozen).
Exceptions
java.lang.CloneNotSupportedException if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.

cloneAsThawed

Added in API level 24
fun cloneAsThawed(): MessagePattern!

Creates and returns an unfrozen copy of this object.

Return
MessagePattern! a copy of this object.

countParts

Added in API level 24
fun countParts(): Int

Returns the number of "parts" created by parsing the pattern string. Returns 0 if no pattern has been parsed or clear() was called.

Return
Int the number of pattern parts.

equals

Added in API level 24
fun equals(other: Any?): Boolean
Parameters
obj the reference object with which to compare.
other Any?: another object to compare with.
Return
Boolean true if this object is equivalent to the other one.

freeze

Added in API level 24
fun freeze(): MessagePattern!

Freezes this object, making it immutable and thread-safe.

Return
MessagePattern! this

getApostropheMode

Added in API level 24
fun getApostropheMode(): MessagePattern.ApostropheMode!
Return
MessagePattern.ApostropheMode! this instance's ApostropheMode.

getLimitPartIndex

Added in API level 24
fun getLimitPartIndex(start: Int): Int

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

Parameters
start Int: The index of some Part data (0..countParts()-1); this Part should be of Type ARG_START or MSG_START.
Return
Int 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.
Exceptions
java.lang.IndexOutOfBoundsException if start is outside the (0..countParts()-1) range

getNumericValue

Added in API level 24
fun getNumericValue(part: MessagePattern.Part!): Double

Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.

Parameters
part MessagePattern.Part!: a part of this MessagePattern.
Return
Double the part's numeric value, or NO_NUMERIC_VALUE if this is not a numeric part.

getPart

Added in API level 24
fun getPart(i: Int): MessagePattern.Part!

Gets the i-th pattern "part".

Parameters
i Int: The index of the Part data. (0..countParts()-1)
Return
MessagePattern.Part! the i-th pattern "part".
Exceptions
java.lang.IndexOutOfBoundsException if i is outside the (0..countParts()-1) range

getPartType

Added in API level 24
fun getPartType(i: Int): MessagePattern.Part.Type!

Returns the Part.Type of the i-th pattern "part". Convenience method for getPart(i).getType().

Parameters
i Int: The index of the Part data. (0..countParts()-1)
Return
MessagePattern.Part.Type! The Part.Type of the i-th Part.
Exceptions
java.lang.IndexOutOfBoundsException if i is outside the (0..countParts()-1) range

getPatternIndex

Added in API level 24
fun getPatternIndex(partIndex: Int): Int

Returns the pattern index of the specified pattern "part". Convenience method for getPart(partIndex).getIndex().

Parameters
partIndex Int: The index of the Part data. (0..countParts()-1)
Return
Int The pattern index of this Part.
Exceptions
java.lang.IndexOutOfBoundsException if partIndex is outside the (0..countParts()-1) range

getPatternString

Added in API level 24
fun getPatternString(): String!
Return
String! the parsed pattern string (null if none was parsed).

getPluralOffset

Added in API level 24
fun getPluralOffset(pluralStart: Int): Double

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

Parameters
pluralStart Int: the index of the first PluralFormat argument style part. (0..countParts()-1)
Return
Double the "offset:" value.
Exceptions
java.lang.IndexOutOfBoundsException if pluralStart is outside the (0..countParts()-1) range

getSubstring

Added in API level 24
fun getSubstring(part: MessagePattern.Part!): String!

Returns the substring of the pattern string indicated by the Part. Convenience method for getPatternString().substring(part.getIndex(), part.getLimit()).

Parameters
part MessagePattern.Part!: a part of this MessagePattern.
Return
String! the substring associated with part.

hasNamedArguments

Added in API level 24
fun hasNamedArguments(): Boolean

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

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

hasNumberedArguments

Added in API level 24
fun hasNumberedArguments(): Boolean

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

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

hashCode

Added in API level 24
fun hashCode(): Int

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Return
Int a hash code value for this object.

isFrozen

Added in API level 24
fun isFrozen(): Boolean

Determines whether this object is frozen (immutable) or not.

Return
Boolean true if this object is frozen.

parse

Added in API level 24
fun parse(pattern: String!): MessagePattern!

Parses a MessageFormat pattern string.

Parameters
pattern String!: a MessageFormat pattern string
Return
MessagePattern! this
Exceptions
java.lang.IllegalArgumentException for syntax errors in the pattern string
java.lang.IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
java.lang.NumberFormatException if a number could not be parsed

parseChoiceStyle

Added in API level 24
fun parseChoiceStyle(pattern: String!): MessagePattern!

Parses a ChoiceFormat pattern string.

Parameters
pattern String!: a ChoiceFormat pattern string
Return
MessagePattern! this
Exceptions
java.lang.IllegalArgumentException for syntax errors in the pattern string
java.lang.IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
java.lang.NumberFormatException if a number could not be parsed

parsePluralStyle

Added in API level 24
fun parsePluralStyle(pattern: String!): MessagePattern!

Parses a PluralFormat pattern string.

Parameters
pattern String!: a PluralFormat pattern string
Return
MessagePattern! this
Exceptions
java.lang.IllegalArgumentException for syntax errors in the pattern string
java.lang.IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
java.lang.NumberFormatException if a number could not be parsed

parseSelectStyle

Added in API level 24
fun parseSelectStyle(pattern: String!): MessagePattern!

Parses a SelectFormat pattern string.

Parameters
pattern String!: a SelectFormat pattern string
Return
MessagePattern! this
Exceptions
java.lang.IllegalArgumentException for syntax errors in the pattern string
java.lang.IndexOutOfBoundsException if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
java.lang.NumberFormatException if a number could not be parsed

partSubstringMatches

Added in API level 24
fun partSubstringMatches(
    part: MessagePattern.Part!,
    s: String!
): Boolean

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

Parameters
part MessagePattern.Part!: a part of this MessagePattern.
s String!: a string.
Return
Boolean true if getSubstring(part).equals(s).

toString

Added in API level 24
fun toString(): String

Returns a string representation of the object.

Return
String a string representation of the object.

validateArgumentName

Added in API level 24
static fun validateArgumentName(name: String!): Int

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 String!: Input string.
Return
Int >=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.