java.text

Class ChoiceFormat

java.lang.Object

java.text.Format

java.text.NumberFormat

java.text.ChoiceFormat

All Implemented Interfaces:

Serializable, Cloneable

public class ChoiceFormat
extends NumberFormat

Returns a fixed string based on a numeric value. The class can be used in conjunction with the MessageFormat class to handle plurals in messages. ChoiceFormat enables users to attach a format to a range of numbers. The choice is specified with an ascending list of doubles, where each item specifies a half-open interval up to the next item as in the following: 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. The first or last index is used depending on whether the number is too low or too high. The length of the format array must be the same as the length of the limits array.

Examples:

 double[] limits = {1, 2, 3, 4, 5, 6, 7};
 String[] fmts = {"Sun", "Mon", "Tue", "Wed", "Thur", "Fri", "Sat"};

 double[] limits2 = {0, 1, ChoiceFormat.nextDouble(1)};
 String[] fmts2 = {"no files", "one file", "many files"};
 

ChoiceFormat.nextDouble(double) allows to get the double following the one passed to the method. This is used to create half open intervals.

ChoiceFormat objects also may be converted to and from patterns. The conversion can be done programmatically, as in the example above, or by using a pattern like the following:

 "1#Sun|2#Mon|3#Tue|4#Wed|5#Thur|6#Fri|7#Sat"
 "0#are no files|1#is one file|1<are many files"
 

where:

• "#" specifies an inclusive limit value;
• "<" specifies an exclusive limit value.

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

Constructors

Constructor and Description
ChoiceFormat(double[] limits, String[] formats) Constructs a new ChoiceFormat with the specified double values and associated strings.
ChoiceFormat(String template) Constructs a new ChoiceFormat with the strings and limits parsed from the specified pattern.

Method Summary

Modifier and Type	Method and Description
void	applyPattern(String template) Parses the pattern to determine new strings and ranges for this ChoiceFormat.
Object	clone() Returns a new instance of ChoiceFormat with the same ranges and strings as this ChoiceFormat.
boolean	equals(Object object) Compares the specified object with this ChoiceFormat.
StringBuffer	format(double value, StringBuffer buffer, FieldPosition field) Appends the string associated with the range in which the specified double value fits to the specified string buffer.
StringBuffer	format(long value, StringBuffer buffer, FieldPosition field) Appends the string associated with the range in which the specified long value fits to the specified string buffer.
Object[]	getFormats() Returns the strings associated with the ranges of this ChoiceFormat.
double[]	getLimits() Returns the limits of this ChoiceFormat.
int	hashCode() Returns an integer hash code for the receiver.
static double	nextDouble(double value) Equivalent to Math.nextUp(double).
static double	nextDouble(double value, boolean increment) Equivalent to Math.nextUp(double) if increment == true, and Math.nextAfter(double, double) with direction == Double.NEGATIVE_INFINITY otherwise.
Number	parse(String string, ParsePosition position) Parses a double from the specified string starting at the index specified by position.
static double	previousDouble(double value) Equivalent to Math.nextAfter(double, double) with direction == Double.NEGATIVE_INFINITY.
void	setChoices(double[] limits, String[] formats) Sets the double values and associated strings of this ChoiceFormat.
String	toPattern() Returns the pattern of this ChoiceFormat which specifies the ranges and their associated strings.

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, getRoundingMode, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setCurrency, setGroupingUsed, setMaximumFractionDigits, setMaximumIntegerDigits, setMinimumFractionDigits, setMinimumIntegerDigits, setParseIntegerOnly, setRoundingMode

Methods inherited from class java.text.Format

format, formatToCharacterIterator, parseObject

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ChoiceFormat

public ChoiceFormat(double[] limits,
                    String[] formats)

Constructs a new ChoiceFormat with the specified double values and associated strings. When calling format with a double value d, then the element i in formats is selected where i fulfills limits[i] <= d < limits[i+1].

The length of the limits and formats arrays must be the same.

Parameters:

limits - an array of doubles in ascending order. The lowest and highest possible values are negative and positive infinity.

formats - the strings associated with the ranges defined through limits. The lower bound of the associated range is at the same index as the string.

ChoiceFormat

public ChoiceFormat(String template)

Constructs a new ChoiceFormat with the strings and limits parsed from the specified pattern.

Parameters:

template - the pattern of strings and ranges.

Throws:

IllegalArgumentException - if an error occurs while parsing the pattern.

Method Detail

applyPattern

public void applyPattern(String template)

Parses the pattern to determine new strings and ranges for this ChoiceFormat.

Parameters:

template - the pattern of strings and ranges.

Throws:

IllegalArgumentException - if an error occurs while parsing the pattern.

clone

public Object clone()

Returns a new instance of ChoiceFormat with the same ranges and strings as this ChoiceFormat.

Overrides:

clone in class NumberFormat

Returns:

a shallow copy of this ChoiceFormat.

See Also:

Cloneable

equals

public boolean equals(Object object)

Compares the specified object with this ChoiceFormat. The object must be an instance of ChoiceFormat and have the same limits and formats to be equal to this instance.

Overrides:

equals in class NumberFormat

Parameters:

object - the object to compare with this instance.

Returns:

true if the specified object is equal to this instance; false otherwise.

See Also:

hashCode()

format

public StringBuffer format(double value,
                           StringBuffer buffer,
                           FieldPosition field)

Appends the string associated with the range in which the specified double value fits to the specified string buffer.

Specified by:

format in class NumberFormat

Parameters:

value - the double to format.

buffer - the target string buffer to append the formatted value to.

field - a FieldPosition which is ignored.

Returns:

the string buffer.

format

public StringBuffer format(long value,
                           StringBuffer buffer,
                           FieldPosition field)

Appends the string associated with the range in which the specified long value fits to the specified string buffer.

Specified by:

format in class NumberFormat

Parameters:

value - the long to format.

buffer - the target string buffer to append the formatted value to.

field - a FieldPosition which is ignored.

Returns:

the string buffer.

getFormats

public Object[] getFormats()

Returns the strings associated with the ranges of this ChoiceFormat.

Returns:

an array of format strings.

getLimits

public double[] getLimits()

Returns the limits of this ChoiceFormat.

Returns:

the array of doubles which make up the limits of this ChoiceFormat.

hashCode

public int hashCode()

Returns an integer hash code for the receiver. Objects which are equal return the same value for this method.

Overrides:

hashCode in class NumberFormat

Returns:

the receiver's hash.

See Also:

equals(java.lang.Object)

nextDouble

public static final double nextDouble(double value)

Equivalent to Math.nextUp(double).

nextDouble

public static double nextDouble(double value,
                                boolean increment)

Equivalent to Math.nextUp(double) if increment == true, and Math.nextAfter(double, double) with direction == Double.NEGATIVE_INFINITY otherwise.

parse

public Number parse(String string,
                    ParsePosition position)

Parses a double from the specified string starting at the index specified by position. The string is compared to the strings of this ChoiceFormat and if a match occurs then the lower bound of the corresponding range in the limits array is returned. If the string is successfully parsed then the index of the ParsePosition passed to this method is updated to the index following the parsed text.

If one of the format strings of this ChoiceFormat instance is found in string starting at position.getIndex() then

• the index in position is set to the index following the parsed text;
• the Double corresponding to the format string is returned.

If none of the format strings is found in string then

• the error index in position is set to the current index in position;
• Double.NaN is returned.

Specified by:

parse in class NumberFormat

Parameters:

string - the source string to parse.

position - input/output parameter, specifies the start index in string from where to start parsing. See the Returns section for a description of the output values.

Returns:

a Double resulting from the parse, or Double.NaN if there is an error

previousDouble

public static final double previousDouble(double value)

Equivalent to Math.nextAfter(double, double) with direction == Double.NEGATIVE_INFINITY.

setChoices

public void setChoices(double[] limits,
                       String[] formats)

Sets the double values and associated strings of this ChoiceFormat. When calling format with a double value d, then the element i in formats is selected where i fulfills limits[i] <= d < limits[i+1].

The length of the limits and formats arrays must be the same.

Parameters:

limits - an array of doubles in ascending order. The lowest and highest possible values are negative and positive infinity.

formats - the strings associated with the ranges defined through limits. The lower bound of the associated range is at the same index as the string.

toPattern

public String toPattern()

Returns the pattern of this ChoiceFormat which specifies the ranges and their associated strings.

Returns:

the pattern.