This class is a subclass of Format that converts a number to a String in a way reminiscent of a switch statement or an enumerated type. Each ChoiceFormat object has an array of doubles known as its limits and an array of strings known as its formats. When the format( ) method is called to format a number x, the ChoiceFormat finds an index i such that:

limits[i] <= x < limits[i+1]

If x is less than the first element of the array, the first element is used, and if it is greater than the last, the last element is used. Once the index i has been determined, it is used as the index into the array of strings, and the indexed string is returned as the result of the format( ) method.

A ChoiceFormat object may also be created by encoding its limits and formats into a single string known as its pattern. A typical pattern looks like the one below, used to return the singular or plural form of a word based on the numeric value passed to the format( ) method:

ChoiceFormat cf = new ChoiceFormat("0#errors|1#error|2#errors");

A ChoiceFormat object created in this way returns the string "errors" when it formats the number 0 or any number greater than or equal to 2. It returns "error" when it formats the number 1. In the syntax shown here, note the pound sign (#) used to separate the limit number from the string that corresponds to that case and the vertical bar (|) used to separate the individual cases. You can use the applyPattern( ) method to change the pattern used by a ChoiceFormat object; use toPattern( ) to query the pattern it uses.

Figure 15-4. java.text.ChoiceFormat

public class ChoiceFormat extends NumberFormat {
// Public Constructors
     public ChoiceFormat(String newPattern);  
     public ChoiceFormat(double[ ] limits, String[ ] formats);  
// Public Class Methods
     public static final double nextDouble(double d);  
     public static double nextDouble(double d, boolean positive);  
     public static final double previousDouble(double d);  
// Public Instance Methods
     public void applyPattern(String newPattern);  
     public Object[ ] getFormats( );  
     public double[ ] getLimits( );  
     public void setChoices(double[ ] limits, String[ ] formats);  
     public String toPattern( );  
// Public Methods Overriding NumberFormat
     public Object clone( );  
     public boolean equals(Object obj);  
     public StringBuffer format(long number, StringBuffer toAppendTo, 
        FieldPosition status);  
     public StringBuffer format(double number, StringBuffer toAppendTo, 
        FieldPosition status);  
     public int hashCode( );  
     public Number parse(String text, ParsePosition status);  
}