public class SelectFormat
extends java.text.Format
SelectFormat
supports the creation of internationalized
messages by selecting phrases based on keywords. The pattern specifies
how to map keywords to phrases and provides a default phrase. The
object provided to the format method is a string that's matched
against the keywords. If there is a match, the corresponding phrase
is selected; otherwise, the default phrase is used.
SelectFormat
for Gender AgreementThe main use case for the select format is gender based inflection. When names or nouns are inserted into sentences, their gender can affect pronouns, verb forms, articles, and adjectives. Special care needs to be taken for the case where the gender cannot be determined. The impact varies between languages:
Some other languages have noun classes that are not related to gender, but similar in grammatical use. Some African languages have around 20 noun classes.
To enable localizers to create sentence patterns that take their
language's gender dependencies into consideration, software has to provide
information about the gender associated with a noun or name to
MessageFormat
.
Two main cases can be distinguished:
The resulting keyword is provided to MessageFormat
as a
parameter separate from the name or noun it's associated with. For example,
to generate a message such as "Jean went to Paris", three separate arguments
would be provided: The name of the person as argument 0, the gender of
the person as argument 1, and the name of the city as argument 2.
The sentence pattern for English, where the gender of the person has
no impact on this simple sentence, would not refer to argument 1 at all:
{0} went to {2}.
The sentence pattern for French, where the gender of the person affects the form of the participle, uses a select format based on argument 1:
{0} est {1, select, female {allu00E9;e} other {allu00E9;}} u00E0; {2}.
Patterns can be nested, so that it's possible to handle interactions of number and gender where necessary. For example, if the above sentence should allow for the names of several people to be inserted, the following sentence pattern can be used (with argument 0 the list of people's names, argument 1 the number of people, argument 2 their combined gender, and argument 3 the city name):
{0} {1, plural, one {est {2, select, female {allu00E9;e} other {allu00E9;}}} other {sont {2, select, female {allu00E9;es} other {allu00E9;s}}} }u00E0; {3}.
The SelectFormat
pattern text defines the phrase output
for each user-defined keyword.
The pattern is a sequence of keyword{phrase}
clauses, separated by white space characters.
Each clause assigns the phrase phrase
to the user-defined keyword
.
Keywords must match the pattern [a-zA-Z][a-zA-Z0-9_-]*; keywords
that don't match this pattern result in the error code
U_ILLEGAL_CHARACTER
.
You always have to define a phrase for the default keyword
other
; this phrase is returned when the keyword
provided to
the format
method matches no other keyword.
If a pattern does not provide a phrase for other
, the method
it's provided to returns the error U_DEFAULT_KEYWORD_MISSING
.
If a pattern provides more than one phrase for the same keyword, the
error U_DUPLICATE_KEYWORD
is returned.
Spaces between keyword
and
{phrase}
will be ignored; spaces within
{phrase}
will be preserved.
The phrase for a particular select case may contain other message
format patterns. SelectFormat
preserves these so that you
can use the strings produced by SelectFormat
with other
formatters. If you are using SelectFormat
inside a
MessageFormat
pattern, MessageFormat
will
automatically evaluate the resulting format pattern.
Thus, curly braces ({
, }
) are only allowed
in phrases to define a nested format pattern.
Example: MessageFormat msgFmt = new MessageFormat("{0} est " + "{1, select, female {allu00E9;e} other {allu00E9;}} u00E0; Paris.", new ULocale("fr")); Object args[] = {"Kirti","female"}; System.out.println(msgFmt.format(args));
Produces the output:
Kirti est allu00E9;e u00E0; Paris.
Constructor and Description |
---|
SelectFormat(java.lang.String pattern)
Creates a new
SelectFormat for a given pattern string. |
Modifier and Type | Method and Description |
---|---|
void |
applyPattern(java.lang.String pattern)
Sets the pattern used by this select format.
|
boolean |
equals(java.lang.Object obj) |
java.lang.StringBuffer |
format(java.lang.Object keyword,
java.lang.StringBuffer toAppendTo,
java.text.FieldPosition pos)
Selects the phrase for the given keyword.
|
java.lang.String |
format(java.lang.String keyword)
Selects the phrase for the given keyword.
|
int |
hashCode() |
java.lang.Object |
parseObject(java.lang.String source,
java.text.ParsePosition pos)
This method is not supported by
SelectFormat . |
java.lang.String |
toPattern()
Returns the pattern for this
SelectFormat |
java.lang.String |
toString()
Returns a string representation of the object
|
public SelectFormat(java.lang.String pattern)
SelectFormat
for a given pattern string.pattern
- the pattern for this SelectFormat
.public void applyPattern(java.lang.String pattern)
pattern
- the pattern for this select format.java.lang.IllegalArgumentException
- when the pattern is not a valid select format pattern.public java.lang.String toPattern()
SelectFormat
public final java.lang.String format(java.lang.String keyword)
keyword
- a keyword for which the select message should be formatted.java.lang.IllegalArgumentException
- when the given keyword is not available in the select format patternpublic java.lang.StringBuffer format(java.lang.Object keyword, java.lang.StringBuffer toAppendTo, java.text.FieldPosition pos)
StringBuffer
.format
in class java.text.Format
keyword
- a keyword for which the select message should be formatted.toAppendTo
- the formatted message will be appended to this
StringBuffer
.pos
- will be ignored by this method.java.lang.IllegalArgumentException
- when the given keyword is not available in the select format patternpublic java.lang.Object parseObject(java.lang.String source, java.text.ParsePosition pos)
SelectFormat
.parseObject
in class java.text.Format
source
- the string to be parsed.pos
- defines the position where parsing is to begin,
and upon return, the position where parsing left off. If the position
has not changed upon return, then parsing failed.java.lang.UnsupportedOperationException
- thrown always.public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
toPattern()
.Copyright (c) 2011 IBM Corporation and others.