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}