Package 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

  • Constructor Details

    • 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 Details

    • 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)
      Returns the double value which is closest to the specified double but larger.
      Parameters:
      value - a double value.
      Returns:
      the next larger double value.

    • nextDouble

      public 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.
      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.

    • 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)
      Returns the double value which is closest to the specified double but smaller.
      Parameters:
      value - a double value.
      Returns:
      the next smaller double value.

    • 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.