Summary

Clarify an undocumented ArrayIndexOutOfBoundsException in ChoiceFormat::format.

Problem

A ChoiceFormat can be created either through applyPattern() or setChoices() (which the constructors call). These setter methods set the instance variables, limits and formats. In both cases, it is possible to create limits and formats that are empty. When this is done, calling format() on the constructed ChoiceFormat will throw an undocumented ArrayIndexOutOfBoundsException.

For example,

var a = new ChoiceFormat(""); // calls applyPattern()
a.format(0); // throws an unexpected ArrayIndexOutOfBoundsException
var b = new ChoiceFormat(new double[]{}, new String[]{}); // calls setChoices()
b.format(0); // throws an unexpected ArrayIndexOutOfBoundsException

Solution

Make it apparent that the default implementation throws an ArrayIndexOutOfBoundsException when calling both the ChoiceFormat::format methods with empty limits and formats.

Preferably an IllegalArgumentException should have been called during the invocation of the setter methods. However, this cannot be done due to compatibility reasons. Since ChoiceFormat is likely not sub-classed much in practice, this exception should apply to all implementations (no usage of implSpec).

Specification

Adjust the long format as such

     /**
      * Specialization of format. This method really calls
-     * {@code format(double, StringBuffer, FieldPosition)}
-     * thus the range of longs that are supported is only equal to
+     * {@link #format(double, StringBuffer, FieldPosition)}.
+     * Thus, the range of longs that are supported is only equal to
      * the range that can be stored by double. This will never be
      * a practical limitation.
+     *
+     * @param number number to be formatted and substituted.
+     * @param toAppendTo where text is appended.
+     * @param status ignore no useful status is returned.
+     * @throws    ArrayIndexOutOfBoundsException if either the {@code limits}
+     *            or {@code formats} of this ChoiceFormat are empty
+     * @throws    NullPointerException if {@code toAppendTo}
+     *            is {@code null}
      */

Adjust the double format as such

     /**
      * Returns pattern with formatted double.
+     *
      * @param number number to be formatted and substituted.
      * @param toAppendTo where text is appended.
      * @param status ignore no useful status is returned.
+     * @throws    ArrayIndexOutOfBoundsException if either the {@code limits}
+     *            or {@code formats} of this ChoiceFormat are empty
      * @throws    NullPointerException if {@code toAppendTo}
      *            is {@code null}
      */