8329222: java.text.NumberFormat (and subclasses) spec updates

Reviewed-by: naoto

Author: Justin Lu

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

@@ -47,112 +47,149 @@
 /**
  * <p>
  * {@code CompactNumberFormat} is a concrete subclass of {@code NumberFormat}
- * that formats a decimal number in its compact form.
- *
- * The compact number formatting is designed for the environment where the space
- * is limited, and the formatted string can be displayed in that limited space.
- * It is defined by LDML's specification for
+ * that formats a decimal number in a localized compact form.
+ * Compact number formatting is designed for an environment with limited space.
+ * For example, displaying the formatted number {@code 7M} instead of {@code
+ * 7,000,000.00} in the {@link java.util.Locale#US US locale}. The {@code
+ * CompactNumberFormat} class is defined by LDML's specification for
  * <a href = "http://unicode.org/reports/tr35/tr35-numbers.html#Compact_Number_Formats">
- * Compact Number Formats</a>. A compact number formatting refers
- * to the representation of a number in a shorter form, based on the patterns
- * provided for a given locale.
+ * Compact Number Formats</a>.
  *
- * <p>
- * For example:
- * <br>In the {@link java.util.Locale#US US locale}, {@code 1000} can be formatted
- * as {@code "1K"}, and {@code 1000000} as {@code "1M"}, depending upon the
- * {@linkplain ##compact_number_style style} used.
- * <br>In the {@code "hi_IN"} locale, {@code 1000} can be formatted as
- * "1 \u0939\u091C\u093C\u093E\u0930", and {@code 50000000} as "5 \u0915.",
- * depending upon the {@linkplain ##compact_number_style style} used.
+ * <h2>Getting a CompactNumberFormat</h2>
+ * To get a compact number format, use one of the ways listed below.
+ * <ul>
+ * <li> Use the factory method {@link NumberFormat#getCompactNumberInstance()}
+ * to obtain a format for the default locale with
+ * {@link NumberFormat.Style#SHORT SHORT} style.
+ * <li> Use the factory methood {@link NumberFormat#getCompactNumberInstance(Locale, Style)}
+ * to obtain a format for a different locale
+ * and to control the {@linkplain ##compact_number_style Style}.
+ * <li> Use one of the {@code CompactNumberFormat} constructors, for example, {@link
+ * CompactNumberFormat#CompactNumberFormat(String, DecimalFormatSymbols, String[])
+ * CompactNumberFormat(decimalPattern, symbols, compactPatterns)}, to obtain a
+ * {@code CompactNumberFormat} with further customization.
+ * </ul>
+ * <p>If a standard compact format for a given locale and {@link
+ * ##compact_number_style style} is desired, it is recommended to use one of the
+ * NumberFormat factory methods listed above. To use an instance method
+ * defined by {@code CompactNumberFormat}, the {@code NumberFormat} returned by
+ * these factory methods should be type checked before converted to {@code CompactNumberFormat}.
+ * If the installed locale-sensitive service implementation does not support
+ * the given {@code Locale}, the parent locale chain will be looked up, and
+ * a {@code Locale} used that is supported.
  *
- * <p>
- * To obtain a {@code CompactNumberFormat} for a locale, use one
- * of the factory methods given by {@code NumberFormat} for compact number
- * formatting. For example,
- * {@link NumberFormat#getCompactNumberInstance(Locale, Style)}.
+ * <h2><a id="compact_number_style">Style</a></h2>
+ * When using {@link NumberFormat#getCompactNumberInstance(Locale, Style)}, a
+ * compact form can be retrieved with either a {@link NumberFormat.Style#SHORT
+ * SHORT} or {@link NumberFormat.Style#LONG LONG} style.
+ * For example, a {@link NumberFormat.Style#SHORT SHORT} style compact number instance in
+ * the {@link java.util.Locale#US US locale} formats {@code 10000} as {@code
+ * "10K"}. However, a {@link NumberFormat.Style#LONG LONG} style instance in
+ * the same locale formats {@code 10000} as {@code "10 thousand"}.
  *
- * <blockquote>{@snippet lang=java :
- * NumberFormat fmt = NumberFormat.getCompactNumberInstance(
- *                             Locale.forLanguageTag("hi-IN"), NumberFormat.Style.SHORT);
- * String result = fmt.format(1000);
- * }</blockquote>
+ * <h2>Using CompactNumberFormat</h2>
+ * The following is an example of formatting and parsing in a localized manner,
  *
- * <h2><a id="compact_number_style">Style</a></h2>
- * <p>
- * A number can be formatted in the compact forms with two different
- * styles, {@link NumberFormat.Style#SHORT SHORT}
- * and {@link NumberFormat.Style#LONG LONG}. Use
- * {@link NumberFormat#getCompactNumberInstance(Locale, Style)} for formatting and
- * parsing a number in {@link NumberFormat.Style#SHORT SHORT} or
- * {@link NumberFormat.Style#LONG LONG} compact form,
- * where the given {@code Style} parameter requests the desired
- * format. A {@link NumberFormat.Style#SHORT SHORT} style
- * compact number instance in the {@link java.util.Locale#US US locale} formats
- * {@code 10000} as {@code "10K"}. However, a
- * {@link NumberFormat.Style#LONG LONG} style instance in same locale
- * formats {@code 10000} as {@code "10 thousand"}.
+ * {@snippet lang=java :
+ * NumberFormat compactFormat = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.SHORT);
+ * compactFormat.format(1000); // returns "1K"
+ * compactFormat.parse("1K"); // returns 1000
+ * }
+ *
+ * <h2 id="formatting">Formatting</h2>
+ * The default formatting behavior returns a formatted string with no fractional
+ * digits, however users can use the {@link #setMinimumFractionDigits(int)}
+ * method to include the fractional part.
+ * The number {@code 1000.0} or {@code 1000} is formatted as {@code "1K"}
+ * not {@code "1.00K"} (in the {@link java.util.Locale#US US locale}). For this
+ * reason, the patterns provided for formatting contain only the minimum
+ * integer digits, prefix and/or suffix, but no fractional part.
+ * For example, patterns used are {@code {"", "", "", 0K, 00K, ...}}. If the pattern
+ * selected for formatting a number is {@code "0"} (special pattern),
+ * either explicit or defaulted, then the general number formatting provided by
+ * {@link java.text.DecimalFormat DecimalFormat}
+ * for the specified locale is used.
+ *
+ * <h3>Rounding</h3>
+ * {@code CompactNumberFormat} provides rounding modes defined in
+ * {@link java.math.RoundingMode} for formatting.  By default, it uses
+ * {@link java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}.
+ *
+ * <h2>Parsing</h2>
+ * The default parsing behavior does not allow a grouping separator until
+ * grouping used is set to {@code true} by using
+ * {@link #setGroupingUsed(boolean)}. The parsing of the fractional part
+ * depends on the {@link #isParseIntegerOnly()}. For example, if the
+ * parse integer only is set to true, then the fractional part is skipped.
  *
  * <h2><a id="compact_number_patterns">Compact Number Patterns</a></h2>
  * <p>
- * The compact number patterns are represented in a series of patterns where each
- * pattern is used to format a range of numbers. An example of
- * {@link NumberFormat.Style#SHORT SHORT} styled compact number patterns
+ * The {@code compactPatterns} in {@link
+ * CompactNumberFormat#CompactNumberFormat(String, DecimalFormatSymbols, String[])
+ * CompactNumberFormat(decimalPattern, symbols, compactPatterns)} are represented
+ * as a series of strings, where each string is a {@link ##compact_number_syntax
+ * pattern} that is used to format a range of numbers.
+ *
+ * <p> An example of the {@link NumberFormat.Style#SHORT SHORT} styled compact number patterns
  * for the {@link java.util.Locale#US US locale} is {@code {"", "", "", "0K",
  * "00K", "000K", "0M", "00M", "000M", "0B", "00B", "000B", "0T", "00T", "000T"}},
  * ranging from {@code 10}<sup>{@code 0}</sup> to {@code 10}<sup>{@code 14}</sup>.
  * There can be any number of patterns and they are
  * strictly index based starting from the range {@code 10}<sup>{@code 0}</sup>.
- * For example, in the above patterns, pattern at index 3
- * ({@code "0K"}) is used for formatting {@code number >= 1000 and number < 10000},
- * pattern at index 4 ({@code "00K"}) is used for formatting
- * {@code number >= 10000 and number < 100000} and so on. In most of the locales,
- * patterns with the range
+ * For example, in the above patterns, the pattern at index 3
+ * ({@code "0K"}) is used for formatting a number in the range: {@code 1000 <= number < 10000},
+ * index 4 ({@code "00K"}) for formatting a number the range: {@code 10000 <=
+ * number < 100000}, and so forth.
+ * <p>In most locales, patterns with the range
  * {@code 10}<sup>{@code 0}</sup>-{@code 10}<sup>{@code 2}</sup> are empty
  * strings, which implicitly means a special pattern {@code "0"}.
  * A special pattern {@code "0"} is used for any range which does not contain
  * a compact pattern. This special pattern can appear explicitly for any specific
  * range, or considered as a default pattern for an empty string.
  *
- * <p>
+ * <h3>Negative Subpatterns</h3>
  * A compact pattern contains a positive and negative subpattern
- * separated by a subpattern boundary character {@code ';' (U+003B)},
+ * separated by a subpattern boundary character {@code ';'},
  * for example, {@code "0K;-0K"}. Each subpattern has a prefix,
  * minimum integer digits, and suffix. The negative subpattern
  * is optional, if absent, then the positive subpattern prefixed with the
- * minus sign ({@code '-' U+002D HYPHEN-MINUS}) is used as the negative
+ * minus sign {@code '-' (U+002D HYPHEN-MINUS)} is used as the negative
  * subpattern. That is, {@code "0K"} alone is equivalent to {@code "0K;-0K"}.
  * If there is an explicit negative subpattern, it serves only to specify
  * the negative prefix and suffix. The number of minimum integer digits,
  * and other characteristics are all the same as the positive pattern.
  * That means that {@code "0K;-00K"} produces precisely the same behavior
  * as {@code "0K;-0K"}.
  *
- * <p>
+ * <h4>Escaping Special Characters</h4>
  * Many characters in a compact pattern are taken literally, they are matched
  * during parsing and output unchanged during formatting.
  * {@linkplain DecimalFormat##special_pattern_character Special characters},
  * on the other hand, stand for other characters, strings, or classes of
- * characters. They must be quoted, using single quote {@code ' (U+0027)}
+ * characters. These characters must be quoted using single quotes {@code ' (U+0027)}
  * unless noted otherwise, if they are to appear in the prefix or suffix
  * as literals. For example, 0\u0915'.'.
  *
  * <h3>Plurals</h3>
+ * <p> {@code CompactNumberFormat} support patterns for both singular and plural
+ * compact forms. For the plural form, the {@code Pattern} should consist
+ * of {@code PluralPattern}(s) separated by a space ' ' (U+0020) that are enumerated
+ * within a pair of curly brackets '{' (U+007B) and '}' (U+007D).
+ * In this format, each {@code PluralPattern} consists of its {@code count},
+ * followed by a single colon {@code ':' (U+003A)} and a {@code SimplePattern}.
+ * As a space is reserved for separating subsequent {@code PluralPattern}s, it must
+ * be quoted to be used literally in either the {@code prefix} or {@code suffix}.
  * <p>
- * In case some localization requires compact number patterns to be different for
- * plurals, each singular and plural pattern can be enumerated within a pair of
- * curly brackets <code>'{' (U+007B)</code> and <code>'}' (U+007D)</code>, separated
- * by a space {@code ' ' (U+0020)}. If this format is used, each pattern needs to be
- * prepended by its {@code count}, followed by a single colon {@code ':' (U+003A)}.
- * If the pattern includes spaces literally, they must be quoted.
+ * For example, while the pattern representing millions ({@code 10}<sup>{@code 6}
+ * </sup>) in the US locale can be specified as the SimplePattern: {@code "0 Million"}, for the
+ * German locale it can be specified as the PluralPattern:
+ * {@code "{one:0' 'Million other:0' 'Millionen}"}.
+ *
  * <p>
- * For example, the compact number pattern representing millions in German locale can be
- * specified as {@code "{one:0' 'Million other:0' 'Millionen}"}. The {@code count}
- * follows LDML's
+ * <a id="compact_number_syntax">A compact pattern has the following syntax, with {@code count}</a>
+ * following LDML's
  * <a href="https://unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules">
- * Language Plural Rules</a>.
- * <p>
- * A compact pattern has the following syntax:
+ * Language Plural Rules</a>:
  * <blockquote><pre>
  * <i>Pattern:</i>
  *         <i>SimplePattern</i>
@@ -179,37 +216,12 @@
  *      0 <i>MinimumInteger</i>
  * </pre></blockquote>
  *
- * <h2>Formatting</h2>
- * The default formatting behavior returns a formatted string with no fractional
- * digits, however users can use the {@link #setMinimumFractionDigits(int)}
- * method to include the fractional part.
- * The number {@code 1000.0} or {@code 1000} is formatted as {@code "1K"}
- * not {@code "1.00K"} (in the {@link java.util.Locale#US US locale}). For this
- * reason, the patterns provided for formatting contain only the minimum
- * integer digits, prefix and/or suffix, but no fractional part.
- * For example, patterns used are {@code {"", "", "", 0K, 00K, ...}}. If the pattern
- * selected for formatting a number is {@code "0"} (special pattern),
- * either explicit or defaulted, then the general number formatting provided by
- * {@link java.text.DecimalFormat DecimalFormat}
- * for the specified locale is used.
- *
- * <h2>Parsing</h2>
- * The default parsing behavior does not allow a grouping separator until
- * grouping used is set to {@code true} by using
- * {@link #setGroupingUsed(boolean)}. The parsing of the fractional part
- * depends on the {@link #isParseIntegerOnly()}. For example, if the
- * parse integer only is set to true, then the fractional part is skipped.
- *
- * <h2>Rounding</h2>
- * {@code CompactNumberFormat} provides rounding modes defined in
- * {@link java.math.RoundingMode} for formatting.  By default, it uses
- * {@link java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}.
- *
  * @spec https://www.unicode.org/reports/tr35
  *      Unicode Locale Data Markup Language (LDML)
  * @see NumberFormat.Style
  * @see NumberFormat
  * @see DecimalFormat
+ * @see Locale
  * @since 12
  */
 public final class CompactNumberFormat extends NumberFormat {
@@ -389,10 +401,19 @@ public final class CompactNumberFormat extends NumberFormat {
      * To obtain the instance of {@code CompactNumberFormat} with the standard
      * compact patterns for a {@code Locale} and {@code Style},
      * it is recommended to use the factory methods given by
-     * {@code NumberFormat} for compact number formatting. For example,
-     * {@link NumberFormat#getCompactNumberInstance(Locale, Style)}.
+     * {@code NumberFormat} for compact number formatting.
+     *
+     * <p>Below is an example of using the constructor,
+     *
+     * {@snippet lang=java :
+     * String[] compactPatterns = {"", "", "", "a lot"};
+     * NumberFormat fmt = new CompactNumberFormat("00", DecimalFormatSymbols.getInstance(Locale.US), compactPatterns);
+     * fmt.format(1); // returns "01"
+     * fmt.format(1000); // returns "a lot"
+     * }
      *
-     * @param decimalPattern a decimal pattern for general number formatting
+     * @param decimalPattern a {@linkplain DecimalFormat##patterns decimal pattern}
+     *                       for general number formatting
      * @param symbols the set of symbols to be used
      * @param compactPatterns an array of
      *        {@linkplain ##compact_number_patterns compact number patterns}
@@ -419,7 +440,8 @@ public CompactNumberFormat(String decimalPattern,
      * {@code NumberFormat} for compact number formatting. For example,
      * {@link NumberFormat#getCompactNumberInstance(Locale, Style)}.
      *
-     * @param decimalPattern a decimal pattern for general number formatting
+     * @param decimalPattern a {@linkplain DecimalFormat##patterns decimal pattern}
+     *                      for general number formatting
      * @param symbols the set of symbols to be used
      * @param compactPatterns an array of
      *        {@linkplain ##compact_number_patterns compact number patterns}

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

@@ -56,45 +56,104 @@
 
 /**
  * {@code DecimalFormat} is a concrete subclass of
- * {@code NumberFormat} that formats decimal numbers. It has a variety of
- * features designed to make it possible to parse and format numbers in any
- * locale, including support for Western, Arabic, and Indic digits.  It also
- * supports different kinds of numbers, including integers (123), fixed-point
+ * {@code NumberFormat} that formats decimal numbers in a localized manner.
+ * It has a variety of features designed to make it possible to parse and format
+ * numbers in any locale, including support for Western, Arabic, and Indic digits.
+ * It also supports different kinds of numbers, including integers (123), fixed-point
  * numbers (123.4), scientific notation (1.23E4), percentages (12%), and
- * currency amounts ($123).  All of these can be localized.
+ * currency amounts ($123).
  *
- * <p>To obtain a {@code NumberFormat} for a specific locale, including the
- * default locale, call one of {@code NumberFormat}'s factory methods, such
- * as {@code getInstance()}.  In general, do not call the
- * {@code DecimalFormat} constructors directly, since the
- * {@code NumberFormat} factory methods may return subclasses other than
- * {@code DecimalFormat}. If you need to customize the format object, do
- * something like this:
+ * <h2>Getting a DecimalFormat</h2>
  *
- * <blockquote>{@snippet lang=java :
- * NumberFormat numFormat = NumberFormat.getInstance(loc);
- * if (numFormat instanceof DecimalFormat decFormat) {
- *     decFormat.setDecimalSeparatorAlwaysShown(true);
+ * To obtain a standard decimal format for a specific locale, including the default locale,
+ * it is recommended to call one of the {@code NumberFormat}
+ * {@link NumberFormat##factory_methods factory methods}, such as {@link NumberFormat#getInstance()}.
+ * These factory methods may not always return a {@code DecimalFormat}
+ * depending on the locale-service provider implementation
+ * installed. Thus, to use an instance method defined by {@code DecimalFormat},
+ * the {@code NumberFormat} returned by the factory method should be
+ * type checked before converted to {@code DecimalFormat}. If the installed locale-sensitive
+ * service implementation does not support the given {@code Locale}, the parent
+ * locale chain will be looked up, and a {@code Locale} used that is supported.
+ *
+ * <p>If the factory methods are not desired, use one of the constructors such
+ * as {@link #DecimalFormat(String) DecimalFormat(String pattern)}. See the {@link
+ * ##patterns Pattern} section for more information on the {@code pattern} parameter.
+ *
+ * <h2>Using DecimalFormat</h2>
+ * The following is an example of formatting and parsing,
+ * {@snippet lang=java :
+ * NumberFormat nFmt = NumberFormat.getCurrencyInstance(Locale.US);
+ * if (nFmt instanceof DecimalFormat dFmt) {
+ *     // pattern match to DecimalFormat to use setPositiveSuffix(String)
+ *     dFmt.setPositiveSuffix(" dollars");
+ *     dFmt.format(100000); // returns "$100,000.00 dollars"
+ *     dFmt.parse("$100,000.00 dollars"); // returns 100000
+ * }
  * }
- * }</blockquote>
  *
- * <p>A {@code DecimalFormat} comprises a <em>pattern</em> and a set of
- * <em>symbols</em>.  The pattern may be set directly using
- * {@code applyPattern()}, or indirectly using the API methods.  The
- * symbols are stored in a {@code DecimalFormatSymbols} object.  When using
- * the {@code NumberFormat} factory methods, the pattern and symbols are
- * read from localized {@code ResourceBundle}s.
  *
- * <h2 id="patterns">Patterns</h2>
+ * <h2 id="formatting">Formatting and Parsing</h2>
+ * <h3 id="rounding">Rounding</h3>
  *
- * Note: For any given {@code DecimalFormat} pattern, if the 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.
+ * When formatting, {@code DecimalFormat} can adjust its rounding using {@link
+ * #setRoundingMode(RoundingMode)}. By default, it uses
+ * {@link java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}.
+ *
+ * <h3>Digits</h3>
+ *
+ * When formatting, {@code DecimalFormat} uses the ten consecutive
+ * characters starting with the localized zero digit defined in the
+ * {@code DecimalFormatSymbols} object as digits.
+ * <p>When parsing, these digits as well as all Unicode decimal digits, as
+ * defined by {@link Character#digit Character.digit}, are recognized.
+ *
+ * <h3 id="digit_limits"> Integer and Fraction Digit Limits </h3>
+ * @implSpec
+ * When formatting a {@code Number} other than {@code BigInteger} and
+ * {@code BigDecimal}, {@code 309} is used as the upper limit for integer digits,
+ * and {@code 340} as the upper limit for fraction digits. This occurs, even if
+ * one of the {@code DecimalFormat} getter methods, for example, {@link #getMinimumFractionDigits()}
+ * returns a numerically greater value.
+ *
+ * <h3>Special Values</h3>
+ * <ul>
+ * <li><p><b>Not a Number</b> ({@code NaN}) is formatted as a string,
+ * which is typically given as "NaN". This string is determined by {@link
+ * DecimalFormatSymbols#getNaN()}. This is the only value for which the prefixes
+ * and suffixes are not attached.
+ *
+ * <li><p><b>Infinity</b> is formatted as a string, which is typically given as
+ * "&#8734;" ({@code U+221E}), with the positive or negative prefixes and suffixes
+ * attached. This string is determined by {@link DecimalFormatSymbols#getInfinity()}.
+ *
+ * <li><p><b>Negative zero</b> ({@code "-0"}) parses to
+ * <ul>
+ * <li>{@code BigDecimal(0)} if {@code isParseBigDecimal()} is
+ * true
+ * <li>{@code Long(0)} if {@code isParseBigDecimal()} is false
+ *     and {@code isParseIntegerOnly()} is true
+ * <li>{@code Double(-0.0)} if both {@code isParseBigDecimal()}
+ * and {@code isParseIntegerOnly()} are false
+ * </ul>
+ * </ul>
+ *
+ * <h2><a id="synchronization">Synchronization</a></h2>
+ *
+ * <p>
+ * Decimal formats are generally not synchronized.
+ * It is recommended to create separate format instances for each thread.
+ * If multiple threads access a format concurrently, it must be synchronized
+ * externally.
+ *
+ * <h2 id="patterns">DecimalFormat Pattern</h2>
+ *
+ * A {@code DecimalFormat} comprises a <em>pattern</em> and a set of
+ * <em>symbols</em>. The pattern may be set directly using {@code applyPattern()},
+ * or indirectly using the various API methods. The symbols are stored in a {@code
+ * DecimalFormatSymbols} object. When using the {@code NumberFormat} factory
+ * methods, the pattern and symbols are created from the locale-sensitive service
+ * implementation installed.
  *
  * <p> {@code DecimalFormat} patterns have the following syntax:
  * <blockquote><pre>
@@ -135,120 +194,91 @@
  *         0 <i>MinimumExponent<sub>opt</sub></i>
  * </pre></blockquote>
  *
- * <p>A {@code DecimalFormat} pattern contains a positive and negative
- * subpattern, for example, {@code "#,##0.00;(#,##0.00)"}.  Each
- * subpattern has a prefix, numeric part, and suffix. The negative subpattern
- * is optional; if absent, then the positive subpattern prefixed with the
- * minus sign ({@code '-' U+002D HYPHEN-MINUS}) is used as the
- * negative subpattern. That is, {@code "0.00"} alone is equivalent to
- * {@code "0.00;-0.00"}.  If there is an explicit negative subpattern, it
- * serves only to specify the negative prefix and suffix; the number of digits,
- * minimal digits, and other characteristics are all the same as the positive
- * pattern. That means that {@code "#,##0.0#;(#)"} produces precisely
- * the same behavior as {@code "#,##0.0#;(#,##0.0#)"}.
- *
- * <p>The prefixes, suffixes, and various symbols used for infinity, digits,
- * grouping separators, decimal separators, etc. may be set to arbitrary
- * values, and they will appear properly during formatting.  However, care must
- * be taken that the symbols and strings do not conflict, or parsing will be
- * unreliable.  For example, either the positive and negative prefixes or the
- * suffixes must be distinct for {@code DecimalFormat.parse()} to be able
- * to distinguish positive from negative values.  (If they are identical, then
- * {@code DecimalFormat} will behave as if no negative subpattern was
- * specified.)  Another example is that the decimal separator and grouping
- * separator should be distinct characters, or parsing will be impossible.
- *
- * <p>The grouping separator is commonly used for thousands, but in some
- * countries it separates ten-thousands. The grouping size is a constant number
- * of digits between the grouping characters, such as 3 for 100,000,000 or 4 for
- * 1,0000,0000.  If you supply a pattern with multiple grouping characters, the
- * interval between the last one and the end of the integer is the one that is
- * used. So {@code "#,##,###,####"} == {@code "######,####"} ==
- * {@code "##,####,####"}.
- *
  * <h3><a id="special_pattern_character">Special Pattern Characters</a></h3>
  *
- * <p>Many characters in a pattern are taken literally; they are matched during
- * parsing and output unchanged during formatting.  Special characters, on the
- * other hand, stand for other characters, strings, or classes of characters.
+ * <p>The special characters in the table below are interpreted syntactically when
+ * used in the DecimalFormat pattern.
  * They must be quoted, unless noted otherwise, if they are to appear in the
  * prefix or suffix as literals.
  *
- * <p>The characters listed here are used in non-localized patterns.  Localized
- * patterns use the corresponding characters taken from this formatter's
- * {@code DecimalFormatSymbols} object instead, and these characters lose
- * their special status.  Two exceptions are the currency sign and quote, which
- * are not localized.
+ * <p> The characters in the {@code Symbol} column are used in non-localized
+ * patterns. The corresponding characters in the {@code Localized Symbol} column are used
+ * in localized patterns, with the characters in {@code Symbol} losing their
+ * syntactical meaning. Two exceptions are the currency sign ({@code U+00A4}) and
+ * quote ({@code U+0027}), which are not localized.
+ * <p>
+ * Non-localized patterns should be used when calling {@link #applyPattern(String)}.
+ * Localized patterns should be used when calling {@link #applyLocalizedPattern(String)}.
  *
  * <blockquote>
  * <table class="striped">
  * <caption style="display:none">Chart showing symbol, location, localized, and meaning.</caption>
  * <thead>
  *     <tr>
  *          <th scope="col" style="text-align:left">Symbol
+ *          <th scope="col" style="text-align:left">Localized Symbol
  *          <th scope="col" style="text-align:left">Location
- *          <th scope="col" style="text-align:left">Localized?
- *          <th scope="col" style="text-align:left">Meaning
+ *          <th scope="col" style="text-align:left;width:50%">Meaning
  * </thead>
  * <tbody>
- *     <tr style="vertical-align:top">
+ *     <tr>
  *          <th scope="row">{@code 0}
+ *          <td>{@link DecimalFormatSymbols#getZeroDigit()}
  *          <td>Number
- *          <td>Yes
  *          <td>Digit
- *     <tr style="vertical-align: top">
+ *     <tr>
  *          <th scope="row">{@code #}
+ *          <td>{@link DecimalFormatSymbols#getDigit()}
  *          <td>Number
- *          <td>Yes
  *          <td>Digit, zero shows as absent
- *     <tr style="vertical-align:top">
+ *     <tr>
  *          <th scope="row">{@code .}
+ *          <td>{@link DecimalFormatSymbols#getDecimalSeparator()}
  *          <td>Number
- *          <td>Yes
  *          <td>Decimal separator or monetary decimal separator
- *     <tr style="vertical-align: top">
- *          <th scope="row">{@code -}
+ *     <tr>
+ *          <th scope="row">{@code - (U+002D)}
+ *          <td>{@link DecimalFormatSymbols#getMinusSign()}
  *          <td>Number
- *          <td>Yes
  *          <td>Minus sign
- *     <tr style="vertical-align:top">
+ *     <tr>
  *          <th scope="row">{@code ,}
+ *          <td>{@link DecimalFormatSymbols#getGroupingSeparator()}
  *          <td>Number
- *          <td>Yes
  *          <td>Grouping separator or monetary grouping separator
- *     <tr style="vertical-align: top">
+ *     <tr>
  *          <th scope="row">{@code E}
+ *          <td>{@link DecimalFormatSymbols#getExponentSeparator()}
  *          <td>Number
- *          <td>Yes
- *          <td>Separates mantissa and exponent in scientific notation.
- *              <em>Need not be quoted in prefix or suffix.</em>
- *     <tr style="vertical-align:top">
+ *          <td>Separates mantissa and exponent in scientific notation. This value
+ *              is case sensistive. <em>Need not be quoted in prefix or suffix.</em>
+ *     <tr>
  *          <th scope="row">{@code ;}
+ *          <td>{@link DecimalFormatSymbols#getPatternSeparator()}
  *          <td>Subpattern boundary
- *          <td>Yes
  *          <td>Separates positive and negative subpatterns
- *     <tr style="vertical-align: top">
+ *     <tr>
  *          <th scope="row">{@code %}
+ *          <td>{@link DecimalFormatSymbols#getPercent()}
  *          <td>Prefix or suffix
- *          <td>Yes
  *          <td>Multiply by 100 and show as percentage
- *     <tr style="vertical-align:top">
- *          <th scope="row">{@code U+2030}
+ *     <tr>
+ *          <th scope="row">&permil; ({@code U+2030})
+ *          <td>{@link DecimalFormatSymbols#getPerMill()}
  *          <td>Prefix or suffix
- *          <td>Yes
  *          <td>Multiply by 1000 and show as per mille value
- *     <tr style="vertical-align: top">
+ *     <tr>
  *          <th scope="row">&#164; ({@code U+00A4})
+ *          <td> n/a (not localized)
  *          <td>Prefix or suffix
- *          <td>No
  *          <td>Currency sign, replaced by currency symbol.  If
  *              doubled, replaced by international currency symbol.
  *              If present in a pattern, the monetary decimal/grouping separators
  *              are used instead of the decimal/grouping separators.
- *     <tr style="vertical-align:top">
- *          <th scope="row">{@code '}
+ *     <tr>
+ *          <th scope="row">{@code ' (U+0027)}
+ *          <td> n/a (not localized)
  *          <td>Prefix or suffix
- *          <td>No
  *          <td>Used to quote special characters in a prefix or suffix,
  *              for example, {@code "'#'#"} formats 123 to
  *              {@code "#123"}.  To create a single quote
@@ -257,6 +287,49 @@
  * </table>
  * </blockquote>
  *
+ * <h3>Maximum Digits Derivation</h3>
+ * For any given {@code DecimalFormat} pattern, if the 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. {@link
+ * #setMaximumIntegerDigits(int)} can be used to manually adjust the maximum
+ * integer digits.
+ *
+ * <h3>Negative Subpatterns</h3>
+ * A {@code DecimalFormat} pattern contains a positive and negative
+ * subpattern, for example, {@code "#,##0.00;(#,##0.00)"}.  Each
+ * subpattern has a prefix, numeric part, and suffix. The negative subpattern
+ * is optional; if absent, then the positive subpattern prefixed with the
+ * minus sign {@code '-' (U+002D HYPHEN-MINUS)} is used as the
+ * negative subpattern. That is, {@code "0.00"} alone is equivalent to
+ * {@code "0.00;-0.00"}.  If there is an explicit negative subpattern, it
+ * serves only to specify the negative prefix and suffix; the number of digits,
+ * minimal digits, and other characteristics are all the same as the positive
+ * pattern. That means that {@code "#,##0.0#;(#)"} produces precisely
+ * the same behavior as {@code "#,##0.0#;(#,##0.0#)"}.
+ *
+ * <p>The prefixes, suffixes, and various symbols used for infinity, digits,
+ * grouping separators, decimal separators, etc. may be set to arbitrary
+ * values, and they will appear properly during formatting.  However, care must
+ * be taken that the symbols and strings do not conflict, or parsing will be
+ * unreliable.  For example, either the positive and negative prefixes or the
+ * suffixes must be distinct for {@code DecimalFormat.parse()} to be able
+ * to distinguish positive from negative values.  (If they are identical, then
+ * {@code DecimalFormat} will behave as if no negative subpattern was
+ * specified.)  Another example is that the decimal separator and grouping
+ * separator should be distinct characters, or parsing will be impossible.
+ *
+ * <h3>Grouping Separator</h3>
+ * <p>The grouping separator is commonly used for thousands, but in some
+ * locales it separates ten-thousands. The grouping size is a constant number
+ * of digits between the grouping characters, such as 3 for 100,000,000 or 4 for
+ * 1,0000,0000. If you supply a pattern with multiple grouping characters, the
+ * interval between the last one and the end of the integer is the one that is
+ * used. For example, {@code "#,##,###,####"} == {@code "######,####"} ==
+ * {@code "##,####,####"}.
+ *
  * <h3 id="scientific_notation">Scientific Notation</h3>
  *
  * <p>Numbers in scientific notation are expressed as the product of a mantissa
@@ -339,95 +412,13 @@
  * <li>Exponential patterns may not contain grouping separators.
  * </ul>
  *
- * <h3>Rounding</h3>
- *
- * {@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}.
- *
- * <h3>Digits</h3>
- *
- * For formatting, {@code DecimalFormat} uses the ten consecutive
- * characters starting with the localized zero digit defined in the
- * {@code DecimalFormatSymbols} object as digits. For parsing, these
- * digits as well as all Unicode decimal digits, as defined by
- * {@link Character#digit Character.digit}, are recognized.
- *
- * <h3 id="digit_limits"> Integer and Fraction Digit Limits </h3>
- *
- * @implSpec
- * When formatting a {@code Number} other than {@code BigInteger} and
- * {@code BigDecimal}, {@code 309} is used as the upper limit for integer digits,
- * and {@code 340} as the upper limit for fraction digits. This occurs, even if
- * one of the {@code DecimalFormat} getter methods, for example, {@link #getMinimumFractionDigits()}
- * returns a numerically greater value.
- *
- * <h4>Special Values</h4>
- *
- * <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.
- *
- * <p>Infinity is formatted as a string, which typically has a single character
- * {@code U+221E}, with the positive or negative prefixes and suffixes
- * applied.  The infinity string is determined by the
- * {@code DecimalFormatSymbols} object.
- *
- * <p>Negative zero ({@code "-0"}) parses to
- * <ul>
- * <li>{@code BigDecimal(0)} if {@code isParseBigDecimal()} is
- * true,
- * <li>{@code Long(0)} if {@code isParseBigDecimal()} is false
- *     and {@code isParseIntegerOnly()} is true,
- * <li>{@code Double(-0.0)} if both {@code isParseBigDecimal()}
- * and {@code isParseIntegerOnly()} are false.
- * </ul>
- *
- * <h3><a id="synchronization">Synchronization</a></h3>
- *
- * <p>
- * Decimal formats are generally not synchronized.
- * It is recommended to create separate format instances for each thread.
- * If multiple threads access a format concurrently, it must be synchronized
- * externally.
- *
- * <h3>Example</h3>
- *
- * <blockquote>{@snippet lang=java :
- * // Print out a number using the localized number, integer, currency,
- * // and percent format for each locale
- * Locale[] locales = NumberFormat.getAvailableLocales();
- * double myNumber = -1234.56;
- * NumberFormat form;
- * for (int j = 0; j < 4; ++j) {
- *     System.out.println("FORMAT");
- *     for (Locale locale : locales) {
- *         if (locale.getCountry().length() == 0) {
- *             continue; // Skip language-only locales
- *         }
- *         System.out.print(locale.getDisplayName());
- *         form = switch (j) {
- *             case 0 -> NumberFormat.getInstance(locale);
- *             case 1 -> NumberFormat.getIntegerInstance(locale);
- *             case 2 -> NumberFormat.getCurrencyInstance(locale);
- *             default -> NumberFormat.getPercentInstance(locale);
- *         };
- *         if (form instanceof DecimalFormat decForm) {
- *             System.out.print(": " + decForm.toPattern());
- *         }
- *         System.out.print(" -> " + form.format(myNumber));
- *         try {
- *             System.out.println(" -> " + form.parse(form.format(myNumber)));
- *         } catch (ParseException e) {}
- *     }
- * }
- * }</blockquote>
- *
+ * @spec         https://www.unicode.org/reports/tr35
+ *               Unicode Locale Data Markup Language (LDML)
  * @see          <a href="http://docs.oracle.com/javase/tutorial/i18n/format/decimalFormat.html">Java Tutorial</a>
  * @see          NumberFormat
  * @see          DecimalFormatSymbols
  * @see          ParsePosition
+ * @see          Locale
  * @author       Mark Davis
  * @author       Alan Liu
  * @since 1.1

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

@@ -59,102 +59,110 @@
 /**
  * {@code NumberFormat} is the abstract base class for all number
  * formats. This class provides the interface for formatting and parsing
- * numbers. {@code NumberFormat} also provides methods for determining
- * which locales have number formats, and what their names are.
+ * numbers in a localized manner. This enables code that can be completely
+ * independent of the locale conventions for decimal points, thousands-separators,
+ * the particular decimal digits used, or whether the number format is even
+ * decimal. For example, this class could be used within an application to
+ * produce a number in a currency format according to the conventions of the desired
+ * locale.
  *
- * <p>
- * {@code NumberFormat} helps you to format and parse numbers for any locale.
- * Your code can be completely independent of the locale conventions for
- * decimal points, thousands-separators, or even the particular decimal
- * digits used, or whether the number format is even decimal.
+ * <h2 id="factory_methods">Getting a NumberFormat</h2>
+ * To get a {@code NumberFormat} for the default Locale, use one of the static
+ * factory methods that return a concrete subclass of {@code NumberFormat}.
+ * The following formats all provide an example of formatting the {@code Number}
+ * "2000.50" with the {@link java.util.Locale#US US} locale as the default locale.
+ * <ul>
+ * <li> Use {@link #getInstance()} or {@link #getNumberInstance()} to get
+ * a decimal format. For example, {@code "2,000.5"}.
+ * <li> Use {@link #getIntegerInstance()} to get an integer number format.
+ * For example, {@code "2,000"}.
+ * <li> Use {@link #getCurrencyInstance} to get a currency number format.
+ * For example, {@code "$2,000.50"}.
+ * <li> Use {@link #getCompactNumberInstance} to get a compact number format.
+ * For example, {@code "2K"}.
+ * <li> Use {@link #getPercentInstance} to get a format for displaying percentages.
+ * For example, {@code "200,050%"}.
+ * </ul>
  *
- * <p>
- * To format a number for the current Locale, use one of the factory
- * class methods:
- * <blockquote>
- * {@snippet lang=java :
- * myString = NumberFormat.getInstance().format(myNumber);
- * }
- * </blockquote>
- * If you are formatting multiple numbers, it is
- * more efficient to get the format and use it multiple times so that
- * the system doesn't have to fetch the information about the local
- * language and country conventions multiple times.
- * <blockquote>
- * {@snippet lang=java :
- * NumberFormat nf = NumberFormat.getInstance();
- * for (var myNumber : numbers) {
- *     output.println(nf.format(myNumber) + "; ");
- * }
- * }
- * </blockquote>
- * To format a number for a different Locale, specify it in the
- * call to {@code getInstance}.
- * <blockquote>
- * {@snippet lang=java :
- * NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
- * }
- * </blockquote>
+ * Alternatively, if a {@code NumberFormat} for a different locale is required, use
+ * one of the overloaded factory methods that take {@code Locale} as a parameter,
+ * for example, {@link #getIntegerInstance(Locale)}. If the installed locale-sensitive
+ * service implementation does not support the given {@code Locale}, the parent
+ * locale chain will be looked up, and a {@code Locale} used that is supported.
  *
- * <p>If the locale contains "nu" (numbers) and/or "rg" (region override)
+ * <h3>Locale Extensions</h3>
+ * Formatting behavior can be changed when using a locale that contains any of the following
  * <a href="../util/Locale.html#def_locale_extension">Unicode extensions</a>,
- * the decimal digits, and/or the country used for formatting are overridden.
+ * <ul>
+ * <li> "nu"
+ * (<a href="https://unicode.org/reports/tr35/#UnicodeNumberSystemIdentifier">
+ * Numbering System</a>) - Overrides the decimal digits used
+ * <li> "rg"
+ * (<a href="https://unicode.org/reports/tr35/#RegionOverride">
+ * Region Override</a>) - Overrides the country used
+ * <li> "cf"
+ * (<a href="https://www.unicode.org/reports/tr35/tr35.html#UnicodeCurrencyFormatIdentifier">
+ * Currency Format style</a>) - Overrides the Currency Format style used
+ * </ul>
+ * <p>
  * If both "nu" and "rg" are specified, the decimal digits from the "nu"
  * extension supersedes the implicit one from the "rg" extension.
+ * Although <a href="../util/Locale.html#def_locale_extension">Unicode extensions</a>
+ * defines various keys and values, actual locale-sensitive service implementations
+ * in a Java Runtime Environment might not support any particular Unicode locale
+ * attributes or key/type pairs.
+ * <p>Below is an example of a "US" locale currency format with accounting style,
+ * <blockquote>{@code NumberFormat.getCurrencyInstance(Locale.forLanguageTag("en-US-u-cf-account"));}</blockquote>
+ * With this style, a negative value is formatted enclosed in parentheses, instead
+ * of being prepended with a minus sign.
  *
- * <p>You can also use a {@code NumberFormat} to parse numbers:
- * <blockquote>
+ * <h2>Using NumberFormat</h2>
+ * The following is an example of formatting and parsing in a localized fashion,
  * {@snippet lang=java :
- * myNumber = nf.parse(myString);
+ * NumberFormat currencyFormat = NumberFormat.getCurrencyInstance(Locale.US);
+ * currencyFormat.format(100000); // returns "$100,000.00"
+ * currencyFormat.parse("$100,000.00"); // returns 100000
  * }
- * </blockquote>
- * Use {@code getInstance} or {@code getNumberInstance} to get the
- * normal number format. Use {@code getIntegerInstance} to get an
- * integer number format. Use {@code getCurrencyInstance} to get the
- * currency number format. Use {@code getCompactNumberInstance} to get the
- * compact number format to format a number in shorter form. For example,
- * {@code 2000} can be formatted as {@code "2K"} in
- * {@link java.util.Locale#US US locale}. Use {@code getPercentInstance}
- * to get a format for displaying percentages. With this format, a fraction
- * like 0.53 is displayed as 53%.
  *
- * <p>
- * You can also control the display of numbers with such methods as
- * {@code setMinimumFractionDigits}.
- * If you want even more control over the format or parsing,
- * or want to give your users more control,
- * you can try casting the {@code NumberFormat} you get from the factory methods
- * to a {@code DecimalFormat} or {@code CompactNumberFormat} depending on
- * the factory method used. This will work for the vast majority of locales;
- * just remember to put it in a {@code try} block in case you encounter
- * an unusual one.
+ * <h2>Customizing NumberFormat</h2>
+ * {@code NumberFormat} provides API to customize formatting and parsing behavior,
+ * <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 #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.
+ * <li> {@link #setStrict(boolean)}; when {@code true}, parsing will be done strictly.
+ * The behavior of strict parsing should be referred to in the implementing
+ * {@code NumberFormat} subclass.
+ * </ul>
  *
  * <p>
- * NumberFormat and DecimalFormat are designed such that some controls
- * work for formatting and others work for parsing.  The following is
- * the detailed description for each these control methods,
- * <p>
- * setParseIntegerOnly : only affects parsing, e.g.
- * if true,  "3456.78" &rarr; 3456 (and leaves the parse position just after index 6)
- * if false, "3456.78" &rarr; 3456.78 (and leaves the parse position just after index 8)
- * This is independent of formatting.  If you want to not show a decimal point
- * where there might be no digits after the decimal point, use
- * setDecimalSeparatorAlwaysShown.
- * <p>
- * setDecimalSeparatorAlwaysShown : only affects formatting, and only where
- * there might be no digits after the decimal point, such as with a pattern
- * like "#,##0.##", e.g.,
- * if true,  3456.00 &rarr; "3,456."
- * if false, 3456.00 &rarr; "3456"
- * This is independent of parsing.  If you want parsing to stop at the decimal
- * point, use setParseIntegerOnly.
+ * To provide more control over formatting or parsing behavior, type checking can
+ * be done to safely convert to an implementing subclass of {@code NumberFormat}; this
+ * provides additional methods defined by the subclass.
+ * For example,
+ * {@snippet lang=java :
+ * NumberFormat nFmt = NumberFormat.getInstance(Locale.US);
+ * if (nFmt instanceof DecimalFormat dFmt) {
+ *     dFmt.setDecimalSeparatorAlwaysShown(true);
+ *     dFmt.format(100); // returns "100."
+ * }
+ * }
+ * The {@code NumberFormat} subclass returned by the factory methods is dependent
+ * on the locale-service provider implementation installed, and may not always
+ * be {@link DecimalFormat} or {@link CompactNumberFormat}.
+ *
  * <p>
  * You can also use forms of the {@code parse} and {@code format}
  * methods with {@code ParsePosition} and {@code FieldPosition} to
  * allow you to:
  * <ul>
- * <li> progressively parse through pieces of a string
- * <li> align the decimal point and other areas
+ * <li> Progressively parse through pieces of a string
+ * <li> Align the decimal point and other areas
  * </ul>
  * For example, you can align numbers in two ways:
  * <ol>
@@ -197,15 +205,20 @@
  * If multiple threads access a format concurrently, it must be synchronized
  * externally.
  *
- * @implSpec The {@link #format(double, StringBuffer, FieldPosition)},
+ * @implSpec
+ * Null Parameter Handling
+ * <ul>
+ * <li> The {@link #format(double, StringBuffer, FieldPosition)},
  * {@link #format(long, StringBuffer, FieldPosition)} and
  * {@link #parse(String, ParsePosition)} methods may throw
  * {@code NullPointerException}, if any of their parameter is {@code null}.
  * The subclass may provide its own implementation and specification about
  * {@code NullPointerException}.
+ * </ul>
  *
- * <p>
- * The default implementation provides rounding modes defined
+ * Default RoundingMode
+ * <ul>
+ * <li> The default implementation provides rounding modes defined
  * in {@link java.math.RoundingMode} for formatting numbers. It
  * uses the {@linkplain java.math.RoundingMode#HALF_EVEN
  * round half-even algorithm}. To change the rounding mode use
@@ -214,10 +227,14 @@
  * configured to round floating point numbers using half-even
  * rounding (see {@link java.math.RoundingMode#HALF_EVEN
  * RoundingMode.HALF_EVEN}) for formatting.
+ * </ul>
  *
+ * @spec         https://www.unicode.org/reports/tr35
+ *               Unicode Locale Data Markup Language (LDML)
  * @see          DecimalFormat
  * @see          ChoiceFormat
  * @see          CompactNumberFormat
+ * @see          Locale
  * @author       Mark Davis
  * @author       Helena Shih
  * @since 1.1