6354947: [Fmt-*] Clarify DecimalFormat description of FieldPosition use
Reviewed-by: naoto, rriggs
Contributed-by: nishit.jain@oracle.com
--- a/src/java.base/share/classes/java/text/DateFormat.java Fri Nov 24 14:07:59 2017 +0100
+++ b/src/java.base/share/classes/java/text/DateFormat.java Thu Nov 30 13:31:30 2017 +0530
@@ -294,28 +294,27 @@
private static final long serialVersionUID = 7218322306649953788L;
/**
- * Overrides Format.
- * Formats a time object into a time string. Examples of time objects
- * are a time value expressed in milliseconds and a Date object.
- * @param obj must be a Number or a Date.
- * @param toAppendTo the string buffer for the returning time string.
- * @return the string buffer passed in as toAppendTo, with formatted text appended.
- * @param fieldPosition keeps track of the position of the field
- * within the returned string.
- * On input: an alignment field,
- * if desired. On output: the offsets of the alignment field. For
- * example, given a time text "1996.07.10 AD at 15:08:56 PDT",
- * if the given fieldPosition is DateFormat.YEAR_FIELD, the
- * begin index and end index of fieldPosition will be set to
- * 0 and 4, respectively.
- * Notice that if the same time field appears
- * more than once in a pattern, the fieldPosition will be set for the first
- * occurrence of that time field. For instance, formatting a Date to
- * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern
- * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,
- * the begin index and end index of fieldPosition will be set to
- * 5 and 8, respectively, for the first occurrence of the timezone
- * pattern character 'z'.
+ * Formats the given {@code Object} into a date-time string. The formatted
+ * string is appended to the given {@code StringBuffer}.
+ *
+ * @param obj Must be a {@code Date} or a {@code Number} representing a
+ * millisecond offset from the <a href="../util/Calendar.html#Epoch">Epoch</a>.
+ * @param toAppendTo The string buffer for the returning date-time string.
+ * @param fieldPosition keeps track on the position of the field within
+ * the returned string. For example, given a date-time text
+ * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition}
+ * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 0 and 4, respectively.
+ * Notice that if the same date-time field appears more than once in a
+ * pattern, the {@code fieldPosition} will be set for the first occurrence
+ * of that date-time field. For instance, formatting a {@code Date} to the
+ * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the
+ * pattern {@code "h a z (zzzz)"} and the alignment field
+ * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 5 and 8, respectively, for the
+ * first occurrence of the timezone pattern character {@code 'z'}.
+ * @return the string buffer passed in as {@code toAppendTo},
+ * with formatted text appended.
* @exception IllegalArgumentException if the {@code Format} cannot format
* the given {@code obj}.
* @see java.text.Format
@@ -333,34 +332,35 @@
}
/**
- * Formats a Date into a date/time string.
- * @param date a Date to be formatted into a date/time string.
- * @param toAppendTo the string buffer for the returning date/time string.
- * @param fieldPosition keeps track of the position of the field
- * within the returned string.
- * On input: an alignment field,
- * if desired. On output: the offsets of the alignment field. For
- * example, given a time text "1996.07.10 AD at 15:08:56 PDT",
- * if the given fieldPosition is DateFormat.YEAR_FIELD, the
- * begin index and end index of fieldPosition will be set to
- * 0 and 4, respectively.
- * Notice that if the same time field appears
- * more than once in a pattern, the fieldPosition will be set for the first
- * occurrence of that time field. For instance, formatting a Date to
- * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern
- * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,
- * the begin index and end index of fieldPosition will be set to
- * 5 and 8, respectively, for the first occurrence of the timezone
- * pattern character 'z'.
- * @return the string buffer passed in as toAppendTo, with formatted text appended.
+ * Formats a {@link Date} into a date-time string. The formatted
+ * string is appended to the given {@code StringBuffer}.
+ *
+ * @param date a Date to be formatted into a date-time string.
+ * @param toAppendTo the string buffer for the returning date-time string.
+ * @param fieldPosition keeps track on the position of the field within
+ * the returned string. For example, given a date-time text
+ * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition}
+ * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 0 and 4, respectively.
+ * Notice that if the same date-time field appears more than once in a
+ * pattern, the {@code fieldPosition} will be set for the first occurrence
+ * of that date-time field. For instance, formatting a {@code Date} to the
+ * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the
+ * pattern {@code "h a z (zzzz)"} and the alignment field
+ * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 5 and 8, respectively, for the
+ * first occurrence of the timezone pattern character {@code 'z'}.
+ * @return the string buffer passed in as {@code toAppendTo}, with formatted
+ * text appended.
*/
public abstract StringBuffer format(Date date, StringBuffer toAppendTo,
FieldPosition fieldPosition);
/**
- * Formats a Date into a date/time string.
- * @param date the time value to be formatted into a time string.
- * @return the formatted time string.
+ * Formats a {@link Date} into a date-time string.
+ *
+ * @param date the time value to be formatted into a date-time string.
+ * @return the formatted date-time string.
*/
public final String format(Date date)
{
--- a/src/java.base/share/classes/java/text/DecimalFormat.java Fri Nov 24 14:07:59 2017 +0100
+++ b/src/java.base/share/classes/java/text/DecimalFormat.java Thu Nov 30 13:31:30 2017 +0530
@@ -480,8 +480,14 @@
* @param number the number to format
* @param toAppendTo the <code>StringBuffer</code> to which the formatted
* text is to be appended
- * @param pos On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param pos keeps track on the position of the field within the
+ * returned string. For example, for formatting a number
+ * {@code 1234567.89} in {@code Locale.US} locale,
+ * if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 9, respectively for the output string
+ * {@code 1,234,567.89}.
* @return the value passed in as <code>toAppendTo</code>
* @exception IllegalArgumentException if <code>number</code> is
* null or not an instance of <code>Number</code>.
@@ -517,8 +523,14 @@
* Formats a double to produce a string.
* @param number The double to format
* @param result where the text is to be appended
- * @param fieldPosition On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param fieldPosition keeps track on the position of the field within
+ * the returned string. For example, for formatting
+ * a number {@code 1234567.89} in {@code Locale.US}
+ * locale, if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 9, respectively for the output string
+ * {@code 1,234,567.89}.
* @exception NullPointerException if {@code result} or
* {@code fieldPosition} is {@code null}
* @exception ArithmeticException if rounding is needed with rounding
@@ -637,8 +649,14 @@
* Format a long to produce a string.
* @param number The long to format
* @param result where the text is to be appended
- * @param fieldPosition On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param fieldPosition keeps track on the position of the field within
+ * the returned string. For example, for formatting
+ * a number {@code 123456789} in {@code Locale.US}
+ * locale, if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 11, respectively for the output string
+ * {@code 123,456,789}.
* @exception NullPointerException if {@code result} or
* {@code fieldPosition} is {@code null}
* @exception ArithmeticException if rounding is needed with rounding
@@ -727,8 +745,14 @@
* Formats a BigDecimal to produce a string.
* @param number The BigDecimal to format
* @param result where the text is to be appended
- * @param fieldPosition On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param fieldPosition keeps track on the position of the field within
+ * the returned string. For example, for formatting
+ * a number {@code 1234567.89} in {@code Locale.US}
+ * locale, if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 9, respectively for the output string
+ * {@code 1,234,567.89}.
* @return The formatted number string
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
@@ -780,8 +804,14 @@
* Format a BigInteger to produce a string.
* @param number The BigInteger to format
* @param result where the text is to be appended
- * @param fieldPosition On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param fieldPosition keeps track on the position of the field within
+ * the returned string. For example, for formatting
+ * a number {@code 123456789} in {@code Locale.US}
+ * locale, if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 11, respectively for the output string
+ * {@code 123,456,789}.
* @return The formatted number string
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
--- a/src/java.base/share/classes/java/text/MessageFormat.java Fri Nov 24 14:07:59 2017 +0100
+++ b/src/java.base/share/classes/java/text/MessageFormat.java Thu Nov 30 13:31:30 2017 +0530
@@ -820,8 +820,8 @@
*
* @param arguments an array of objects to be formatted and substituted.
* @param result where text is appended.
- * @param pos On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param pos keeps track on the position of the first replaced argument
+ in the output string.
* @return the string buffer passed in as {@code result}, with formatted
* text appended
* @exception IllegalArgumentException if an argument in the
@@ -868,8 +868,8 @@
*
* @param arguments an array of objects to be formatted and substituted.
* @param result where text is appended.
- * @param pos On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param pos keeps track on the position of the first replaced argument
+ * in the output string.
* @exception IllegalArgumentException if an argument in the
* <code>arguments</code> array is not of the type
* expected by the format element(s) that use it.
@@ -1239,11 +1239,11 @@
private int maxOffset = -1;
/**
- * Internal routine used by format. If <code>characterIterators</code> is
- * non-null, AttributedCharacterIterator will be created from the
- * subformats as necessary. If <code>characterIterators</code> is null
- * and <code>fp</code> is non-null and identifies
- * <code>Field.MESSAGE_ARGUMENT</code>, the location of
+ * Internal routine used by format. If {@code characterIterators} is
+ * {@code non-null}, AttributedCharacterIterator will be created from the
+ * subformats as necessary. If {@code characterIterators} is {@code null}
+ * and {@code fp} is {@code non-null} and identifies
+ * {@code Field.ARGUMENT} as the field attribute, the location of
* the first replaced argument will be set in it.
*
* @exception IllegalArgumentException if an argument in the
--- a/src/java.base/share/classes/java/text/NumberFormat.java Fri Nov 24 14:07:59 2017 +0100
+++ b/src/java.base/share/classes/java/text/NumberFormat.java Thu Nov 30 13:31:30 2017 +0530
@@ -240,8 +240,14 @@
* @param number the number to format
* @param toAppendTo the <code>StringBuffer</code> to which the formatted
* text is to be appended
- * @param pos On input: an alignment field, if desired.
- * On output: the offsets of the alignment field.
+ * @param pos keeps track on the position of the field within the
+ * returned string. For example, for formatting a number
+ * {@code 1234567.89} in {@code Locale.US} locale,
+ * if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 9, respectively for the output string
+ * {@code 1,234,567.89}.
* @return the value passed in as <code>toAppendTo</code>
* @exception IllegalArgumentException if <code>number</code> is
* null or not an instance of <code>Number</code>.
@@ -342,7 +348,14 @@
* @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
+ * @param pos keeps track on the position of the field within the
+ * returned string. For example, for formatting a number
+ * {@code 1234567.89} in {@code Locale.US} locale,
+ * if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 9, respectively for the output string
+ * {@code 1,234,567.89}.
* @return the formatted StringBuffer
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
@@ -358,7 +371,14 @@
* @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
+ * @param pos keeps track on the position of the field within the
+ * returned string. For example, for formatting a number
+ * {@code 123456789} in {@code Locale.US} locale,
+ * if the given {@code fieldPosition} is
+ * {@link NumberFormat#INTEGER_FIELD}, the begin index
+ * and end index of {@code fieldPosition} will be set
+ * to 0 and 11, respectively for the output string
+ * {@code 123,456,789}.
* @return the formatted StringBuffer
* @exception ArithmeticException if rounding is needed with rounding
* mode being set to RoundingMode.UNNECESSARY
--- a/src/java.base/share/classes/java/text/SimpleDateFormat.java Fri Nov 24 14:07:59 2017 +0100
+++ b/src/java.base/share/classes/java/text/SimpleDateFormat.java Thu Nov 30 13:31:30 2017 +0530
@@ -942,8 +942,19 @@
*
* @param date the date-time value to be formatted into a date-time string.
* @param toAppendTo where the new date-time text is to be appended.
- * @param pos the formatting position. On input: an alignment field,
- * if desired. On output: the offsets of the alignment field.
+ * @param pos keeps track on the position of the field within
+ * the returned string. For example, given a date-time text
+ * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition}
+ * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 0 and 4, respectively.
+ * Notice that if the same date-time field appears more than once in a
+ * pattern, the {@code fieldPosition} will be set for the first occurrence
+ * of that date-time field. For instance, formatting a {@code Date} to the
+ * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the
+ * pattern {@code "h a z (zzzz)"} and the alignment field
+ * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 5 and 8, respectively, for the
+ * first occurrence of the timezone pattern character {@code 'z'}.
* @return the formatted date-time string.
* @exception NullPointerException if any of the parameters is {@code null}.
*/