8352755: Misconceptions about j.text.DecimalFormat digits during parsing

Reviewed-by: naoto

Author: Justin Lu

src/java.base/share/classes/java/text/CompactNumberFormat.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -2169,14 +2169,10 @@ private void readObject(ObjectInputStream inStream) throws IOException,
     }
 
     /**
-     * Sets the maximum number of digits allowed in the integer portion of a
-     * number.
-     * The maximum allowed integer range is 309, if the {@code newValue} > 309,
-     * then the maximum integer digits count is set to 309. Negative input
-     * values are replaced with 0.
-     *
-     * @param newValue the maximum number of integer digits to be shown
-     * @see #getMaximumIntegerDigits()
+     * {@inheritDoc NumberFormat}
+     * <p>The maximum allowed integer range is 309, if the {@code newValue} &gt;
+     * 309, then the maximum integer digits count is set to 309.
+     * @param newValue the maximum number of integer digits to be shown.
      */
     @Override
     public void setMaximumIntegerDigits(int newValue) {
@@ -2194,14 +2190,10 @@ public void setMaximumIntegerDigits(int newValue) {
     }
 
     /**
-     * Sets the minimum number of digits allowed in the integer portion of a
-     * number.
-     * The maximum allowed integer range is 309, if the {@code newValue} &gt; 309,
-     * then the minimum integer digits count is set to 309. Negative input
-     * values are replaced with 0.
-     *
-     * @param newValue the minimum number of integer digits to be shown
-     * @see #getMinimumIntegerDigits()
+     * {@inheritDoc NumberFormat}
+     * <p>The maximum allowed integer range is 309, if the {@code newValue} &gt;
+     * 309, then the minimum integer digits count is set to 309.
+     * @param newValue the minimum number of integer digits to be shown.
      */
     @Override
     public void setMinimumIntegerDigits(int newValue) {
@@ -2219,14 +2211,10 @@ public void setMinimumIntegerDigits(int newValue) {
     }
 
     /**
-     * Sets the minimum number of digits allowed in the fraction portion of a
-     * number.
-     * The maximum allowed fraction range is 340, if the {@code newValue} &gt; 340,
-     * then the minimum fraction digits count is set to 340. Negative input
-     * values are replaced with 0.
-     *
-     * @param newValue the minimum number of fraction digits to be shown
-     * @see #getMinimumFractionDigits()
+     * {@inheritDoc NumberFormat}
+     * <p>The maximum allowed fraction range is 340, if the {@code newValue} &gt;
+     * 340, then the minimum fraction digits count is set to 340.
+     * @param newValue the minimum number of fraction digits to be shown.
      */
     @Override
     public void setMinimumFractionDigits(int newValue) {
@@ -2245,14 +2233,10 @@ public void setMinimumFractionDigits(int newValue) {
     }
 
     /**
-     * Sets the maximum number of digits allowed in the fraction portion of a
-     * number.
-     * The maximum allowed fraction range is 340, if the {@code newValue} &gt; 340,
-     * then the maximum fraction digits count is set to 340. Negative input
-     * values are replaced with 0.
-     *
-     * @param newValue the maximum number of fraction digits to be shown
-     * @see #getMaximumFractionDigits()
+     * {@inheritDoc NumberFormat}
+     * <p>The maximum allowed fraction range is 340, if the {@code newValue} &gt;
+     * 340, then the maximum fraction digits count is set to 340.
+     * @param newValue the maximum number of fraction digits to be shown.
      */
     @Override
     public void setMaximumFractionDigits(int newValue) {

src/java.base/share/classes/java/text/DecimalFormat.java

@@ -110,6 +110,10 @@
  * defined by {@link Character#digit Character.digit}, are recognized.
  *
  * <h3 id="digit_limits"> Integer and Fraction Digit Limits </h3>
+ * The integer and fraction digit limits are set by either applying a {@link ##patterns
+ * pattern} or using one of the appropriate {@code DecimalFormat} setter methods,
+ * for example, {@link #setMinimumFractionDigits(int)}. These limits have no impact
+ * on parsing behavior.
  * @implSpec
  * When formatting a {@code Number} other than {@code BigInteger} and
  * {@code BigDecimal}, {@code 309} is used as the upper limit for integer digits,
@@ -3972,9 +3976,9 @@ else if (ch == percent) {
     }
 
     /**
-     * Sets the maximum number of digits allowed in the integer portion of a
-     * number. Negative input values are replaced with 0.
-     * @see NumberFormat#setMaximumIntegerDigits
+     * {@inheritDoc NumberFormat}
+     * @param newValue the maximum number of integer digits to be shown.
+     * @see #getMaximumIntegerDigits()
      * @see ##digit_limits Integer and Fraction Digit Limits
      */
     @Override
@@ -3989,9 +3993,9 @@ public void setMaximumIntegerDigits(int newValue) {
     }
 
     /**
-     * Sets the minimum number of digits allowed in the integer portion of a
-     * number. Negative input values are replaced with 0.
-     * @see NumberFormat#setMinimumIntegerDigits
+     * {@inheritDoc NumberFormat}
+     * @param newValue the minimum number of integer digits to be shown.
+     * @see #getMinimumIntegerDigits()
      * @see ##digit_limits Integer and Fraction Digit Limits
      */
     @Override
@@ -4006,9 +4010,9 @@ public void setMinimumIntegerDigits(int newValue) {
     }
 
     /**
-     * Sets the maximum number of digits allowed in the fraction portion of a
-     * number. Negative input values are replaced with 0.
-     * @see NumberFormat#setMaximumFractionDigits
+     * {@inheritDoc NumberFormat}
+     * @param newValue the maximum number of fraction digits to be shown.
+     * @see #getMaximumFractionDigits()
      * @see ##digit_limits Integer and Fraction Digit Limits
      */
     @Override
@@ -4023,9 +4027,9 @@ public void setMaximumFractionDigits(int newValue) {
     }
 
     /**
-     * Sets the minimum number of digits allowed in the fraction portion of a
-     * number. Negative input values are replaced with 0.
-     * @see NumberFormat#setMinimumFractionDigits
+     * {@inheritDoc NumberFormat}
+     * @param newValue the minimum number of fraction digits to be shown.
+     * @see #getMinimumFractionDigits()
      * @see ##digit_limits Integer and Fraction Digit Limits
      */
     @Override
@@ -4040,11 +4044,11 @@ public void setMinimumFractionDigits(int newValue) {
     }
 
     /**
-     * Gets the maximum number of digits allowed in the integer portion of a
-     * number. The maximum number of integer digits can be set by either {@link #setMaximumIntegerDigits(int)}
-     * or {@link #applyPattern(String)}. See the {@link ##patterns Pattern Section} for
-     * comprehensive rules regarding maximum integer digits in patterns.
+     * {@inheritDoc NumberFormat}
+     * <p>Unlike the other digit limits, {@code maximumIntegerDigits} is not
+     * updated by {@code DecimalFormats} created or updated with a string pattern.
      * @see #setMaximumIntegerDigits
+     * @see ##patterns Pattern Section
      * @see ##digit_limits Integer and Fraction Digit Limits
      */
     @Override
@@ -4053,8 +4057,7 @@ public int getMaximumIntegerDigits() {
     }
 
     /**
-     * Gets the minimum number of digits allowed in the integer portion of a
-     * number.
+     * {@inheritDoc NumberFormat}
      * @see #setMinimumIntegerDigits
      * @see ##digit_limits Integer and Fraction Digit Limits
      */
@@ -4064,8 +4067,7 @@ public int getMinimumIntegerDigits() {
     }
 
     /**
-     * Gets the maximum number of digits allowed in the fraction portion of a
-     * number.
+     * {@inheritDoc NumberFormat}
      * @see #setMaximumFractionDigits
      * @see ##digit_limits Integer and Fraction Digit Limits
      */
@@ -4075,8 +4077,7 @@ public int getMaximumFractionDigits() {
     }
 
     /**
-     * Gets the minimum number of digits allowed in the fraction portion of a
-     * number.
+     * {@inheritDoc NumberFormat}
      * @see #setMinimumFractionDigits
      * @see ##digit_limits Integer and Fraction Digit Limits
      */

src/java.base/share/classes/java/text/NumberFormat.java

@@ -129,9 +129,9 @@
  * <ul>
  * <li> {@link #setParseIntegerOnly(boolean)}; when {@code true}, will only return the
  * integer portion of the number parsed from the String.
- * <li> {@link #setMinimumFractionDigits(int)}; Use to adjust the expected digits when
- * formatting. Use any of the other minimum/maximum or fraction/integer setter methods
- * in the same manner.
+ * <li> {@link #setMinimumFractionDigits(int)}; Use to adjust the expected digits
+ * when formatting. Use any of the other minimum/maximum or fraction/integer
+ * setter methods in the same manner. These methods have no impact on parsing behavior.
  * <li> {@link #setGroupingUsed(boolean)}; when {@code true}, formatted numbers will be displayed
  * with grouping separators. Additionally, when {@code false}, parsing will not expect
  * grouping separators in the parsed String.
@@ -918,7 +918,7 @@ public void setGroupingUsed(boolean newValue) {
 
     /**
      * Returns the maximum number of digits allowed in the integer portion of a
-     * number.
+     * number during formatting.
      *
      * @return the maximum number of digits
      * @see #setMaximumIntegerDigits
@@ -929,14 +929,15 @@ public int getMaximumIntegerDigits() {
 
     /**
      * Sets the maximum number of digits allowed in the integer portion of a
-     * number. maximumIntegerDigits must be &ge; minimumIntegerDigits.  If the
-     * new value for maximumIntegerDigits is less than the current value
-     * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
-     * the new value.
+     * number during formatting. {@code maximumIntegerDigits} must be &ge;
+     * {@code minimumIntegerDigits}. If the new value for {@code
+     * maximumIntegerDigits} is less than the current value of
+     * {@code minimumIntegerDigits}, then {@code minimumIntegerDigits} will
+     * also be set to the new value. Negative input values are replaced with 0.
      *
-     * @param newValue the maximum number of integer digits to be shown; if
-     * less than zero, then zero is used. The concrete subclass may enforce an
-     * upper limit to this value appropriate to the numeric type being formatted.
+     * @param newValue the maximum number of integer digits to be shown. The
+     * concrete subclass may enforce an upper limit to this value appropriate to
+     * the numeric type being formatted.
      * @see #getMaximumIntegerDigits
      */
     public void setMaximumIntegerDigits(int newValue) {
@@ -948,7 +949,7 @@ public void setMaximumIntegerDigits(int newValue) {
 
     /**
      * Returns the minimum number of digits allowed in the integer portion of a
-     * number.
+     * number during formatting.
      *
      * @return the minimum number of digits
      * @see #setMinimumIntegerDigits
@@ -959,14 +960,15 @@ public int getMinimumIntegerDigits() {
 
     /**
      * Sets the minimum number of digits allowed in the integer portion of a
-     * number. minimumIntegerDigits must be &le; maximumIntegerDigits.  If the
-     * new value for minimumIntegerDigits exceeds the current value
-     * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
-     * the new value
+     * number during formatting. {@code minimumIntegerDigits} must be &le;
+     * {@code maximumIntegerDigits}. If the new value for {@code minimumIntegerDigits}
+     * exceeds the current value of {@code maximumIntegerDigits}, then {@code
+     * maximumIntegerDigits} will also be set to the new value. Negative input
+     * values are replaced with 0.
      *
-     * @param newValue the minimum number of integer digits to be shown; if
-     * less than zero, then zero is used. The concrete subclass may enforce an
-     * upper limit to this value appropriate to the numeric type being formatted.
+     * @param newValue the minimum number of integer digits to be shown. The
+     * concrete subclass may enforce an upper limit to this value appropriate to
+     * the numeric type being formatted.
      * @see #getMinimumIntegerDigits
      */
     public void setMinimumIntegerDigits(int newValue) {
@@ -978,7 +980,7 @@ public void setMinimumIntegerDigits(int newValue) {
 
     /**
      * Returns the maximum number of digits allowed in the fraction portion of a
-     * number.
+     * number during formatting.
      *
      * @return the maximum number of digits.
      * @see #setMaximumFractionDigits
@@ -989,14 +991,15 @@ public int getMaximumFractionDigits() {
 
     /**
      * Sets the maximum number of digits allowed in the fraction portion of a
-     * number. maximumFractionDigits must be &ge; minimumFractionDigits.  If the
-     * new value for maximumFractionDigits is less than the current value
-     * of minimumFractionDigits, then minimumFractionDigits will also be set to
-     * the new value.
+     * number during formatting. {@code maximumFractionDigits} must be &ge;
+     * {@code minimumFractionDigits}. If the new value for {@code maximumFractionDigits}
+     * is less than the current value of {@code minimumFractionDigits}, then
+     * {@code minimumFractionDigits} will also be set to the new value. Negative
+     * input values are replaced with 0.
      *
-     * @param newValue the maximum number of fraction digits to be shown; if
-     * less than zero, then zero is used. The concrete subclass may enforce an
-     * upper limit to this value appropriate to the numeric type being formatted.
+     * @param newValue the maximum number of fraction digits to be shown. The
+     * concrete subclass may enforce an upper limit to this value appropriate to
+     * the numeric type being formatted.
      * @see #getMaximumFractionDigits
      */
     public void setMaximumFractionDigits(int newValue) {
@@ -1008,7 +1011,7 @@ public void setMaximumFractionDigits(int newValue) {
 
     /**
      * Returns the minimum number of digits allowed in the fraction portion of a
-     * number.
+     * number during formatting.
      *
      * @return the minimum number of digits
      * @see #setMinimumFractionDigits
@@ -1019,14 +1022,15 @@ public int getMinimumFractionDigits() {
 
     /**
      * Sets the minimum number of digits allowed in the fraction portion of a
-     * number. minimumFractionDigits must be &le; maximumFractionDigits.  If the
-     * new value for minimumFractionDigits exceeds the current value
-     * of maximumFractionDigits, then maximumFractionDigits will also be set to
-     * the new value
+     * number during formatting. {@code minimumFractionDigits} must be &le;
+     * {@code maximumFractionDigits}. If the new value for {@code
+     * minimumFractionDigits} exceeds the current value of {@code
+     * maximumFractionDigits}, then {@code maximumFractionDigits} will also be
+     * set to the new value. Negative input values are replaced with 0.
      *
-     * @param newValue the minimum number of fraction digits to be shown; if
-     * less than zero, then zero is used. The concrete subclass may enforce an
-     * upper limit to this value appropriate to the numeric type being formatted.
+     * @param newValue the minimum number of fraction digits to be shown. The
+     * concrete subclass may enforce an upper limit to this value appropriate to
+     * the numeric type being formatted.
      * @see #getMinimumFractionDigits
      */
     public void setMinimumFractionDigits(int newValue) {