Summary

Clarify java.text.DecimalFormat pattern behavior in both the methods and constructors that take String pattern regarding setting the max integer digits.

Problem

The current specification of applyPattern(String pattern) states that this method does not set the limit of max integer digits. This is false, if the pattern is in scientific notation, the max integer digits is derived from the pattern, otherwise the implementation sets the max integer digits to Integer.MAX_VALUE.

The constructors that take String pattern as input make no mention of this behavior at all.

The current wording can cause the following incorrect assumption,

jshell> DecimalFormat df = new DecimalFormat();
df ==> java.text.DecimalFormat@674dc
jshell> df.setMaximumIntegerDigits(3)
jshell> df.applyPattern("000.000") // Current spec states max integer digits is not set
jshell> df.getMaximumIntegerDigits() // User still expects 3 here
$5 ==> 2147483647

Solution

Clarify in both the methods and constructors relating to the pattern that if the pattern is in scientific notation, the max integer digits will be set. Otherwise, the value will be set to Integer.MAX_VALUE. Added to each method/constructor as opposed to the class description as this behavior is highly unexpected, and should be emphasized.

Specification

--- a/src/java.base/share/classes/java/text/DecimalFormat.java
+++ b/src/java.base/share/classes/java/text/DecimalFormat.java
@@ -245,7 +245,7 @@
- * <h3>Scientific Notation</h3>
+ * <h3 id="scientific_notation">Scientific Notation</h3>
  *
  * <p>Numbers in scientific notation are expressed as the product of a mantissa
  * and a power of ten, for example, 1234 can be expressed as 1.234 x 10^3.  The
@@ -449,6 +449,14 @@ public DecimalFormat() {
      * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
      * This is a convenient way to obtain a
      * DecimalFormat when internationalization is not the main concern.
+     * If the given pattern is not in scientific notation, the maximum number
+     * of integer digits will not be derived from the pattern, and instead set
+     * to {@link Integer#MAX_VALUE}. Otherwise, if the pattern is in scientific
+     * notation, the maximum number of integer digits will be derived from the
+     * pattern. This derivation is detailed in the {@link ##scientific_notation
+     * Scientific Notation} section. This behavior is the typical end-user desire;
+     * {@link #setMaximumIntegerDigits(int)} can be used to manually adjust the
+     * maximum integer digits.
      * <p>
      * To obtain standard formats for a given locale, use the factory methods
      * on NumberFormat such as getNumberInstance. These factories will
@@ -474,6 +482,14 @@ public DecimalFormat(String pattern) {
      * Creates a DecimalFormat using the given pattern and symbols.
      * Use this constructor when you need to completely customize the
      * behavior of the format.
+     * If the given pattern is not in scientific notation, the maximum number
+     * of integer digits will not be derived from the pattern, and instead set
+     * to {@link Integer#MAX_VALUE}. Otherwise, if the pattern is in scientific
+     * notation, the maximum number of integer digits will be derived from the
+     * pattern. This derivation is detailed in the {@link ##scientific_notation
+     * Scientific Notation} section. This behavior is the typical end-user desire;
+     * {@link #setMaximumIntegerDigits(int)} can be used to manually adjust the
+     * maximum integer digits.
      * <p>
      * To obtain standard formats for a given
      * locale, use the factory methods on NumberFormat such as
@@ -3298,9 +3314,14 @@ private String toPattern(boolean localized) {
      * These properties can also be changed individually through the
      * various setter methods.
      * <p>
-     * There is no limit to integer digits set
-     * by this routine, since that is the typical end-user desire;
-     * use setMaximumInteger if you want to set a real value.
+     * If the given pattern is not in scientific notation, the maximum number
+     * of integer digits will not be derived from the pattern, and instead set
+     * to {@link Integer#MAX_VALUE}. Otherwise, if the pattern is in scientific
+     * notation, the maximum number of integer digits will be derived from the
+     * pattern. This derivation is detailed in the {@link ##scientific_notation
+     * Scientific Notation} section. This behavior is the typical end-user desire;
+     * {@link #setMaximumIntegerDigits(int)} can be used to manually adjust the
+     * maximum integer digits.
      * For negative numbers, use a second pattern, separated by a semicolon
      * <P>Example {@code "#,#00.0#"} &rarr; 1,234.56
      * <P>This means a minimum of 2 integer digits, 1 fraction digit, and
@@ -3325,9 +3346,14 @@ public void applyPattern(String pattern) {
      * These properties can also be changed individually through the
      * various setter methods.
      * <p>
-     * There is no limit to integer digits set
-     * by this routine, since that is the typical end-user desire;
-     * use setMaximumInteger if you want to set a real value.
+     * If the given pattern is not in scientific notation, the maximum number
+     * of integer digits will not be derived from the pattern, and instead set
+     * to {@link Integer#MAX_VALUE}. Otherwise, if the pattern is in scientific
+     * notation, the maximum number of integer digits will be derived from the
+     * pattern. This derivation is detailed in the {@link ##scientific_notation
+     * Scientific Notation} section. This behavior is the typical end-user desire;
+     * {@link #setMaximumIntegerDigits(int)} can be used to manually adjust the
+     * maximum integer digits.
      * For negative numbers, use a second pattern, separated by a semicolon
      * <P>Example {@code "#,#00.0#"} &rarr; 1,234.56
      * <P>This means a minimum of 2 integer digits, 1 fraction digit, and