Summary

There is a discrepancy between Formatter and DecimalFormat when rounding doubles. To prevent behavioral compatibility issues, instead of aligning the classes, expand the DecimalFormat rounding section to provide greater specification details.

Problem

There are behavioral differences when formatting doubles between Formatter and DecimalFormat. This stems from JDK-7131459 which was a change made to DecimalFormat to use the old implementation of Double.toString() which was modified to not double round.

For example, (JDK22 EA)

var df = new DecimalFormat("0.00000");
df.setRoundingMode(RoundingMode.HALF_UP);
df.format(0.002485); // returns  "0.00248"
String.format("%.5f", 0.002485); // returns  "0.00249"

As this behavior has been consistent for 10+years now, it is safest from a compatibility standpoint to not align the classes. Rather, the specification of DecimalFormat regarding rounding needs to be greatly expanded on, as it is currently only,

DecimalFormat provides rounding modes defined in RoundingMode for formatting. By default, it uses RoundingMode.HALF_EVEN.

This allows users to know what behavior is expected while formatting doubles requiring rounding.

Solution

Add the following sub-sections which address ambiguous rounding behavior:

Rounding Mode - Elaborate on implications of certain rounding modes (UP, CEILING, and FLOOR).

Rounding Doubles - Elaborate on how rounding is done, that is, it is a decimal floating-point format that rounds after making a binary to String conversion. This should address the many false bug reports filed against DecimalFormat where users believe the output is wrong, as they believe the numerical String value is the basis of rounding, instead of the decimal floating-point value of the double.

Precision (Binary to Decimal Conversion) - Explains the precision of DecimalFormat, which is equivalent to Double.toString(). There currently exists no specification that mentions the limit of how precise a double can be formatted to. The proposed specification provides an example of the ambiguous behavior.

Specification

Replace

 * {@code DecimalFormat} provides rounding modes defined in
 * {@link java.math.RoundingMode} for formatting.  By default, it uses
 * {@link java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}.

with

 * <p> <b>Rounding Modes</b>
 *
 * <p> {@code DecimalFormat} provides rounding modes defined in
 * {@link java.math.RoundingMode} for formatting. By default, it uses
 * {@link java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}. It should be
 * noted that the following rounding modes: {@link java.math.RoundingMode#UP
 * RoundingMode.UP}, {@link java.math.RoundingMode#CEILING RoundingMode.CEILING},
 * and {@link java.math.RoundingMode#FLOOR RoundingMode.FLOOR} have stipulations
 * that prevent the loss of magnitude when rounding under certain circumstances.
 *
 * <p>For example,
 * {@snippet lang=java :
 *     DecimalFormat df = new DecimalFormat("0.00");
 *     df.setRoundingMode(RoundingMode.UP);
 *     df.format(0.000001); // returns "0.01"
 *     df.setRoundingMode(RoundingMode.HALF_UP);
 *     df.format(0.000001); // returns "0.00"
 * }
 *
 * <p> <b>Rounding Doubles</b>
 *
 * <p> {@code DecimalFormat}, when formatting doubles, is a decimal floating-point format
 * which rounds a {@code double} to a {@code String} value that represents the
 * sign and magnitude of the argument.
 *
 * <p> When rounding with a {@code double} represented by the numerical value X,
 * rounding is done using the nearest floating-point approximation for X. When the
 * exact value is a representable number, the exact number is used for rounding.
 * Otherwise, either of the two decimal floating-point values which bracket the
 * exact result may be returned and used as the basis for rounding.
 *
 * <p> Consider the following example,
 * {@snippet lang=java :
 *     DecimalFormat df = new DecimalFormat("0.00000");
 *     df.setRoundingMode(RoundingMode.HALF_UP);
 *     df.format(0.002485); // returns "0.00248"
 * }
 *
 * <p> When rounding with the numerical value {@code 0.002485}, one might expect
 * a formatted value of {@code "0.00249"}. However, since rounding occurs under
 * a floating-point format, the nearest double given by the
 * decimal floating-point value {@code 0.00248499999999999979585774134704934112
 * 96047270298004150390625} is used. Rounding this value to 5 fractional digits
 * gives {@code "0.00248"}, since {@code "0.0024849..."} under {@code RoundingMode.HALF_UP}
 * rounds down.
 *
 * <p> <b>Precision (Binary to Decimal Conversion)</b>
 *
 * <p> To round under a decimal-floating point format, a binary to {@code String}
 * conversion is done. {@code DecimalFormat} does not
 * round using the exact decimal expansion and thus does not have the precision
 * provided by {@link BigDecimal#BigDecimal(double)}.
 * @implNote
 * The default implementation performs the binary to {@code String} conversion using
 * {@link Double#toString(double)}. As such, fractional precision of formatted
 * values will only go up to that of the fractional precision provided by {@code
 * toString(double)}, even if the pattern set is higher.
 *
 * <p> For example,
 * {@snippet lang=java :
 *     // A pattern with a minimum of 30 fractional digits
 *     DecimalFormat df = new DecimalFormat("0.000000000000000000000000000000");
 *     // Format a double approximated by a numerical value with 24 fractional digits
 *     df.format(0.248524852485248524852485); // returns "0.248524852485248530000000000000"
 *     // For reference
 *     new BigDecimal(0.248524852485248524852485); // returns 0.248524852485248526345884556576493196189403533935546875
 * }