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 |
static Int |
Return value from |
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. |
|
MessagePattern(pattern: String!) 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 |
clear() Clears this MessagePattern. |
Unit |
Clears this MessagePattern and sets the ApostropheMode. |
Any |
clone() 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 | |
MessagePattern! |
freeze() Freezes this object, making it immutable and thread-safe. |
MessagePattern.ApostropheMode! | |
Int |
getLimitPartIndex(start: Int) Returns the index of the ARG|MSG_LIMIT part corresponding to the ARG|MSG_START at start. |
Double |
getNumericValue(part: MessagePattern.Part!) Returns the numeric value associated with an ARG_INT or ARG_DOUBLE. |
MessagePattern.Part! |
Gets the i-th pattern "part". |
MessagePattern.Part.Type! |
getPartType(i: Int) 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! |
getSubstring(part: MessagePattern.Part!) 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 |
hashCode() Returns a hash code value for the object. |
Boolean |
isFrozen() Determines whether this object is frozen (immutable) or not. |
MessagePattern! |
Parses a MessageFormat pattern string. |
MessagePattern! |
parseChoiceStyle(pattern: String!) Parses a ChoiceFormat pattern string. |
MessagePattern! |
parsePluralStyle(pattern: String!) Parses a PluralFormat pattern string. |
MessagePattern! |
parseSelectStyle(pattern: String!) Parses a SelectFormat pattern string. |
Boolean |
partSubstringMatches(part: MessagePattern.Part!, s: String!) Compares the part's substring with the input string s. |
String |
toString() Returns a string representation of the object. |
static Int |
validateArgumentName(name: String!) Validates and parses an argument name or argument number string. |
Constants
ARG_NAME_NOT_NUMBER
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
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
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
MessagePattern()
Constructs an empty MessagePattern with default ApostropheMode.
MessagePattern
MessagePattern(mode: MessagePattern.ApostropheMode!)
Constructs an empty MessagePattern.
Parameters | |
---|---|
mode |
MessagePattern.ApostropheMode!: Explicit ApostropheMode. |
MessagePattern
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
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
fun clear(): Unit
Clears this MessagePattern. countParts() will return 0.
clearPatternAndSetApostropheMode
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
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
fun cloneAsThawed(): MessagePattern!
Creates and returns an unfrozen copy of this object.
Return | |
---|---|
MessagePattern! |
a copy of this object. |
countParts
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
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
fun freeze(): MessagePattern!
Freezes this object, making it immutable and thread-safe.
Return | |
---|---|
MessagePattern! |
this |
getApostropheMode
fun getApostropheMode(): MessagePattern.ApostropheMode!
Return | |
---|---|
MessagePattern.ApostropheMode! |
this instance's ApostropheMode. |
getLimitPartIndex
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
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
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
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
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
fun getPatternString(): String!
Return | |
---|---|
String! |
the parsed pattern string (null if none was parsed). |
getPluralOffset
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
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
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
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
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 inequals
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 thehashCode
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 thehashCode
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
fun isFrozen(): Boolean
Determines whether this object is frozen (immutable) or not.
Return | |
---|---|
Boolean |
true if this object is frozen. |
parse
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
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
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
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
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
fun toString(): String
Returns a string representation of the object.
Return | |
---|---|
String |
a string representation of the object. |
validateArgumentName
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. |