ICU 4.8.1.1  4.8.1.1
Data Structures | Public Member Functions | Static Public Member Functions
MessagePattern Class Reference

Parses and represents ICU MessageFormat patterns. More...

#include <messagepattern.h>

Inheritance diagram for MessagePattern:
UObject UMemory

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.
MessagePatternoperator= (const MessagePattern &other)
 Assignment operator.
virtual ~MessagePattern ()
 Destructor.
MessagePatternparse (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
 Parses a MessageFormat pattern string.
MessagePatternparseChoiceStyle (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
 Parses a ChoiceFormat pattern string.
MessagePatternparsePluralStyle (const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode)
 Parses a PluralFormat pattern string.
MessagePatternparseSelectStyle (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.
UBool operator== (const MessagePattern &other) const
UBool operator!= (const MessagePattern &other) const
int32_t hashCode () const
UMessagePatternApostropheMode getApostropheMode () const
const UnicodeStringgetPatternString () 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 PartgetPart (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.

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

This class is not intended for public subclassing.

Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 346 of file messagepattern.h.


Constructor & Destructor Documentation

Constructs an empty MessagePattern with default UMessagePatternApostropheMode.

Parameters:
errorCodeStandard 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.)
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Constructs an empty MessagePattern.

Parameters:
modeExplicit UMessagePatternApostropheMode.
errorCodeStandard 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.)
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
MessagePattern::MessagePattern ( const UnicodeString pattern,
UParseError parseError,
UErrorCode errorCode 
)

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

Parameters:
patterna MessageFormat pattern string
parseErrorStruct to receive information on the position of an error within the pattern. Can be NULL.
errorCodeStandard 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:
intoUErrorCode specifics?
IllegalArgumentExceptionfor syntax errors in the pattern string
IndexOutOfBoundsExceptionif certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
NumberFormatExceptionif a number could not be parsed
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Copy constructor.

Parameters:
otherObject to copy.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
virtual MessagePattern::~MessagePattern ( ) [virtual]

Destructor.

Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Member Function Documentation

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()
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Clears this MessagePattern.

countParts() will return 0.

Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Clears this MessagePattern and sets the UMessagePatternApostropheMode.

countParts() will return 0.

Parameters:
modeThe new UMessagePatternApostropheMode.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 503 of file messagepattern.h.

int32_t 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.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 600 of file messagepattern.h.

Returns:
this instance's UMessagePatternApostropheMode.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 534 of file messagepattern.h.

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

Parameters:
startThe 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.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 682 of file messagepattern.h.

double MessagePattern::getNumericValue ( const Part part) const

Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.

Parameters:
parta part of this MessagePattern.
Returns:
the part's numeric value, or UMSGPAT_NO_NUMERIC_VALUE if this is not a numeric part.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
const Part& MessagePattern::getPart ( int32_t  i) const [inline]

Gets the i-th pattern "part".

Parameters:
iThe index of the Part data. (0..countParts()-1)
Returns:
the i-th pattern "part".
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 610 of file messagepattern.h.

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

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

Parameters:
iThe index of the Part data. (0..countParts()-1)
Returns:
The UMessagePatternPartType of the i-th Part.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 621 of file messagepattern.h.

int32_t MessagePattern::getPatternIndex ( int32_t  partIndex) const [inline]

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

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

Parameters:
partIndexThe index of the Part data. (0..countParts()-1)
Returns:
The pattern index of this Part.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 632 of file messagepattern.h.

Returns:
the parsed pattern string (null if none was parsed).
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 545 of file messagepattern.h.

double MessagePattern::getPluralOffset ( int32_t  pluralStart) const

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

Parameters:
pluralStartthe index of the first PluralFormat argument style part. (0..countParts()-1)
Returns:
the "offset:" value.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
UnicodeString 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:
parta part of this MessagePattern.
Returns:
the substring associated with part.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 643 of file messagepattern.h.

References UnicodeString::tempSubString().

Returns:
A hash code for this object.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

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

Returns:
TRUE if the parsed pattern has at least one named argument.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 554 of file messagepattern.h.

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

Returns:
TRUE if the parsed pattern has at least one numbered argument.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 563 of file messagepattern.h.

UBool MessagePattern::operator!= ( const MessagePattern other) const [inline]
Parameters:
otheranother object to compare with.
Returns:
FALSE if this object is equivalent to the other one.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 520 of file messagepattern.h.

References operator==().

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

Assignment operator.

Parameters:
otherObject to copy.
Returns:
*this=other
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
UBool MessagePattern::operator== ( const MessagePattern other) const
Parameters:
otheranother object to compare with.
Returns:
TRUE if this object is equivalent to the other one.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
MessagePattern& MessagePattern::parse ( const UnicodeString pattern,
UParseError parseError,
UErrorCode errorCode 
)

Parses a MessageFormat pattern string.

Parameters:
patterna MessageFormat pattern string
parseErrorStruct to receive information on the position of an error within the pattern. Can be NULL.
errorCodeStandard 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:
IllegalArgumentExceptionfor syntax errors in the pattern string
IndexOutOfBoundsExceptionif certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
NumberFormatExceptionif a number could not be parsed
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
MessagePattern& MessagePattern::parseChoiceStyle ( const UnicodeString pattern,
UParseError parseError,
UErrorCode errorCode 
)

Parses a ChoiceFormat pattern string.

Parameters:
patterna ChoiceFormat pattern string
parseErrorStruct to receive information on the position of an error within the pattern. Can be NULL.
errorCodeStandard 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:
IllegalArgumentExceptionfor syntax errors in the pattern string
IndexOutOfBoundsExceptionif certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
NumberFormatExceptionif a number could not be parsed
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
MessagePattern& MessagePattern::parsePluralStyle ( const UnicodeString pattern,
UParseError parseError,
UErrorCode errorCode 
)

Parses a PluralFormat pattern string.

Parameters:
patterna PluralFormat pattern string
parseErrorStruct to receive information on the position of an error within the pattern. Can be NULL.
errorCodeStandard 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:
IllegalArgumentExceptionfor syntax errors in the pattern string
IndexOutOfBoundsExceptionif certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
NumberFormatExceptionif a number could not be parsed
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
MessagePattern& MessagePattern::parseSelectStyle ( const UnicodeString pattern,
UParseError parseError,
UErrorCode errorCode 
)

Parses a SelectFormat pattern string.

Parameters:
patterna SelectFormat pattern string
parseErrorStruct to receive information on the position of an error within the pattern. Can be NULL.
errorCodeStandard 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:
IllegalArgumentExceptionfor syntax errors in the pattern string
IndexOutOfBoundsExceptionif certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)
NumberFormatExceptionif a number could not be parsed
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8
UBool MessagePattern::partSubstringMatches ( const Part part,
const UnicodeString s 
) const [inline]

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

Parameters:
parta part of this MessagePattern.
sa string.
Returns:
TRUE if getSubstring(part).equals(s).
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

Definition at line 654 of file messagepattern.h.

static int32_t 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:
nameInput 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.
Draft:
This API may be changed in the future versions and was introduced in ICU 4.8

The documentation for this class was generated from the following file:
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines