public class

ChoiceFormat

extends NumberFormat
java.lang.Object
   ↳ java.text.Format
     ↳ java.text.NumberFormat
       ↳ java.text.ChoiceFormat

Class Overview

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.

Summary

[Expand]
Inherited Constants
From class java.text.NumberFormat
Public Constructors
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.
Public Methods
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.
final static double nextDouble(double value)
Returns the double value which is closest to the specified double but larger.
static double nextDouble(double value, boolean increment)
Returns the double value which is closest to the specified double but either larger or smaller as specified.
Number parse(String string, ParsePosition position)
Parses a double from the specified string starting at the index specified by position.
final static double previousDouble(double value)
Returns the double value which is closest to the specified double but smaller.
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.
[Expand]
Inherited Methods
From class java.text.NumberFormat
From class java.text.Format
From class java.lang.Object

Public Constructors

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

Since: API Level 1

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.

public ChoiceFormat (String template)

Since: API Level 1

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.

Public Methods

public void applyPattern (String template)

Since: API Level 1

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.

public Object clone ()

Since: API Level 1

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

Returns
  • a shallow copy of this ChoiceFormat.
See Also

public boolean equals (Object object)

Since: API Level 1

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.

Parameters
object the object to compare with this instance.
Returns
  • true if the specified object is equal to this instance; false otherwise.
See Also

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

Since: API Level 1

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

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.

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

Since: API Level 1

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

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.

public Object[] getFormats ()

Since: API Level 1

Returns the strings associated with the ranges of this ChoiceFormat.

Returns
  • an array of format strings.

public double[] getLimits ()

Since: API Level 1

Returns the limits of this ChoiceFormat.

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

public int hashCode ()

Since: API Level 1

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

Returns
  • the receiver's hash.
See Also

public static final double nextDouble (double value)

Since: API Level 1

Returns the double value which is closest to the specified double but larger.

Parameters
value a double value.
Returns
  • the next larger double value.

public static double nextDouble (double value, boolean increment)

Since: API Level 1

Returns the double value which is closest to the specified double but either larger or smaller as specified.

Parameters
value a double value.
increment true to get the next larger value, false to get the previous smaller value.
Returns
  • the next larger or smaller double value.

public Number parse (String string, ParsePosition position)

Since: API Level 1

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.

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

public static final double previousDouble (double value)

Since: API Level 1

Returns the double value which is closest to the specified double but smaller.

Parameters
value a double value.
Returns
  • the next smaller double value.

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

Since: API Level 1

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.

public String toPattern ()

Since: API Level 1

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

Returns
  • the pattern.