archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 23:04:50 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source 
Reviewed-by: naoto
This commit is contained in:
Justin Lu 2024-04-23 21:10:46 +00:00
parent 2555166247
commit f60798a30e
3 changed files with 421 additions and 391 deletions
Download patch file Download diff file Expand all files Collapse all files

181
src/java.base/share/classes/java/text/NumberFormat.java
View file

@ -59,102 +59,110 @@ import sun.util.locale.provider.LocaleServiceProviderPool;
/**
* {@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%.
*
* <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>
* 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.
* 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>
* 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.
* <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 @@ import sun.util.locale.provider.LocaleServiceProviderPool;
* 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 @@ import sun.util.locale.provider.LocaleServiceProviderPool;
* 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