- All Implemented Interfaces:
Serializable
,Cloneable
ChoiceFormat
is a concrete subclass of NumberFormat
that
allows you to attach a format to a range of numbers.
It is generally used in a MessageFormat
for handling plurals.
The choice is specified with an ascending list of doubles, where each item
specifies a half-open interval up to the next item:
If there is no match, then either the first or last index is used, depending on whether the number (X) is too low or too high. If the limit array is not in ascending order, the results of formatting will be incorrect. ChoiceFormat also acceptsX matches j if and only if limit[j] ≤ X < limit[j+1]
\u221E
as equivalent to infinity(INF).
Note:
ChoiceFormat
differs from the other Format
classes in that you create a ChoiceFormat
object with a
constructor (not with a getInstance
style factory
method). The factory methods aren't necessary because ChoiceFormat
doesn't require any complex setup for a given locale. In fact,
ChoiceFormat
doesn't implement any locale specific behavior.
A ChoiceFormat
can be constructed using either an array of formats
and an array of limits or a string pattern. When constructing with
format and limit arrays, the length of these arrays must be the same.
For example,
-
limits = {1,2,3,4,5,6,7}
formats = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"} -
limits = {0, 1, ChoiceFormat.nextDouble(1)}
formats = {"no files", "one file", "many files"}
(nextDouble
can be used to get the next higher double, to make the half-open interval.)
Below is an example of constructing a ChoiceFormat with arrays to format and parse values:
For more sophisticated patterns,double[] limits = {1,2,3,4,5,6,7}; String[] dayOfWeekNames = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}; ChoiceFormat form = new ChoiceFormat(limits, dayOfWeekNames); ParsePosition status = new ParsePosition(0); for (double i = 0.0; i <= 8.0; ++i) { status.setIndex(0); System.out.println(i + " -> " + form.format(i) + " -> " + form.parse(form.format(i),status)); }
ChoiceFormat
can be used with
MessageFormat
to produce accurate forms for singular and plural:
Would output the following:double[] filelimits = {0,1,2}; String[] filepart = {"are no files","is one file","are {2} files"}; ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart); Format[] testFormats = {fileform, null, NumberFormat.getInstance()}; MessageFormat pattform = new MessageFormat("There {0} on {1}"); pattform.setFormats(testFormats); Object[] testArgs = {null, "ADisk", null}; for (int i = 0; i < 4; ++i) { testArgs[0] = Integer.valueOf(i); testArgs[2] = testArgs[0]; System.out.println(pattform.format(testArgs)); }
There are no files on ADisk There is one file on ADisk There are 2 files on ADisk There are 3 files on ADisk
Patterns
AChoiceFormat
pattern has the following syntax:
Note:The relation ≤ is not equivalent to <=
- Pattern:
- SubPattern *("|" SubPattern)
- Note: Each additional SubPattern must have a Limit greater than the previous SubPattern's Limit
- SubPattern:
- Limit Relation Format
- Limit:
- Number / "∞" / "-∞"
- Number:
- ["-"] *(Digit) 1*(Decimal / Digit) *(Digit) [Exponent]
- Decimal:
- 1*(Digit ".") / 1*("." Digit)
- Digit:
- 0 - 9
- Exponent:
- *(Digit) Digit ExponentSymbol Digit *(Digit)
- ExponentSymbol:
- "e" / "E"
- Relation:
- "#" / "<" / "≤"
- Format:
- Any characters except the Relation symbols
If a Relation symbol is to be used within a Format pattern,
it must be single quoted. For example,
new ChoiceFormat("1# '#'1 ").format(1)
returns " #1 "
.
Use two single quotes in a row to produce a literal single quote. For example,
new ChoiceFormat("1# ''one'' ").format(1)
returns " 'one' "
.
Below is an example of constructing a ChoiceFormat with a pattern:
ChoiceFormat fmt = new ChoiceFormat( "-1#is negative| 0#is zero or fraction | 1#is one |1.0<is 1+ |2#is two |2<is more than 2."); System.out.println(fmt.format(Double.NEGATIVE_INFINITY)); // outputs "is negative" System.out.println(fmt.format(-1.0)); // outputs "is negative" System.out.println(fmt.format(0)); // outputs "is zero or fraction" System.out.println(fmt.format(0.9)); // outputs "is zero or fraction" System.out.println(fmt.format(1)); // outputs "is one" System.out.println(fmt.format(1.5)); // outputs "is 1+" System.out.println(fmt.format(2)); // outputs "is two" System.out.println(fmt.format(2.1)); // outputs "is more than 2." System.out.println(fmt.format(Double.NaN)); // outputs "is negative" System.out.println(fmt.format(Double.POSITIVE_INFINITY)); // outputs "is more than 2."
Synchronization
Choice formats are not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.
- Since:
- 1.1
- See Also:
-
Nested Class Summary
Nested classes/interfaces declared in class java.text.NumberFormat
NumberFormat.Field, NumberFormat.Style
-
Field Summary
Fields declared in class java.text.NumberFormat
FRACTION_FIELD, INTEGER_FIELD
-
Constructor Summary
ConstructorDescriptionChoiceFormat
(double[] limits, String[] formats) Constructs with the limits and the corresponding formats.ChoiceFormat
(String newPattern) Constructs a ChoiceFormat with limits and corresponding formats based on the pattern. -
Method Summary
Modifier and TypeMethodDescriptionvoid
applyPattern
(String newPattern) Apply the given pattern to this ChoiceFormat object.clone()
Overrides Cloneableboolean
Compares the specified object with thisChoiceFormat
for equality.format
(double number, StringBuffer toAppendTo, FieldPosition status) Returns pattern with formatted double.format
(long number, StringBuffer toAppendTo, FieldPosition status) Specialization of format.Object[]
Returns the formats of this ChoiceFormat.double[]
Returns the limits of this ChoiceFormat.int
hashCode()
Returns the hash code for thisChoiceFormat
.static final double
nextDouble
(double d) Finds the least double greater thand
.static double
nextDouble
(double d, boolean positive) Finds the least double greater thand
(ifpositive
istrue
), or the greatest double less thand
(ifpositive
isfalse
).parse
(String text, ParsePosition status) Parses a Number from the input text.static final double
previousDouble
(double d) Finds the greatest double less thand
.void
setChoices
(double[] limits, String[] formats) Set the choices to be used in formatting.Returns a patternstring
that represents thelimits
andformats
of this ChoiceFormat object.Methods declared in class java.text.NumberFormat
format, format, format, getAvailableLocales, getCompactNumberInstance, getCompactNumberInstance, getCurrency, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getMaximumFractionDigits, getMaximumIntegerDigits, getMinimumFractionDigits, getMinimumIntegerDigits, getNumberInstance, getNumberInstance, getPercentInstance, getPercentInstance, getRoundingMode, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setCurrency, setGroupingUsed, setMaximumFractionDigits, setMaximumIntegerDigits, setMinimumFractionDigits, setMinimumIntegerDigits, setParseIntegerOnly, setRoundingMode
Methods declared in class java.text.Format
format, formatToCharacterIterator, parseObject
-
Constructor Details
-
ChoiceFormat
Constructs a ChoiceFormat with limits and corresponding formats based on the pattern. The syntax for the ChoiceFormat pattern can be seen in the Patterns section.- Parameters:
newPattern
- the new pattern string- Throws:
NullPointerException
- ifnewPattern
isnull
IllegalArgumentException
- ifnewPattern
violates the pattern syntax- See Also:
-
ChoiceFormat
Constructs with the limits and the corresponding formats.- Parameters:
limits
- limits in ascending orderformats
- corresponding format strings- Throws:
NullPointerException
- iflimits
orformats
isnull
IllegalArgumentException
- if the length oflimits
andformats
are not equal- See Also:
-
-
Method Details
-
applyPattern
Apply the given pattern to this ChoiceFormat object. The syntax for the ChoiceFormat pattern can be seen in the Patterns section. UnlikesetChoices(double[], String[])
this method will throw anIllegalArgumentException
if thelimits
are not in ascending order.- Parameters:
newPattern
- a pattern string- Throws:
NullPointerException
- ifnewPattern
isnull
IllegalArgumentException
- ifnewPattern
violates the pattern syntax- See Also:
-
toPattern
Returns a patternstring
that represents thelimits
andformats
of this ChoiceFormat object. Thestring
returned is not guaranteed to be the same inputstring
passed to eitherapplyPattern(String)
orChoiceFormat(String)
.- Returns:
- a pattern
string
that represents thelimits
andformats
of this ChoiceFormat object - See Also:
-
setChoices
Set the choices to be used in formatting.- Parameters:
limits
- contains the top value that you want parsed with that format, and should be in ascending sorted order. When formatting X, the choice will be the i, where limit[i] ≤ X < limit[i+1]. If the limit array is not in ascending order, the results of formatting will be incorrect.formats
- are the formats you want to use for each limit.- Throws:
NullPointerException
- iflimits
orformats
isnull
IllegalArgumentException
- if the length oflimits
andformats
are not equal
-
getLimits
public double[] getLimits()Returns the limits of this ChoiceFormat.- Returns:
- the limits of this ChoiceFormat
-
getFormats
Returns the formats of this ChoiceFormat.- Returns:
- the formats of this ChoiceFormat
-
format
Specialization of format. This method really callsformat(double, StringBuffer, FieldPosition)
thus the range of longs that are supported is only equal to the range that can be stored by double. This will never be a practical limitation.- Specified by:
format
in classNumberFormat
- Parameters:
number
- the long number to formattoAppendTo
- the StringBuffer to which the formatted text is to be appendedstatus
- keeps track on the position of the field within the returned string. For example, for formatting a number123456789
inLocale.US
locale, if the givenfieldPosition
isNumberFormat.INTEGER_FIELD
, the begin index and end index offieldPosition
will be set to 0 and 11, respectively for the output string123,456,789
.- Returns:
- the formatted StringBuffer
- See Also:
-
format
Returns pattern with formatted double.- Specified by:
format
in classNumberFormat
- Parameters:
number
- number to be formatted and substituted.toAppendTo
- where text is appended.status
- ignore no useful status is returned.- Returns:
- the formatted StringBuffer
- Throws:
NullPointerException
- iftoAppendTo
isnull
- See Also:
-
parse
Parses a Number from the input text.- Specified by:
parse
in classNumberFormat
- Parameters:
text
- the source text.status
- an input-output parameter. On input, the status.index field indicates the first character of the source text that should be parsed. On exit, if no error occurred, status.index is set to the first unparsed character in the source text. On exit, if an error did occur, status.index is unchanged and status.errorIndex is set to the first index of the character that caused the parse to fail.- Returns:
- A Number representing the value of the number parsed.
- Throws:
NullPointerException
- ifstatus
isnull
or iftext
isnull
and the list of choice strings is not empty.- See Also:
-
nextDouble
public static final double nextDouble(double d) Finds the least double greater thand
. IfNaN
, returns same value.Used to make half-open intervals.
- Implementation Note:
- This is equivalent to calling
Math.nextUp(d)
- Parameters:
d
- the reference value- Returns:
- the least double value greater than
d
- See Also:
-
previousDouble
public static final double previousDouble(double d) Finds the greatest double less thand
. IfNaN
, returns same value.- Implementation Note:
- This is equivalent to calling
Math.nextDown(d)
- Parameters:
d
- the reference value- Returns:
- the greatest double value less than
d
- See Also:
-
clone
Overrides Cloneable- Overrides:
clone
in classNumberFormat
- Returns:
- a clone of this instance.
- See Also:
-
hashCode
public int hashCode()Returns the hash code for thisChoiceFormat
.- Overrides:
hashCode
in classNumberFormat
- Implementation Requirements:
- This method calculates the hash code value using the values returned by
getFormats()
andgetLimits()
. - Returns:
- the hash code for this
ChoiceFormat
- See Also:
-
equals
Compares the specified object with thisChoiceFormat
for equality. Returns true if the object is also aChoiceFormat
and the two formats would format any value the same.- Overrides:
equals
in classNumberFormat
- Implementation Requirements:
- This method performs an equality check with a notion of class
identity based on
getClass()
, rather thaninstanceof
. Therefore, in the equals methods in subclasses, no instance of this class should compare as equal to an instance of a subclass. - Parameters:
obj
- object to be compared for equality- Returns:
true
if the specified object is equal to thisChoiceFormat
- See Also:
-
nextDouble
public static double nextDouble(double d, boolean positive) Finds the least double greater thand
(ifpositive
istrue
), or the greatest double less thand
(ifpositive
isfalse
). IfNaN
, returns same value.- Implementation Note:
- This is equivalent to calling
positive ? Math.nextUp(d) : Math.nextDown(d)
- Parameters:
d
- the reference valuepositive
-true
if the least double is desired;false
otherwise- Returns:
- the least or greater double value
-