Android APIs
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(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.
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.
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, boolean increment)
Equivalent to nextUp(double) if increment == true, and nextAfter(double, double) with direction == Double.NEGATIVE_INFINITY otherwise.
final static double nextDouble(double value)
Equivalent to nextUp(double).
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)
Equivalent to 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.
[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)

Added in 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 double: an array of doubles in ascending order. The lowest and highest possible values are negative and positive infinity.
formats String: 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)

Added in API level 1

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

Parameters
template String: the pattern of strings and ranges.
Throws
IllegalArgumentException if an error occurs while parsing the pattern.

Public Methods

public void applyPattern (String template)

Added in API level 1

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

Parameters
template String: the pattern of strings and ranges.
Throws
IllegalArgumentException if an error occurs while parsing the pattern.

public Object clone ()

Added in API level 1

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

Returns
Object a shallow copy of this ChoiceFormat.

See also:

public boolean equals (Object object)

Added in 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 Object: the object to compare with this instance.
Returns
boolean true if the specified object is equal to this instance; false otherwise.

See also:

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

Added in API level 1

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

Parameters
value long: the long to format.
buffer StringBuffer: the target string buffer to append the formatted value to.
field FieldPosition: a FieldPosition which is ignored.
Returns
StringBuffer the string buffer.

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

Added in API level 1

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

Parameters
value double: the double to format.
buffer StringBuffer: the target string buffer to append the formatted value to.
field FieldPosition: a FieldPosition which is ignored.
Returns
StringBuffer the string buffer.

public Object[] getFormats ()

Added in API level 1

Returns the strings associated with the ranges of this ChoiceFormat.

Returns
Object[] an array of format strings.

public double[] getLimits ()

Added in API level 1

Returns the limits of this ChoiceFormat.

Returns
double[] the array of doubles which make up the limits of this ChoiceFormat.

public int hashCode ()

Added in API level 1

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

Returns
int the receiver's hash.

See also:

public static double nextDouble (double value, boolean increment)

Added in API level 1

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

Parameters
value double
increment boolean
Returns
double

public static final double nextDouble (double value)

Added in API level 1

Equivalent to nextUp(double).

Parameters
value double
Returns
double

public Number parse (String string, ParsePosition position)

Added in 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 String: the source string to parse.
position ParsePosition: 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
Number a Double resulting from the parse, or Double.NaN if there is an error

public static final double previousDouble (double value)

Added in API level 1

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

Parameters
value double
Returns
double

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

Added in 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 double: an array of doubles in ascending order. The lowest and highest possible values are negative and positive infinity.
formats String: 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 ()

Added in API level 1

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

Returns
String the pattern.