From dd892f9e2bc38cd0fa54b290a1fb2eaaaa0f7467 Mon Sep 17 00:00:00 2001 From: Shane Carr Date: Tue, 28 Mar 2017 04:33:32 +0000 Subject: [PATCH] ICU-13060 Adding file-level documentation back to DecimalFormat. X-SVN-Rev: 39949 --- .../ibm/icu/text/CompactDecimalFormat.java | 4 +- .../src/com/ibm/icu/text/DecimalFormat.java | 487 ++++++++++++++---- .../src/com/ibm/icu/text/NumberFormat.java | 11 +- 3 files changed, 395 insertions(+), 107 deletions(-) diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java index 102a38b7973..ef5abaf2b46 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java @@ -70,7 +70,7 @@ public class CompactDecimalFormat extends DecimalFormat { } /** - * Create a CompactDecimalFormat appropriate for a locale. The result may be affected by the + * Creates a CompactDecimalFormat appropriate for a locale. The result may be affected by the * number system in the locale, such as ar-u-nu-latn. * * @param locale the desired locale @@ -82,7 +82,7 @@ public class CompactDecimalFormat extends DecimalFormat { } /** - * Create a CompactDecimalFormat appropriate for a locale. The result may be affected by the + * Creates a CompactDecimalFormat appropriate for a locale. The result may be affected by the * number system in the locale, such as ar-u-nu-latn. * * @param locale the desired locale diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java index 1a0154e2e19..b6b991c68fa 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java @@ -32,8 +32,186 @@ import com.ibm.icu.util.Currency; import com.ibm.icu.util.Currency.CurrencyUsage; import com.ibm.icu.util.CurrencyAmount; import com.ibm.icu.util.ULocale; - -/** @stable ICU 2.0 */ +import com.ibm.icu.util.ULocale.Category; + +/** + * {@icuenhanced java.text.DecimalFormat}.{@icu _usage_} DecimalFormat is the primary + * concrete subclass of {@link NumberFormat}. It has a variety of features designed to make it + * possible to parse and format numbers in any locale, including support for Western, Arabic, or + * Indic digits. It supports different flavors of numbers, including integers ("123"), fixed-point + * numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency amounts + * ("$123.00", "USD123.00", "123.00 US dollars"). All of these flavors can be easily localized. + * + *

To obtain a number formatter for a specific locale (including the default locale), call one of + * NumberFormat's factory methods such as {@link NumberFormat#getInstance}. Do not call + * DecimalFormat constructors directly unless you know what you are doing. + * + *

DecimalFormat aims to comply with the specification UTS #35. Read + * the specification for more information on how all the properties in DecimalFormat fit together. + * + *

Example Usage

+ * + *

Customize settings on a DecimalFormat instance from the NumberFormat factory: + * + *

+ * + * 
+ * NumberFormat f = NumberFormat.getInstance(loc);
+ * if (f instanceof DecimalFormat) {
+ *     ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true);
+ *     ((DecimalFormat) f).setMinimumGroupingDigits(2);
+ * }
+ *
+ * + *
+ * + *

Quick and dirty print out a number using the localized number, currency, and percent format + * for each locale: + * + *

+ * + * 
+ * for (ULocale uloc : ULocale.getAvailableLocales()) {
+ *     System.out.print(uloc + ":\t");
+ *     System.out.print(NumberFormat.getInstance(uloc).format(1.23));
+ *     System.out.print("\t");
+ *     System.out.print(NumberFormat.getCurrencyInstance(uloc).format(1.23));
+ *     System.out.print("\t");
+ *     System.out.print(NumberFormat.getPercentInstance(uloc).format(1.23));
+ *     System.out.println();
+ * }
+ *
+ * + *
+ * + *

Properties and Symbols

+ * + *

A DecimalFormat object encapsulates a set of properties and a set of + * symbols. Grouping size, rounding mode, and affixes are examples of properties. Locale + * digits and the characters used for grouping and decimal separators are examples of symbols. + * + *

To set a custom set of symbols, use {@link #setDecimalFormatSymbols}. Use the various other + * setters in this class to set custom values for the properties. + * + *

Rounding

+ * + *

DecimalFormat provides three main strategies to specify the position at which numbers should + * be rounded: + * + *

    + *
  1. Magnitude: Display a fixed number of fraction digits; this is the most + * common form. + *
  2. Increment: Round numbers to the closest multiple of a certain increment, + * such as 0.05. This is common in currencies. + *
  3. Significant Digits: Round numbers such that a fixed number of nonzero + * digits are shown. This is most common in scientific notation. + *
+ * + * It is possible to specify both a magnitude and a number of significant digits. If used together, + * the significant digits mode determines how conflicts between fraction digits and + * signiciant digits are resolved. For more information, see {@link #setSignificantDigitsMode}. + * + *

It is also possible to specify the rounding mode to use. The default rounding mode is + * "half even", which rounds numbers to their closest increment, with ties broken in favor of + * trailing numbers being even. For more information, see {@link #setRoundingMode} and the ICU User + * Guide. + * + *

Pattern Strings

+ * + *

A pattern string is a way to serialize some of the available properties for decimal + * formatting. However, not all properties are capable of being serialized into a pattern string; + * see {@link #applyPattern} for more information. + * + *

Most users should not need to interface with pattern strings directly. + * + *

ICU DecimalFormat aims to follow the specification for pattern strings in UTS #35. + * Refer to that specification for more information on pattern string syntax. + * + *

Pattern String BNF

+ * + * The following BNF is used when parsing the pattern string into property values: + * + * 
+ * pattern    := subpattern (';' subpattern)?
+ * subpattern := prefix? number exponent? suffix?
+ * number     := (integer ('.' fraction)?) | sigDigits
+ * prefix     := '\u0000'..'\uFFFD' - specialCharacters
+ * suffix     := '\u0000'..'\uFFFD' - specialCharacters
+ * integer    := '#'* '0'* '0'
+ * fraction   := '0'* '#'*
+ * sigDigits  := '#'* '@' '@'* '#'*
+ * exponent   := 'E' '+'? '0'* '0'
+ * padSpec    := '*' padChar
+ * padChar    := '\u0000'..'\uFFFD' - quote
+ *  
+ * Notation:
+ *   X*       0 or more instances of X
+ *   X?       0 or 1 instances of X
+ *   X|Y      either X or Y
+ *   C..D     any character from C up to D, inclusive
+ *   S-T      characters in S, except those in T
+ *
+ * + * The first subpattern is for positive numbers. The second (optional) subpattern is for negative + * numbers. + * + *

Not indicated in the BNF syntax above: + * + *

+ * + *

Parsing

+ * + * DecimalFormat aims to be able to parse anything that it can output as a formatted string. + * + *

There are two primary parse modes: lenient and strict. Lenient mode should + * be used if the goal is to parse user input to a number; strict mode should be used if the goal is + * validation. For more information, see {@link #setParseStrict}. + * + *

DecimalFormat parses all Unicode characters that represent decimal digits, as + * defined by {@link UCharacter#digit}. In addition, DecimalFormat also recognizes as + * digits the ten consecutive characters starting with the localized zero digit defined in the + * {@link DecimalFormatSymbols} object. During formatting, the {@link DecimalFormatSymbols}-based + * digits are output. + * + *

During parsing, grouping separators are ignored. + * + *

For currency parsing, the formatter is able to parse every currency style formats no matter + * which style the formatter is constructed with. For example, a formatter instance gotten from + * NumberFormat.getInstance(ULocale, NumberFormat.CURRENCYSTYLE) can parse formats such as "USD1.00" + * and "3.00 US dollars". + * + *

If {@link #parse(String, ParsePosition)} fails to parse a string, it returns null + * and leaves the parse position unchanged. The convenience method {@link #parse(String)} indicates + * parse failure by throwing a {@link java.text.ParseException}. + * + * + *

Thread Safety and Best Practices

+ * + *

Starting with ICU 59, instance of DecimalFormat are thread-safe. + * + *

Under the hood, DecimalFormat maintains an immutable formatter object that is used whenever + * one of the {@link #format} methods is called. This immutable formatter object is rebuilt whenever + * any of the property setters are called. It is therefore best practice to call property setters + * only during construction and not when formatting numbers online. + * + * @see java.text.Format + * @see NumberFormat + * @stable ICU 2.0 + */ public class DecimalFormat extends NumberFormat { /** New serialization in ICU 59: declare different version from ICU 58. */ @@ -84,11 +262,26 @@ public class DecimalFormat extends NumberFormat { // CONSTRUCTORS // //=====================================================================================// - /** @stable ICU 2.0 */ + /** + * Creates a DecimalFormat based on the number pattern and symbols for the default locale. This is + * a convenient way to obtain a DecimalFormat instance when internationalization is not the main + * concern. + * + *

Most users should call the factory methods on NumberFormat, such as {@link + * NumberFormat#getNumberInstance}, which return localized formatter objects, instead of the + * DecimalFormat constructors. + * + * @see NumberFormat#getInstance + * @see NumberFormat#getNumberInstance + * @see NumberFormat#getCurrencyInstance + * @see NumberFormat#getPercentInstance + * @see Category#FORMAT + * @stable ICU 2.0 + */ public DecimalFormat() { // Use the locale's default pattern ULocale def = ULocale.getDefault(ULocale.Category.FORMAT); - String pattern = getPattern(def, 0); + String pattern = getPattern(def, NumberFormat.NUMBERSTYLE); symbols = getDefaultSymbols(); properties = new Properties(); exportedProperties = new Properties(); @@ -98,7 +291,26 @@ public class DecimalFormat extends NumberFormat { refreshFormatter(); } - /** @stable ICU 2.0 */ + /** + * Creates a DecimalFormat based on the given pattern, using symbols for the default locale. This + * is a convenient way to obtain a DecimalFormat instance when internationalization is not the + * main concern. + * + *

Most users should call the factory methods on NumberFormat, such as {@link + * NumberFormat#getNumberInstance}, which return localized formatter objects, instead of the + * DecimalFormat constructors. + * + * @param pattern A pattern string such as "#,##0.00" conforming to UTS + * #35. + * @throws IllegalArgumentException if the given pattern is invalid. + * @see NumberFormat#getInstance + * @see NumberFormat#getNumberInstance + * @see NumberFormat#getCurrencyInstance + * @see NumberFormat#getPercentInstance + * @see Category#FORMAT + * @stable ICU 2.0 + */ public DecimalFormat(String pattern) { symbols = getDefaultSymbols(); properties = new Properties(); @@ -109,7 +321,26 @@ public class DecimalFormat extends NumberFormat { refreshFormatter(); } - /** @stable ICU 2.0 */ + /** + * Creates a DecimalFormat based on the given pattern and symbols. Use this constructor if you + * want complete control over the behavior of the formatter. + * + *

Most users should call the factory methods on NumberFormat, such as {@link + * NumberFormat#getNumberInstance}, which return localized formatter objects, instead of the + * DecimalFormat constructors. + * + * @param pattern A pattern string such as "#,##0.00" conforming to UTS + * #35. + * @param symbols The set of symbols to be used. + * @exception IllegalArgumentException if the given pattern is invalid + * @see NumberFormat#getInstance + * @see NumberFormat#getNumberInstance + * @see NumberFormat#getCurrencyInstance + * @see NumberFormat#getPercentInstance + * @see DecimalFormatSymbols + * @stable ICU 2.0 + */ public DecimalFormat(String pattern, DecimalFormatSymbols symbols) { this.symbols = (DecimalFormatSymbols) symbols.clone(); properties = new Properties(); @@ -120,12 +351,29 @@ public class DecimalFormat extends NumberFormat { refreshFormatter(); } - /** @stable ICU 4.2 */ + /** + * Creates a DecimalFormat based on the given pattern and symbols, with additional control over + * the behavior of currency. The style argument determines whether currency rounding rules should + * override the pattern, and the {@link CurrencyPluralInfo} object is used for customizing the + * plural forms used for currency long names. + * + *

Most users should call the factory methods on NumberFormat, such as {@link + * NumberFormat#getNumberInstance}, which return localized formatter objects, instead of the + * DecimalFormat constructors. + * + * @param pattern a non-localized pattern string + * @param symbols the set of symbols to be used + * @param infoInput the information used for currency plural format, including currency plural + * patterns and plural rules. + * @param style the decimal formatting style, it is one of the following values: + * NumberFormat.NUMBERSTYLE; NumberFormat.CURRENCYSTYLE; NumberFormat.PERCENTSTYLE; + * NumberFormat.SCIENTIFICSTYLE; NumberFormat.INTEGERSTYLE; NumberFormat.ISOCURRENCYSTYLE; + * NumberFormat.PLURALCURRENCYSTYLE; + * @stable ICU 4.2 + */ public DecimalFormat( String pattern, DecimalFormatSymbols symbols, CurrencyPluralInfo infoInput, int style) { - this.symbols = (DecimalFormatSymbols) symbols.clone(); - properties = new Properties(); - exportedProperties = new Properties(); + this(pattern, symbols, style); properties.setCurrencyPluralInfo(infoInput); refreshFormatter(); } @@ -199,6 +447,7 @@ public class DecimalFormat extends NumberFormat { /** * Converts the given string to standard notation and then parses it using {@link #applyPattern}. + * This method is provided for backwards compatibility and should not be used in new projects. * *

Localized notation means that instead of using generic placeholders in the pattern, you use * the corresponding locale-specific characters instead. For example, in locale fr-FR, @@ -739,11 +988,12 @@ public class DecimalFormat extends NumberFormat { } /** - * @return Whether the sign is being shown on positive numbers. + * {@icu} Returns whether the sign is being shown on positive numbers. + * * @see #setSignAlwaysShown * @category Affixes * @internal - * @deprecated This API is technical preview. + * @deprecated ICU 59: This API is a technical preview. It may change in an upcoming release. */ @Deprecated public synchronized boolean getSignAlwaysShown() { @@ -783,7 +1033,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The multiplier being applied to numbers before they are formatted. + * Returns the multiplier being applied to numbers before they are formatted. + * * @see #setMultiplier * @category Multipliers * @stable ICU 2.0 @@ -836,7 +1087,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The increment to which numbers are being rounded. + * {@icu} Returns the increment to which numbers are being rounded. + * * @see #setRoundingIncrement * @category Rounding * @stable ICU 2.0 @@ -846,9 +1098,9 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Sets an increment, or interval, to which numbers - * are rounded. For example, a rounding increment of 0.05 will cause the number 1.23 to be rounded - * to 1.25 in the default rounding mode. + * {@icu} Rounding and Digit Limits: Sets an increment, or interval, to which + * numbers are rounded. For example, a rounding increment of 0.05 will cause the number 1.23 to be + * rounded to 1.25 in the default rounding mode. * *

The rounding increment can be specified via the pattern string: for example, the pattern * "#,##0.05" encodes a rounding increment of 0.05. @@ -879,7 +1131,7 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Overload of {@link + * {@icu} Rounding and Digit Limits: Overload of {@link * #setRoundingIncrement(java.math.BigDecimal)}. * * @param increment The increment to which numbers are to be rounded. @@ -893,7 +1145,7 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Overload of {@link + * {@icu} Rounding and Digit Limits: Overload of {@link * #setRoundingIncrement(java.math.BigDecimal)}. * * @param increment The increment to which numbers are to be rounded. @@ -911,7 +1163,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The rounding mode being used to round numbers. + * Returns the rounding mode being used to round numbers. + * * @see #setRoundingMode * @category Rounding * @stable ICU 2.0 @@ -951,7 +1204,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The {@link java.math.MathContext} being used to round numbers. + * {@icu} Returns the {@link java.math.MathContext} being used to round numbers. + * * @see #setMathContext * @category Rounding * @stable ICU 4.2 @@ -963,8 +1217,8 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Sets the {@link java.math.MathContext} used to - * round numbers. A "math context" encodes both a rounding mode and a number of significant + * {@icu} Rounding and Digit Limits: Sets the {@link java.math.MathContext} used + * to round numbers. A "math context" encodes both a rounding mode and a number of significant * digits. * *

This method is provided for users who require their output to conform to a standard math @@ -986,7 +1240,8 @@ public class DecimalFormat extends NumberFormat { private transient int icuMathContextForm = MathContext.PLAIN; /** - * @return The {@link com.ibm.icu.math.MathContext} being used to round numbers. + * {@icu} Returns the {@link com.ibm.icu.math.MathContext} being used to round numbers. + * * @see #setMathContext * @category Rounding * @stable ICU 4.2 @@ -1001,8 +1256,8 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Overload of {@link #setMathContext} for {@link - * com.ibm.icu.math.MathContext}. + * {@icu} Rounding and Digit Limits: Overload of {@link #setMathContext} for + * {@link com.ibm.icu.math.MathContext}. * * @param mathContextICU The MathContext to use when rounding numbers. * @see #setMathContext(java.math.MathContext) @@ -1026,7 +1281,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The effective minimum number of digits before the decimal separator. + * Returns the effective minimum number of digits before the decimal separator. + * * @see #setMinimumIntegerDigits * @category Rounding * @stable ICU 2.0 @@ -1059,7 +1315,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The effective maximum number of digits before the decimal separator. + * Returns the effective maximum number of digits before the decimal separator. + * * @see #setMaximumIntegerDigits * @category Rounding * @stable ICU 2.0 @@ -1091,7 +1348,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The effective minimum number of integer digits after the decimal separator. + * Returns the effective minimum number of integer digits after the decimal separator. + * * @see #setMaximumIntegerDigits * @category Rounding * @stable ICU 2.0 @@ -1130,7 +1388,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The effective maximum number of integer digits after the decimal separator. + * Returns the effective maximum number of integer digits after the decimal separator. + * * @see #setMaximumIntegerDigits * @category Rounding * @stable ICU 2.0 @@ -1165,7 +1424,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return Whether significant digits are being used in rounding. + * {@icu} Returns whether significant digits are being used in rounding. + * * @see #setSignificantDigitsUsed * @category Rounding * @stable ICU 3.0 @@ -1175,8 +1435,8 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Sets whether significant digits are to be used in - * rounding. + * {@icu} Rounding and Digit Limits: Sets whether significant digits are to be + * used in rounding. * *

Calling df.setSignificantDigitsUsed(true) is functionally equivalent to: * @@ -1203,7 +1463,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The effective minimum number of significant digits displayed. + * {@icu} Returns the effective minimum number of significant digits displayed. + * * @see #setMinimumSignificantDigits * @category Rounding * @stable ICU 3.0 @@ -1213,9 +1474,9 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Sets the minimum number of significant digits to be - * displayed. If the number of significant digits is less than this value, the number will be - * padded with zeros as necessary. + * {@icu} Rounding and Digit Limits: Sets the minimum number of significant + * digits to be displayed. If the number of significant digits is less than this value, the number + * will be padded with zeros as necessary. * *

For example, if minimum significant digits is 3 and the number is 1.2, the number will be * printed as "1.20". @@ -1231,7 +1492,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The effective maximum number of significant digits displayed. + * {@icu} Returns the effective maximum number of significant digits displayed. + * * @see #setMaximumSignificantDigits * @category Rounding * @stable ICU 3.0 @@ -1241,9 +1503,9 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Sets the maximum number of significant digits to be - * displayed. If the number of significant digits in the number exceeds this value, the number - * will be rounded according to the current rounding mode. + * {@icu} Rounding and Digit Limits: Sets the maximum number of significant + * digits to be displayed. If the number of significant digits in the number exceeds this value, + * the number will be rounded according to the current rounding mode. * *

For example, if maximum significant digits is 3 and the number is 12345, the number will be * printed as "12300". @@ -1265,7 +1527,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The current significant digits mode. + * {@icu} Returns the current significant digits mode. + * * @see #setSignificantDigitsMode * @category Rounding * @internal @@ -1277,7 +1540,7 @@ public class DecimalFormat extends NumberFormat { } /** - * Rounding and Digit Limits: Sets the strategy used for resolving + * {@icu} Rounding and Digit Limits: Sets the strategy used for resolving * minimum/maximum significant digits when minimum/maximum integer and/or fraction digits are * specified. There are three modes: * @@ -1318,7 +1581,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The minimum number of characters in formatted output. + * Returns the minimum number of characters in formatted output. + * * @see #setFormatWidth * @category Padding * @stable ICU 2.0 @@ -1353,7 +1617,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The character used for padding. + * {@icu} Returns the character used for padding. + * * @see #setPadCharacter * @category Padding * @stable ICU 2.0 @@ -1368,8 +1633,8 @@ public class DecimalFormat extends NumberFormat { } /** - * Padding: Sets the character used to pad numbers that are narrower than the - * width specified in {@link #setFormatWidth}. + * {@icu} Padding: Sets the character used to pad numbers that are narrower than + * the width specified in {@link #setFormatWidth}. * *

In the pattern string, the padding character is the token that follows '*' before or after * the prefix or suffix. @@ -1385,7 +1650,8 @@ public class DecimalFormat extends NumberFormat { } /** - * @return The position used for padding. + * {@icu} Returns the position used for padding. + * * @see #setPadPosition * @category Padding * @stable ICU 2.0 @@ -1396,9 +1662,9 @@ public class DecimalFormat extends NumberFormat { } /** - * Padding: Sets the position where to insert the pad character when narrower - * than the width specified in {@link #setFormatWidth}. For example, consider the pattern "P123S" - * with padding width 8 and padding char "*". The four positions are: + * {@icu} Padding: Sets the position where to insert the pad character when + * narrower than the width specified in {@link #setFormatWidth}. For example, consider the pattern + * "P123S" with padding width 8 and padding char "*". The four positions are: * *