--- a/jdk/src/share/classes/java/text/NumberFormat.java Thu Jul 25 20:03:20 2013 -0700
+++ b/jdk/src/share/classes/java/text/NumberFormat.java Fri Jul 26 17:22:08 2013 +0900
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -73,34 +73,34 @@
* To format a number for the current Locale, use one of the factory
* class methods:
* <blockquote>
- * <pre>
- * myString = NumberFormat.getInstance().format(myNumber);
- * </pre>
+ * <pre>{@code
+ * myString = NumberFormat.getInstance().format(myNumber);
+ * }</pre>
* </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>
- * <pre>
+ * <pre>{@code
* NumberFormat nf = NumberFormat.getInstance();
* for (int i = 0; i < myNumber.length; ++i) {
* output.println(nf.format(myNumber[i]) + "; ");
* }
- * </pre>
+ * }</pre>
* </blockquote>
* To format a number for a different Locale, specify it in the
* call to <code>getInstance</code>.
* <blockquote>
- * <pre>
+ * <pre>{@code
* NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
- * </pre>
+ * }</pre>
* </blockquote>
* You can also use a <code>NumberFormat</code> to parse numbers:
* <blockquote>
- * <pre>
+ * <pre>{@code
* myNumber = nf.parse(myString);
- * </pre>
+ * }</pre>
* </blockquote>
* Use <code>getInstance</code> or <code>getNumberInstance</code> to get the
* normal number format. Use <code>getIntegerInstance</code> to get an
@@ -125,8 +125,8 @@
* the detailed description for each these control methods,
* <p>
* setParseIntegerOnly : only affects parsing, e.g.
- * if true, "3456.78" -> 3456 (and leaves the parse position just after index 6)
- * if false, "3456.78" -> 3456.78 (and leaves the parse position just after index 8)
+ * if true, "3456.78" → 3456 (and leaves the parse position just after index 6)
+ * if false, "3456.78" → 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.
@@ -134,8 +134,8 @@
* 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 -> "3,456."
- * if false, 3456.00 -> "3456"
+ * if true, 3456.00 → "3,456."
+ * if false, 3456.00 → "3456"
* This is independent of parsing. If you want parsing to stop at the decimal
* point, use setParseIntegerOnly.
*
@@ -166,7 +166,7 @@
* numbers: "(12)" for -12.
* </ol>
*
- * <h4><a name="synchronization">Synchronization</a></h4>
+ * <h3><a name="synchronization">Synchronization</a></h3>
*
* <p>
* Number formats are generally not synchronized.
@@ -280,6 +280,9 @@
/**
* Specialization of format.
+ *
+ * @param number the double number to format
+ * @return the formatted String
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
* @see java.text.Format#format
@@ -302,6 +305,9 @@
/**
* Specialization of format.
+ *
+ * @param number the long number to format
+ * @return the formatted String
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
* @see java.text.Format#format
@@ -313,6 +319,12 @@
/**
* Specialization of format.
+ *
+ * @param number the double number to format
+ * @param toAppendTo the StringBuffer to which the formatted text is to be
+ * appended
+ * @param pos the field position
+ * @return the formatted StringBuffer
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
* @see java.text.Format#format
@@ -323,6 +335,12 @@
/**
* Specialization of format.
+ *
+ * @param number the long number to format
+ * @param toAppendTo the StringBuffer to which the formatted text is to be
+ * appended
+ * @param pos the field position
+ * @return the formatted StringBuffer
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
* @see java.text.Format#format
@@ -339,6 +357,10 @@
* after the 1).
* Does not throw an exception; if no object can be parsed, index is
* unchanged!
+ *
+ * @param source the String to parse
+ * @param parsePosition the parse position
+ * @return the parsed value
* @see java.text.NumberFormat#isParseIntegerOnly
* @see java.text.Format#parseObject
*/
@@ -373,6 +395,9 @@
* would stop at the "." character. Of course, the exact format accepted
* by the parse operation is locale dependant and determined by sub-classes
* of NumberFormat.
+ *
+ * @return {@code true} if numbers should be parsed as integers only;
+ * {@code false} otherwise
*/
public boolean isParseIntegerOnly() {
return parseIntegerOnly;
@@ -380,6 +405,9 @@
/**
* Sets whether or not numbers should be parsed as integers only.
+ *
+ * @param value {@code true} if numbers should be parsed as integers only;
+ * {@code false} otherwise
* @see #isParseIntegerOnly
*/
public void setParseIntegerOnly(boolean value) {
@@ -393,6 +421,9 @@
* {@link java.util.Locale.Category#FORMAT FORMAT} locale.
* This is the same as calling
* {@link #getNumberInstance() getNumberInstance()}.
+ *
+ * @return the {@code NumberFormat} instance for general-purpose number
+ * formatting
*/
public final static NumberFormat getInstance() {
return getInstance(Locale.getDefault(Locale.Category.FORMAT), NUMBERSTYLE);
@@ -402,6 +433,10 @@
* Returns a general-purpose number format for the specified locale.
* This is the same as calling
* {@link #getNumberInstance(java.util.Locale) getNumberInstance(inLocale)}.
+ *
+ * @param inLocale the desired locale
+ * @return the {@code NumberFormat} instance for general-purpose number
+ * formatting
*/
public static NumberFormat getInstance(Locale inLocale) {
return getInstance(inLocale, NUMBERSTYLE);
@@ -413,6 +448,9 @@
* <p>This is equivalent to calling
* {@link #getNumberInstance(Locale)
* getNumberInstance(Locale.getDefault(Locale.Category.FORMAT))}.
+ *
+ * @return the {@code NumberFormat} instance for general-purpose number
+ * formatting
* @see java.util.Locale#getDefault(java.util.Locale.Category)
* @see java.util.Locale.Category#FORMAT
*/
@@ -422,6 +460,10 @@
/**
* Returns a general-purpose number format for the specified locale.
+ *
+ * @param inLocale the desired locale
+ * @return the {@code NumberFormat} instance for general-purpose number
+ * formatting
*/
public static NumberFormat getNumberInstance(Locale inLocale) {
return getInstance(inLocale, NUMBERSTYLE);
@@ -457,6 +499,7 @@
* and to parse only the integer part of an input string (see {@link
* #isParseIntegerOnly isParseIntegerOnly}).
*
+ * @param inLocale the desired locale
* @see #getRoundingMode()
* @return a number format for integer values
* @since 1.4
@@ -472,6 +515,7 @@
* {@link #getCurrencyInstance(Locale)
* getCurrencyInstance(Locale.getDefault(Locale.Category.FORMAT))}.
*
+ * @return the {@code NumberFormat} instance for currency formatting
* @see java.util.Locale#getDefault(java.util.Locale.Category)
* @see java.util.Locale.Category#FORMAT
*/
@@ -481,6 +525,9 @@
/**
* Returns a currency format for the specified locale.
+ *
+ * @param inLocale the desired locale
+ * @return the {@code NumberFormat} instance for currency formatting
*/
public static NumberFormat getCurrencyInstance(Locale inLocale) {
return getInstance(inLocale, CURRENCYSTYLE);
@@ -493,6 +540,7 @@
* {@link #getPercentInstance(Locale)
* getPercentInstance(Locale.getDefault(Locale.Category.FORMAT))}.
*
+ * @return the {@code NumberFormat} instance for percentage formatting
* @see java.util.Locale#getDefault(java.util.Locale.Category)
* @see java.util.Locale.Category#FORMAT
*/
@@ -502,6 +550,9 @@
/**
* Returns a percentage format for the specified locale.
+ *
+ * @param inLocale the desired locale
+ * @return the {@code NumberFormat} instance for percentage formatting
*/
public static NumberFormat getPercentInstance(Locale inLocale) {
return getInstance(inLocale, PERCENTSTYLE);
@@ -516,6 +567,8 @@
/**
* Returns a scientific format for the specified locale.
+ *
+ * @param inLocale the desired locale
*/
/*public*/ static NumberFormat getScientificInstance(Locale inLocale) {
return getInstance(inLocale, SCIENTIFICSTYLE);
@@ -586,6 +639,9 @@
* English locale, with grouping on, the number 1234567 might be formatted
* as "1,234,567". The grouping separator as well as the size of each group
* is locale dependant and is determined by sub-classes of NumberFormat.
+ *
+ * @return {@code true} if grouping is used;
+ * {@code false} otherwise
* @see #setGroupingUsed
*/
public boolean isGroupingUsed() {
@@ -594,6 +650,9 @@
/**
* Set whether or not grouping will be used in this format.
+ *
+ * @param newValue {@code true} if grouping is used;
+ * {@code false} otherwise
* @see #isGroupingUsed
*/
public void setGroupingUsed(boolean newValue) {
@@ -603,6 +662,8 @@
/**
* Returns the maximum number of digits allowed in the integer portion of a
* number.
+ *
+ * @return the maximum number of digits
* @see #setMaximumIntegerDigits
*/
public int getMaximumIntegerDigits() {
@@ -611,10 +672,11 @@
/**
* Sets the maximum number of digits allowed in the integer portion of a
- * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
+ * number. maximumIntegerDigits must be ≥ minimumIntegerDigits. If the
* new value for maximumIntegerDigits is less than the current value
* of minimumIntegerDigits, then minimumIntegerDigits will also be set to
* the new value.
+ *
* @param newValue the maximum number of integer digits to be shown; if
* less than zero, then zero is used. The concrete subclass may enforce an
* upper limit to this value appropriate to the numeric type being formatted.
@@ -630,6 +692,8 @@
/**
* Returns the minimum number of digits allowed in the integer portion of a
* number.
+ *
+ * @return the minimum number of digits
* @see #setMinimumIntegerDigits
*/
public int getMinimumIntegerDigits() {
@@ -638,10 +702,11 @@
/**
* Sets the minimum number of digits allowed in the integer portion of a
- * number. minimumIntegerDigits must be <= maximumIntegerDigits. If the
+ * number. minimumIntegerDigits must be ≤ maximumIntegerDigits. If the
* new value for minimumIntegerDigits exceeds the current value
* of maximumIntegerDigits, then maximumIntegerDigits will also be set to
* the new value
+ *
* @param newValue the minimum number of integer digits to be shown; if
* less than zero, then zero is used. The concrete subclass may enforce an
* upper limit to this value appropriate to the numeric type being formatted.
@@ -657,6 +722,8 @@
/**
* Returns the maximum number of digits allowed in the fraction portion of a
* number.
+ *
+ * @return the maximum number of digits.
* @see #setMaximumFractionDigits
*/
public int getMaximumFractionDigits() {
@@ -665,10 +732,11 @@
/**
* Sets the maximum number of digits allowed in the fraction portion of a
- * number. maximumFractionDigits must be >= minimumFractionDigits. If the
+ * number. maximumFractionDigits must be ≥ minimumFractionDigits. If the
* new value for maximumFractionDigits is less than the current value
* of minimumFractionDigits, then minimumFractionDigits will also be set to
* the new value.
+ *
* @param newValue the maximum number of fraction digits to be shown; if
* less than zero, then zero is used. The concrete subclass may enforce an
* upper limit to this value appropriate to the numeric type being formatted.
@@ -684,6 +752,8 @@
/**
* Returns the minimum number of digits allowed in the fraction portion of a
* number.
+ *
+ * @return the minimum number of digits
* @see #setMinimumFractionDigits
*/
public int getMinimumFractionDigits() {
@@ -692,10 +762,11 @@
/**
* Sets the minimum number of digits allowed in the fraction portion of a
- * number. minimumFractionDigits must be <= maximumFractionDigits. If the
+ * number. minimumFractionDigits must be ≤ maximumFractionDigits. If the
* new value for minimumFractionDigits exceeds the current value
* of maximumFractionDigits, then maximumIntegerDigits will also be set to
* the new value
+ *
* @param newValue the minimum number of fraction digits to be shown; if
* less than zero, then zero is used. The concrete subclass may enforce an
* upper limit to this value appropriate to the numeric type being formatted.