java.text
Class ChoiceFormat

java.lang.Object
  extended by java.text.Format
      extended by java.text.NumberFormat
          extended by java.text.ChoiceFormat
All Implemented Interfaces:
Serializable, Cloneable

public class ChoiceFormat
extends NumberFormat

This class allows a format to be specified based on a range of numbers. To use this class, first specify two lists of formats and range terminators. These lists must be arrays of equal length. The format of index i will be selected for value X if terminator[i] <= X < limit[i + 1]. If the value X is not included in any range, then either the first or last format will be used depending on whether the value X falls outside the range.

This sounds complicated, but that is because I did a poor job of explaining it. Consider the following example:

terminators = { 1, ChoiceFormat.nextDouble(1) }
formats = { "file", "files" }

In this case if the actual number tested is one or less, then the word "file" is used as the format value. If the number tested is greater than one, then "files" is used. This allows plurals to be handled gracefully. Note the use of the method nextDouble. This method selects the next highest double number than its argument. This effectively makes any double greater than 1.0 cause the "files" string to be selected. (Note that all terminator values are specified as doubles.

Note that in order for this class to work properly, the range terminator array must be sorted in ascending order and the format string array must be the same length as the terminator array.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class java.text.NumberFormat
NumberFormat.Field
 
Field Summary
 
Fields inherited from class java.text.NumberFormat
FRACTION_FIELD, INTEGER_FIELD
 
Constructor Summary
ChoiceFormat(double[] choiceLimits, String[] choiceFormats)
          This method initializes a new instance of ChoiceFormat that will use the specified range terminators and format strings.
ChoiceFormat(String newPattern)
          This method initializes a new instance of ChoiceFormat that generates its range terminator and format string arrays from the specified pattern.
 
Method Summary
 void applyPattern(String newPattern)
          This method sets new range terminators and format strings for this object based on the specified pattern.
 boolean equals(Object obj)
          This method tests this object for equality with the specified object.
 StringBuffer format(double num, StringBuffer appendBuf, FieldPosition pos)
          This method appends the appropriate format string to the specified StringBuffer based on the supplied double argument.
 StringBuffer format(long num, StringBuffer appendBuf, FieldPosition pos)
          This method appends the appropriate format string to the specified StringBuffer based on the supplied long argument.
 Object[] getFormats()
          This method returns the list of format strings in use.
 double[] getLimits()
          This method returns the list of range terminators in use.
 int hashCode()
          This method returns a hash value for this object
static double nextDouble(double d)
          This method returns the lowest possible double greater than the specified double.
static double nextDouble(double d, boolean next)
          This method returns a double that is either the next highest double or next lowest double compared to the specified double depending on the value of the passed boolean parameter.
 Number parse(String sourceStr, ParsePosition pos)
          I'm not sure what this method is really supposed to do, as it is not documented.
static double previousDouble(double d)
          This method returns the highest possible double less than the specified double.
 void setChoices(double[] choiceLimits, String[] choiceFormats)
          This method sets new range terminators and format strings for this object.
 String toPattern()
          This method returns the range terminator list and format string list as a String suitable for using with the applyPattern method.
 
Methods inherited from class java.text.NumberFormat
format, format, format, getAvailableLocales, getCurrency, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getMaximumFractionDigits, getMaximumIntegerDigits, getMinimumFractionDigits, getMinimumIntegerDigits, getNumberInstance, getNumberInstance, getPercentInstance, getPercentInstance, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setCurrency, setGroupingUsed, setMaximumFractionDigits, setMaximumIntegerDigits, setMinimumFractionDigits, setMinimumIntegerDigits, setParseIntegerOnly
 
Methods inherited from class java.text.Format
clone, format, formatToCharacterIterator, parseObject
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ChoiceFormat

public ChoiceFormat(String newPattern)
This method initializes a new instance of ChoiceFormat that generates its range terminator and format string arrays from the specified pattern. This pattern is of the form "term#string|term#string...". For example "1#Sunday|2#Monday|#Tuesday". This is the same pattern type used by the applyPattern method.

Parameters:
newPattern - The pattern of terminators and format strings.
Throws:
IllegalArgumentException - If the pattern is not valid

ChoiceFormat

public ChoiceFormat(double[] choiceLimits,
                    String[] choiceFormats)
This method initializes a new instance of ChoiceFormat that will use the specified range terminators and format strings.

Parameters:
choiceLimits - The array of range terminators
choiceFormats - The array of format strings
Method Detail

applyPattern

public void applyPattern(String newPattern)
This method sets new range terminators and format strings for this object based on the specified pattern. This pattern is of the form "term#string|term#string...". For example "1#Sunday|2#Monday|#Tuesday".

Parameters:
newPattern - The pattern of terminators and format strings.
Throws:
IllegalArgumentException - If the pattern is not valid

equals

public boolean equals(Object obj)
This method tests this object for equality with the specified object. This will be true if and only if:

Overrides:
equals in class NumberFormat
Parameters:
obj - The object to test for equality against.
Returns:
true if the specified object is equal to this one, false otherwise.
See Also:
Object.hashCode()

format

public StringBuffer format(long num,
                           StringBuffer appendBuf,
                           FieldPosition pos)
This method appends the appropriate format string to the specified StringBuffer based on the supplied long argument.

Specified by:
format in class NumberFormat
Parameters:
num - The number used for determine (based on the range terminators) which format string to append.
appendBuf - The StringBuffer to append the format string to.
pos - Unused.
Returns:
The StringBuffer with the format string appended.

format

public StringBuffer format(double num,
                           StringBuffer appendBuf,
                           FieldPosition pos)
This method appends the appropriate format string to the specified StringBuffer based on the supplied double argument.

Specified by:
format in class NumberFormat
Parameters:
num - The number used for determine (based on the range terminators) which format string to append.
appendBuf - The StringBuffer to append the format string to.
pos - Unused.
Returns:
The StringBuffer with the format string appended.

getFormats

public Object[] getFormats()
This method returns the list of format strings in use.

Returns:
The list of format objects.

getLimits

public double[] getLimits()
This method returns the list of range terminators in use.

Returns:
The list of range terminators.

hashCode

public int hashCode()
This method returns a hash value for this object

Overrides:
hashCode in class NumberFormat
Returns:
A hash value for this object.
See Also:
Object.equals(Object), System.identityHashCode(Object)

nextDouble

public static final double nextDouble(double d)
This method returns the lowest possible double greater than the specified double. If the specified double value is equal to Double.NaN then that is the value returned.

Parameters:
d - The specified double
Returns:
The lowest double value greater than the specified double.

nextDouble

public static double nextDouble(double d,
                                boolean next)
This method returns a double that is either the next highest double or next lowest double compared to the specified double depending on the value of the passed boolean parameter. If the boolean parameter is true, then the lowest possible double greater than the specified double will be returned. Otherwise the highest possible double less than the specified double will be returned.

Parameters:
d - The specified double
next - true to return the next highest double, false otherwise.
Returns:
The next highest or lowest double value.

parse

public Number parse(String sourceStr,
                    ParsePosition pos)
I'm not sure what this method is really supposed to do, as it is not documented.

Specified by:
parse in class NumberFormat
Parameters:
sourceStr - The string to parse.
pos - The desired ParsePosition.
Returns:
The parsed Number

previousDouble

public static final double previousDouble(double d)
This method returns the highest possible double less than the specified double. If the specified double value is equal to Double.NaN then that is the value returned.

Parameters:
d - The specified double
Returns:
The highest double value less than the specified double.

setChoices

public void setChoices(double[] choiceLimits,
                       String[] choiceFormats)
This method sets new range terminators and format strings for this object.

Parameters:
choiceLimits - The new range terminators
choiceFormats - The new choice formats

toPattern

public String toPattern()
This method returns the range terminator list and format string list as a String suitable for using with the applyPattern method.

Returns:
A pattern string for this object