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 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
ConstructorsConstructorDescriptionChoiceFormat(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 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.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, setRoundingModeMethods 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 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- ifnewPatternisnullIllegalArgumentException- ifnewPatternviolates 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- iflimitsorformatsisnullIllegalArgumentException- if the length oflimitsandformatsare not equal- See Also:
-
-
Method Details
-
applyPattern
Apply 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- ifnewPatternisnullIllegalArgumentException- ifnewPatternviolates the pattern syntax- See Also:
-
toPattern
Returns 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:
-
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- iflimitsorformatsisnullIllegalArgumentException- if the length oflimitsandformatsare 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:
formatin 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:
ArrayIndexOutOfBoundsException- if either thelimitsorformatsof this ChoiceFormat are emptyNullPointerException- iftoAppendToisnull- See Also:
-
format
Returns pattern with formatted double.- Specified by:
formatin 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:
ArrayIndexOutOfBoundsException- if either thelimitsorformatsof this ChoiceFormat are emptyNullPointerException- iftoAppendToisnull- See Also:
-
parse
Parses a Number from the input text.- Specified by:
parsein 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- ifstatusisnullor iftextisnulland the list of choice strings is not empty.- See Also:
-
isStrict
public boolean isStrict()Description copied from class:NumberFormatReturnstrueif this format will parse numbers strictly;falseotherwise.- Overrides:
isStrictin classNumberFormat- Returns:
trueif this format will parse numbers strictly;falseotherwise- Since:
- 23
- See Also:
-
setStrict
public 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 classNumberFormat- Parameters:
strict-trueif parsing should be done strictly;falseotherwise- Since:
- 23
- 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:
-
nextDouble
public 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 valuepositive-trueif the least double is desired;falseotherwise- Returns:
- the least or greater double value
-
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:
clonein classNumberFormat- Returns:
- a clone of this instance.
- See Also:
-
hashCode
public int hashCode()Returns the hash code for thisChoiceFormat.- Overrides:
hashCodein 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:
-
toString
-
equals
Compares 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 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:
trueif the specified object is equal to thisChoiceFormat- See Also:
-