Serializable
, Cloneable
public class ChoiceFormat extends NumberFormat
ChoiceFormat
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.
When creating a ChoiceFormat
, you must specify an array of formats and an array of limits. The length of these arrays must be the same. For example,
nextDouble
can be used to get the next higher double, to make the half-open interval.) Here is a simple example that shows formatting and parsing:
Here is a more complex example, with a pattern format: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)); }
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)); }
Specifying a pattern for ChoiceFormat objects is fairly straightforward. For example:
And the output result would be like the following: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("Formatter Pattern : " + fmt.toPattern()); System.out.println("Format with -INF : " + fmt.format(Double.NEGATIVE_INFINITY)); System.out.println("Format with -1.0 : " + fmt.format(-1.0)); System.out.println("Format with 0 : " + fmt.format(0)); System.out.println("Format with 0.9 : " + fmt.format(0.9)); System.out.println("Format with 1.0 : " + fmt.format(1)); System.out.println("Format with 1.5 : " + fmt.format(1.5)); System.out.println("Format with 2 : " + fmt.format(2)); System.out.println("Format with 2.1 : " + fmt.format(2.1)); System.out.println("Format with NaN : " + fmt.format(Double.NaN)); System.out.println("Format with +INF : " + fmt.format(Double.POSITIVE_INFINITY));
Format with -INF : is negative Format with -1.0 : is negative Format with 0 : is zero or fraction Format with 0.9 : is zero or fraction Format with 1.0 : is one Format with 1.5 : is 1+ Format with 2 : is two Format with 2.1 : is more than 2. Format with NaN : is negative Format with +INF : is more than 2.
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.
NumberFormat.Field, NumberFormat.Style
FRACTION_FIELD, INTEGER_FIELD
Constructor | Description |
---|---|
ChoiceFormat |
Constructs with the limits and the corresponding formats. |
ChoiceFormat |
Constructs with limits and corresponding formats based on the pattern. |
Modifier and Type | Method | Description |
---|---|---|
void |
applyPattern |
Sets the pattern. |
Object |
clone() |
Overrides Cloneable |
boolean |
equals |
Equality comparison between two |
StringBuffer |
format |
Returns pattern with formatted double. |
StringBuffer |
format |
Specialization of format. |
Object[] |
getFormats() |
Get the formats passed in the constructor. |
double[] |
getLimits() |
Get the limits passed in the constructor. |
int |
hashCode() |
Generates a hash code for the message format object. |
static final double |
nextDouble |
Finds the least double greater than d . |
static double |
nextDouble |
Finds the least double greater than d (if positive is true ), or the greatest double less than d (if positive is false ). |
Number |
parse |
Parses a Number from the input text. |
static final double |
previousDouble |
Finds the greatest double less than d . |
void |
setChoices |
Set the choices to be used in formatting. |
String |
toPattern() |
Gets the pattern. |
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
format, formatToCharacterIterator, parseObject
public ChoiceFormat(String newPattern)
newPattern
- the new pattern stringNullPointerException
- if newPattern
is null
public ChoiceFormat(double[] limits, String[] formats)
limits
- limits in ascending orderformats
- corresponding format stringsNullPointerException
- if limits
or formats
is null
public void applyPattern(String newPattern)
newPattern
- See the class description.NullPointerException
- if newPattern
is null
public String toPattern()
public void setChoices(double[] limits, String[] formats)
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.NullPointerException
- if limits
or formats
is null
public double[] getLimits()
public Object[] getFormats()
public StringBuffer format(long number, StringBuffer toAppendTo, FieldPosition status)
format(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.format
in class NumberFormat
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 number 123456789
in Locale.US
locale, if the given fieldPosition
is NumberFormat.INTEGER_FIELD
, the begin index and end index of fieldPosition
will be set to 0 and 11, respectively for the output string 123,456,789
.public StringBuffer format(double number, StringBuffer toAppendTo, FieldPosition status)
format
in class NumberFormat
number
- number to be formatted and substituted.toAppendTo
- where text is appended.status
- ignore no useful status is returned.NullPointerException
- if toAppendTo
is null
public Number parse(String text, ParsePosition status)
parse
in class NumberFormat
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.NullPointerException
- if status
is null
or if text
is null
and the list of choice strings is not empty.public static final double nextDouble(double d)
d
. If NaN
, returns same value. Used to make half-open intervals.
Math.nextUp(d)
d
- the reference valued
public static final double previousDouble(double d)
d
. If NaN
, returns same value.Math.nextDown(d)
d
- the reference valued
public Object clone()
clone
in class NumberFormat
public int hashCode()
hashCode
in class NumberFormat
public boolean equals(Object obj)
equals
in class NumberFormat
obj
- the reference object with which to compare.true
if this object is the same as the obj argument; false
otherwise.public static double nextDouble(double d, boolean positive)
d
(if positive
is true
), or the greatest double less than d
(if positive
is false
). If NaN
, returns same value.positive ? Math.nextUp(d) : Math.nextDown(d)
d
- the reference valuepositive
- true
if the least double is desired; false
otherwise
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/text/ChoiceFormat.html