Class ChoiceFormat
- 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.
 
Patterns
AChoiceFormat pattern has the following syntax:
 Note:The relation ≤ is not equivalent to <=
- Pattern:
- SubPattern *("|" SubPattern)
- SubPattern:
- Limit Relation Format
- Note: Each additional SubPattern must have an ascending Limit-Relation interval
- 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 special pattern character '|'
 To use a reserved special pattern character within a Format pattern,
 it must be single quoted. For example, new ChoiceFormat("1#'|'foo'|'").format(1)
 returns "|foo|".
 Use two single quotes in a row to produce a literal single quote. For example,
 new ChoiceFormat("1# ''one'' ").format(1) returns " 'one' ".
 
Usage Information
 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"}
 (nextDoublecan 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:
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));
}
Below is an example of constructing a ChoiceFormat with a String 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."
 For more sophisticated patterns, ChoiceFormat can be used with
 MessageFormat to produce accurate forms for singular and plural:
 
MessageFormat msgFmt = new MessageFormat("The disk \"{0}\" contains {1}.");
double[] fileLimits = {0,1,2};
String[] filePart = {"no files","one file","{1,number} files"};
ChoiceFormat fileChoices = new ChoiceFormat(fileLimits, filePart);
msgFmt.setFormatByArgumentIndex(1, fileChoices);
Object[] args = {"MyDisk", 1273};
System.out.println(msgFmt.format(args));
fileCount:
 SeeThe disk "MyDisk" contains no files. The disk "MyDisk" contains one file. The disk "MyDisk" contains 1,273 files.
MessageFormat for caveats regarding
 MessageFormat patterns within a ChoiceFormat pattern.
 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.
- API Note:
- A subclass could perform more consistent pattern validation by
 throwing an IllegalArgumentExceptionfor all incorrect cases. See theImplementation Notefor this implementation's behavior regarding incorrect patterns.This class inherits instance methods from NumberFormatit does not utilize; a subclass could override and throwUnsupportedOperationExceptionfor such methods.
- Implementation Note:
- Given an incorrect pattern, this implementation may either
 throw an exception or succeed and discard the incorrect portion. A NumberFormatExceptionis thrown if alimitcan not be parsed as a numeric value and anIllegalArgumentExceptionis thrown if aSubPatternis missing, or the intervals are not ascending. Discarding the incorrect portion may result in a ChoiceFormat with emptylimitsandformats.
- Since:
- 1.1
- See Also:
- 
Nested Class SummaryNested classes/interfaces declared in class java.text.NumberFormatNumberFormat.Field, NumberFormat.Style
- 
Field SummaryFields declared in class java.text.NumberFormatFRACTION_FIELD, INTEGER_FIELD
- 
Constructor SummaryConstructorsConstructorDescriptionChoiceFormat(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 SummaryModifier and TypeMethodDescriptionvoidapplyPattern(String newPattern) Apply the given pattern to this ChoiceFormat object.clone()Overrides CloneablebooleanCompares the specified object with thisChoiceFormatfor 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.inthashCode()Returns the hash code for thisChoiceFormat.booleanisStrict()Returnstrueif this format will parse numbers strictly;falseotherwise.static final doublenextDouble(double d) Finds the least double greater thand.static doublenextDouble(double d, boolean positive) Finds the least double greater thand(ifpositiveistrue), or the greatest double less thand(ifpositiveisfalse).parse(String text, ParsePosition status) Parses a Number from the input text.static final doublepreviousDouble(double d) Finds the greatest double less thand.voidsetChoices(double[] limits, String[] formats) Set the choices to be used in formatting.voidsetStrict(boolean strict) Change the leniency value for parsing.Returns a patternstringthat represents thelimitsandformatsof this ChoiceFormat object.toString()Returns a string identifying thisChoiceFormat, for debugging.Methods declared in class java.text.NumberFormatformat, 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, setRoundingModeMethods declared in class java.text.Formatformat, formatToCharacterIterator, parseObject
- 
Constructor Details- 
ChoiceFormatConstructs a ChoiceFormat with limits and corresponding formats based on the pattern. The syntax and error related caveats for the ChoiceFormat pattern can be found in the Patterns section. UnlikeChoiceFormat(double[], String[]), this constructor will throw anIllegalArgumentExceptionif thelimitsare not in ascending order.- Parameters:
- newPattern- the new pattern string
- Throws:
- NullPointerException- if- newPatternis- null
- IllegalArgumentException- if- newPatternviolates the pattern syntax
- See Also:
 
- 
ChoiceFormatConstructs with the limits and the corresponding formats.- Parameters:
- limits- limits in ascending order
- formats- corresponding format strings
- Throws:
- NullPointerException- if- limitsor- formatsis- null
- IllegalArgumentException- if the length of- limitsand- formatsare not equal
- See Also:
 
 
- 
- 
Method Details- 
applyPatternApply the given pattern to this ChoiceFormat object. The syntax and error related caveats for the ChoiceFormat pattern can be found in the Patterns section. UnlikesetChoices(double[], String[]), this method will throw anIllegalArgumentExceptionif thelimitsare not in ascending order.- Parameters:
- newPattern- a pattern string
- Throws:
- NullPointerException- if- newPatternis- null
- IllegalArgumentException- if- newPatternviolates the pattern syntax
- See Also:
 
- 
toPatternReturns a patternstringthat represents thelimitsandformatsof this ChoiceFormat object. Thestringreturned is not guaranteed to be the same inputstringpassed to eitherapplyPattern(String)orChoiceFormat(String).- Returns:
- a pattern stringthat represents thelimitsandformatsof this ChoiceFormat object
- See Also:
 
- 
setChoicesSet 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- if- limitsor- formatsis- null
- IllegalArgumentException- if the length of- limitsand- formatsare not equal
 
- 
getLimitspublic double[] getLimits()Returns the limits of this ChoiceFormat.- Returns:
- the limits of this ChoiceFormat
 
- 
getFormatsReturns the formats of this ChoiceFormat.- Returns:
- the formats of this ChoiceFormat
 
- 
formatSpecialization 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:
- formatin class- NumberFormat
- 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:
- ArrayIndexOutOfBoundsException- if either the- limitsor- formatsof this ChoiceFormat are empty
- NullPointerException- if- toAppendTois- null
- See Also:
 
- 
formatReturns pattern with formatted double.- Specified by:
- formatin class- NumberFormat
- 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:
- ArrayIndexOutOfBoundsException- if either the- limitsor- formatsof this ChoiceFormat are empty
- NullPointerException- if- toAppendTois- null
- See Also:
 
- 
parseParses a Number from the input text.- Specified by:
- parsein class- NumberFormat
- 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- if- statusis- nullor if- textis- nulland the list of choice strings is not empty.
- See Also:
 
- 
isStrictpublic boolean isStrict()Description copied from class:NumberFormatReturnstrueif this format will parse numbers strictly;falseotherwise.- Overrides:
- isStrictin class- NumberFormat
- Returns:
- trueif this format will parse numbers strictly;- falseotherwise
- Since:
- 23
- See Also:
 
- 
setStrictpublic void setStrict(boolean strict) Description copied from class:NumberFormatChange the leniency value for parsing. Parsing can either be strict or lenient, by default it is lenient.- Overrides:
- setStrictin class- NumberFormat
- Parameters:
- strict-- trueif parsing should be done strictly;- falseotherwise
- Since:
- 23
- See Also:
 
- 
nextDoublepublic 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:
 
- 
nextDoublepublic static double nextDouble(double d, boolean positive) Finds the least double greater thand(ifpositiveistrue), or the greatest double less thand(ifpositiveisfalse). IfNaN, returns same value.- Implementation Note:
- This is equivalent to calling
 positive ? Math.nextUp(d) : Math.nextDown(d)
- Parameters:
- d- the reference value
- positive-- trueif the least double is desired;- falseotherwise
- Returns:
- the least or greater double value
 
- 
previousDoublepublic 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:
 
- 
cloneOverrides Cloneable- Overrides:
- clonein class- NumberFormat
- Returns:
- a clone of this instance.
- See Also:
 
- 
hashCodepublic int hashCode()Returns the hash code for thisChoiceFormat.- Overrides:
- hashCodein class- NumberFormat
- 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:
 
- 
toString
- 
equalsCompares the specified object with thisChoiceFormatfor equality. Returns true if the object is also aChoiceFormatand the two formats would format any value the same.- Overrides:
- equalsin class- NumberFormat
- 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:
- trueif the specified object is equal to this- ChoiceFormat
- See Also:
 
 
-