Summary

Update the specification of Decimal Format's Scientific Notation definition.

Problem

In Decimal Format's Scientific Notation definition, it defines the significant digits in the mantissa as the sum of the minimum integer and maximum fraction digits. It then provides the following example, 12345 formatted with "##0.##E0" is "12.3E3".

Not only is the example wrong, as the actual result is 12.345E3, but the definition for the mantissa is also wrong. Consider the following data which uses JDK21 Decimal Format

12345 formatted by ##0.##E0 is 12.345E3
123456 formatted by ##0.##E0 is 123.46E3
1234567 formatted by ##0.##E0 is 1.2346E6
12345678 formatted by ##0.##E0 is 12.346E6
123456789 formatted by ##0.##E0 is 123.46E6 

Further example data can be seen in the comments of : JDK-8159023

According to the current definition, each number should be formatted to 3 significant digits. In reality, each formatted result actually has 5 significant digits.

Additionally, there is a lack of context for terms, as highlighted by JDK-6282188.

Solution

Firstly, the terms, maximum integer, minimum integer, maximum fraction, and minimum fraction digits should be defined, as they are important to understanding concepts in Decimal Format.

The Scientific Notation section should be updated to contain a definition for the mantissa that reflects the implementation: min(max(minimum pattern digits, significant digits of number), maximum pattern digits). An example of this can be seen with the number 12.345 and the pattern "##00.00##E0" which formats to "12.345E0", which has 5 significant digits. '5' was calculated as = min(max(4, 5), 8).

In addition, it should be explained how even though there are integer and fraction max and min digits, the implementation will move digits in the integer portion to the fraction portion under certain circumstances.

Lastly, To show all digits, set the significant digits count to zero should be removed from the definition of Scientific Notation, as there is no such existing mechanism that "sets the significant digits count to zero".

Specification

--- a/src/java.base/share/classes/java/text/DecimalFormat.java
+++ b/src/java.base/share/classes/java/text/DecimalFormat.java
@@ -264,6 +264,16
  * formatted using the localized minus sign, <em>not</em> the prefix and suffix
  * from the pattern.  This allows patterns such as {@code "0.###E0 m/s"}.
  *
+ * <li>The <em>maximum integer</em> digits is the sum of '0's and '#'s
+ * prior to the decimal point. The <em>minimum integer</em> digits is the
+ * sum of the '0's prior to the decimal point. The <em>maximum fraction</em>
+ * and <em>minimum fraction</em> digits follow the same rules, but apply to the
+ * digits after the decimal point but before the exponent. For example, the
+ * following pattern: {@code "#00.0####E0"} would have a minimum number of
+ * integer digits = 2("00") and a maximum number of integer digits = 3("#00"). It
+ * would have a minimum number of fraction digits = 1("0") and a maximum number of fraction
+ * digits= 5("0####").
+ *
  * <li>The minimum and maximum number of integer digits are interpreted
  * together:
  *
@@ -282,12 +292,36
  * {@code "12.3E-4"}.
  * </ul>
  *
- * <li>The number of significant digits in the mantissa is the sum of the
- * <em>minimum integer</em> and <em>maximum fraction</em> digits, and is
- * unaffected by the maximum integer digits.  For example, 12345 formatted with
- * {@code "##0.##E0"} is {@code "12.3E3"}. To show all digits, set
- * the significant digits count to zero.  The number of significant digits
- * does not affect parsing.
+ * <li>For a given number, the amount of significant digits in
+ * the mantissa can be calculated as such
+ *
+ * <blockquote><pre>
+ * <i>Mantissa Digits:</i>
+ *         min(max(Minimum Pattern Digits, Original Number Digits), Maximum Pattern Digits)
+ * <i>Minimum pattern Digits:</i>
+ *         <i>Minimum Integer Digits</i> + <i>Minimum Fraction Digits</i>
+ * <i>Maximum pattern Digits:</i>
+ *         <i>Maximum Integer Digits</i> + <i>Maximum Fraction Digits</i>
+ * <i>Original Number Digits:</i>
+ *         The amount of significant digits in the number to be formatted
+ * </pre></blockquote>
+ *
+ * This means that generally a mantissa will have up to the combined maximum integer
+ * and fraction digits, if the original number itself has enough significant digits. However,
+ * if there are more minimum pattern digits than significant digits in the original number,
+ * the mantissa will have significant digits that equals the combined
+ * minimum integer and fraction digits. The number of significant digits
+ * does not affect parsing.
+ *
+ * <p>It should be noted, that the integer portion of the mantissa will give
+ * any excess digits to the fraction portion, whether it be for precision or
+ * for satisfying the total amount of combined minimum digits.
+ *
+ * <p>This behavior can be observed in the following example,
+ * {@snippet lang=java :
+ *     DecimalFormat df = new DecimalFormat("#000.000##E0");
+ *     df.format(12); // returns "12.0000E0"
+ *     df.format(123456789) // returns "1.23456789E8"
+ * }
  *
  * <li>Exponential patterns may not contain grouping separators.
  * </ul>
@@ -308,8 +342,8
  *
  * <h4>Special Values</h4>
  *
- * <p>{@code NaN} is formatted as a string, which typically has a single character
- * {@code U+FFFD}.  This string is determined by the
+ * <p>Not a Number({@code NaN}) is formatted as a string, which typically has a
+ * single character {@code U+FFFD}.  This string is determined by the
  * {@code DecimalFormatSymbols} object.  This is the only value for which
  * the prefixes and suffixes are not used.
  *