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.
UBool	operator== (const MessagePattern &other) const
UBool	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.
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

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

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

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

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

Copy constructor.

Parameters:

other

Object to copy.

Stable:: ICU 4.8

virtual icu::MessagePattern::~MessagePattern ( ) [virtual]

Destructor.

Stable:: ICU 4.8

Member Function Documentation

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

void icu::MessagePattern::clear ( )

Clears this MessagePattern.

countParts() will return 0.

Stable:: ICU 4.8

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.

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.

UMessagePatternApostropheMode icu::MessagePattern::getApostropheMode ( ) const [inline]

Returns:: this instance's UMessagePatternApostropheMode.

Stable:: ICU 4.8

Definition at line 550 of file messagepattern.h.

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.

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

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.

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.

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.

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.

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

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

int32_t icu::MessagePattern::hashCode ( ) const

Returns:: A hash code for this object.

Stable:: ICU 4.8

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.

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.

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

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

Assignment operator.

Parameters:

other

Object to copy.

Returns:: *this=other

Stable:: ICU 4.8

UBool 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

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

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

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

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

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.

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:

messagepattern.h

icu::MessagePattern Class Reference

Data Structures

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation