|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.text.Format
com.ibm.icu.text.UFormat
com.ibm.icu.text.PluralFormat
public class PluralFormat
PluralFormat
supports the creation of internationalized
messages with plural inflection. It is based on plural
selection, i.e. the caller specifies messages for each
plural case that can appear in the users language and the
PluralFormat
selects the appropriate message based on
the number.
Different languages have different ways to inflect
plurals. Creating internationalized messages that include plural
forms is only feasible when the framework is able to handle plural
forms of all languages correctly. ChoiceFormat
doesn't handle this well, because it attaches a number interval to
each message and selects the message whose interval contains a
given number. This can only handle a finite number of
intervals. But in some languages, like Polish, one plural case
applies to infinitely many intervals (e.g., paucal applies to
numbers ending with 2, 3, or 4 except those ending with 12, 13, or
14). Thus ChoiceFormat
is not adequate.
PluralFormat
deals with this by breaking the problem
into two parts:
PluralRules
that can define more complex
conditions for a plural case than just a single interval. These plural
rules define both what plural cases exist in a language, and to
which numbers these cases apply.
PluralFormat
This discussion assumes that you use PluralFormat
with
a predefined set of plural rules. You can create one using one of
the constructors that takes a ULocale
object. To
specify the message pattern, you can either pass it to the
constructor or set it explicitly using the
applyPattern()
method. The format()
method takes a number object and selects the message of the
matching plural case. This message will be returned.
The pattern text defines the message output for each plural case of the
used locale. The pattern is a sequence of
caseKeyword{message}
clauses, separated by white
space characters. Each clause assigns the message message
to the plural case identified by caseKeyword
.
You always have to define a message text for the default plural case
"other
" which is contained in every rule set. If the plural
rules of the PluralFormat
object do not contain a plural case
identified by caseKeyword
, an
IllegalArgumentException
is thrown.
If you do not specify a message text for a particular plural case, the
message text of the plural case "other
" gets assigned to this
plural case. If you specify more than one message for the same plural case,
an IllegalArgumentException
is thrown.
Spaces between caseKeyword
and
message
will be ignored; spaces within
message
will be preserved.
The message text for a particular plural case may contain other message
format patterns. PluralFormat
preserves these so that you
can use the strings produced by PluralFormat
with other
formatters. If you are using PluralFormat
inside a
MessageFormat
pattern, MessageFormat
will
automatically evaluate the resulting format pattern.
Thus, curly braces ({
, }
) are only allowed
in message texts to define a nested format pattern.
The pound sign (#
) will be interpreted as the number placeholder
in the message text, if it is not contained in curly braces (to preserve
NumberFormat
patterns). PluralFormat
will
replace each of those pound signs by the number passed to the
format()
method. It will be formatted using a
NumberFormat
for the PluralFormat
's locale. If you
need special number formatting, you have to explicitly specify a
NumberFormat
for the PluralFormat
to use.
MessageFormat msgFmt = new MessageFormat("{0, plural, " + "one{{0, number, C''''est #,##0.0# fichier}} " + "other {Ce sont # fichiers}} dans la liste.", new ULocale("fr")); Object args[] = {new Long(0)}; System.out.println(msgFmt.format(args)); args = {new Long(3)}; System.out.println(msgFmt.format(args));Produces the output:
C'est 0,0 fichier dans la liste.
Ce sont 3 fichiers dans la liste."
Note:
Currently PluralFormat
does not make use of quotes like MessageFormat
.
If you use plural format strings with MessageFormat
and want
to use a quote sign "'
", you have to write "''
".
MessageFormat
unquotes this pattern and passes the unquoted
pattern to PluralFormat
. It's a bit trickier if you use
nested formats that do quoting. In the example above, we wanted to insert
"'
" in the number format pattern. Since
NumberFormat
supports quotes, we had to insert
"''
". But since MessageFormat
unquotes the
pattern before it gets passed to PluralFormat
, we have to
double these quotes, i.e. write "''''
".
If you need to use PluralFormat
with custom rules, you can
create a PluralRules
object and pass it to
PluralFormat
's constructor. If you also specify a locale in this
constructor, this locale will be used to format the number in the message
texts.
For more information about PluralRules
, see
PluralRules
.
Nested Class Summary |
---|
Nested classes/interfaces inherited from class java.text.Format |
---|
Format.Field |
Constructor Summary | |
---|---|
PluralFormat()
Creates a new PluralFormat for the default locale. |
|
PluralFormat(PluralRules rules)
Creates a new PluralFormat for a given set of rules. |
|
PluralFormat(PluralRules rules,
String pattern)
Creates a new PluralFormat for a given set of rules and a
pattern. |
|
PluralFormat(String pattern)
Creates a new PluralFormat for a given pattern string. |
|
PluralFormat(ULocale ulocale)
Creates a new PluralFormat for a given locale. |
|
PluralFormat(ULocale ulocale,
PluralRules rules)
Creates a new PluralFormat for a given set of rules. |
|
PluralFormat(ULocale ulocale,
PluralRules rules,
String pattern)
Creates a new PluralFormat for a given set of rules, a
pattern and a locale. |
|
PluralFormat(ULocale ulocale,
String pattern)
Creates a new PluralFormat for a given pattern string and
locale. |
Method Summary | |
---|---|
void |
applyPattern(String pttrn)
Sets the pattern used by this plural format. |
boolean |
equals(Object rhs)
|
boolean |
equals(PluralFormat rhs)
Returns true if this equals the provided PluralFormat. |
String |
format(double number)
Formats a plural message for a given number. |
StringBuffer |
format(Object number,
StringBuffer toAppendTo,
FieldPosition pos)
Formats a plural message for a given number and appends the formatted message to the given StringBuffer . |
int |
hashCode()
|
Number |
parse(String text,
ParsePosition parsePosition)
This method is not yet supported by PluralFormat . |
Object |
parseObject(String source,
ParsePosition pos)
This method is not yet supported by PluralFormat . |
void |
setLocale(ULocale ulocale)
Sets the locale used by this PluraFormat object. |
void |
setNumberFormat(NumberFormat format)
Sets the number format used by this formatter. |
String |
toString()
For debugging purposes only |
Methods inherited from class com.ibm.icu.text.UFormat |
---|
getLocale |
Methods inherited from class java.text.Format |
---|
clone, format, formatToCharacterIterator, parseObject |
Methods inherited from class java.lang.Object |
---|
finalize, getClass, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public PluralFormat()
PluralFormat
for the default locale.
This locale will be used to get the set of plural rules and for standard
number formatting.
public PluralFormat(ULocale ulocale)
PluralFormat
for a given locale.
ulocale
- the PluralFormat
will be configured with
rules for this locale. This locale will also be used for standard
number formatting.public PluralFormat(PluralRules rules)
PluralFormat
for a given set of rules.
The standard number formatting will be done using the default locale.
rules
- defines the behavior of the PluralFormat
object.public PluralFormat(ULocale ulocale, PluralRules rules)
PluralFormat
for a given set of rules.
The standard number formatting will be done using the given locale.
ulocale
- the default number formatting will be done using this
locale.rules
- defines the behavior of the PluralFormat
object.public PluralFormat(String pattern)
PluralFormat
for a given pattern string.
The default locale will be used to get the set of plural rules and for
standard number formatting.
pattern
- the pattern for this PluralFormat
.
IllegalArgumentException
- if the pattern is invalid.public PluralFormat(ULocale ulocale, String pattern)
PluralFormat
for a given pattern string and
locale.
The locale will be used to get the set of plural rules and for
standard number formatting.
ulocale
- the PluralFormat
will be configured with
rules for this locale. This locale will also be used for standard
number formatting.pattern
- the pattern for this PluralFormat
.
IllegalArgumentException
- if the pattern is invalid.public PluralFormat(PluralRules rules, String pattern)
PluralFormat
for a given set of rules and a
pattern.
The standard number formatting will be done using the default locale.
rules
- defines the behavior of the PluralFormat
object.pattern
- the pattern for this PluralFormat
.
IllegalArgumentException
- if the pattern is invalid.public PluralFormat(ULocale ulocale, PluralRules rules, String pattern)
PluralFormat
for a given set of rules, a
pattern and a locale.
ulocale
- the PluralFormat
will be configured with
rules for this locale. This locale will also be used for standard
number formatting.rules
- defines the behavior of the PluralFormat
object.pattern
- the pattern for this PluralFormat
.
IllegalArgumentException
- if the pattern is invalid.Method Detail |
---|
public void applyPattern(String pttrn)
pttrn
- the pattern for this plural format.
IllegalArgumentException
- if the pattern is invalid.public final String format(double number)
number
- a number for which the plural message should be formatted.
If no pattern has been applied to this
PluralFormat
object yet, the formatted number will
be returned.
public StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos)
StringBuffer
.
format
in class Format
number
- a number object (instance of Number
for which
the plural message should be formatted. If no pattern has been
applied to this PluralFormat
object yet, the
formatted number will be returned.
Note: If this object is not an instance of Number
,
the toAppendTo
will not be modified.toAppendTo
- the formatted message will be appended to this
StringBuffer
.pos
- will be ignored by this method.
IllegalArgumentException
- if number is not an instance of Numberpublic Number parse(String text, ParsePosition parsePosition)
PluralFormat
.
text
- the string to be parsed.parsePosition
- 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.
UnsupportedOperationException
- will always be thrown by this method.public Object parseObject(String source, ParsePosition pos)
PluralFormat
.
parseObject
in class 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.
UnsupportedOperationException
- will always be thrown by this method.public void setLocale(ULocale ulocale)
PluraFormat
object.
Note: Calling this method resets this PluraFormat
object,
i.e., a pattern that was applied previously will be removed,
and the NumberFormat is set to the default number format for
the locale. The resulting format behaves the same as one
constructed from PluralFormat(ULocale)
.
ulocale
- the ULocale
used to configure the
formatter. If ulocale
is null
, the
default locale will be used.public void setNumberFormat(NumberFormat format)
format
- the number format to use.public boolean equals(Object rhs)
equals
in class Object
public boolean equals(PluralFormat rhs)
rhs
- the PluralFormat to compare against
public int hashCode()
hashCode
in class Object
public String toString()
toString
in class Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |