java.text.ChoiceFormat

java.text.ChoiceFormat

public class java.text.ChoiceFormat extends java.text.NumberFormat
since: ???
implemented interfaces: java.lang.Cloneable, java.io.Serializable
see also: java.text.DecimalFormat, java.text.MessageFormat
constructors: [java.text.ChoiceFormat(double limits, String formats)|ChoiceFormat(double limits, String formats)], ChoiceFormat(String newPattern)
methods: applyPattern(String newPattern), clone(), equals(Object obj), format(double number, StringBuffer toAppendTo, FieldPosition status), format(long number, StringBuffer toAppendTo, FieldPosition status), getFormats(), getLimits(), hashCode(), nextDouble(double d), nextDouble(double d, boolean positive), parse(String text, ParsePosition status), previousDouble(double d), [java.text.ChoiceFormat.setChoices(double limits, String formats)|setChoices(double limits, String formats)], toPattern()

A 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:

X matches j if and only if limit[j] <= X < limit[j+1]

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 accepts \\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,

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.)
Here is a simple example that shows formatting and parsing:

double[] limits = {1,2,3,4,5,6,7};
String[] monthNames = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"};
ChoiceFormat form = new ChoiceFormat(limits, monthNames);
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));
}

Here is a more complex example, with a pattern format:
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] = new Integer(i);
testArgs[2] = testArgs[0];
System.out.println(pattform.format(testArgs));
}

Specifying a pattern for ChoiceFormat objects is fairly straightforward. For example:

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));

And the output result would be like the following:

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.

source: Sun's Java documentation for JDK 1.3
Sun Microsystems: www.sun.com   |   Sun's Java: java.sun.com   |   JDK 1.3 API docs: http://java.sun.com/j2se/1.3/docs/api/index.html