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

6354947: [Fmt-*] Clarify DecimalFormat description of FieldPosition use

Browse source 
Reviewed-by: naoto, rriggs
This commit is contained in:
Nishit Jain 2017-11-30 13:31:30 +05:30 • committed by Nishit Jain
parent e6056f2e91
commit 5102cb9120
5 changed files with 131 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

90
src/java.base/share/classes/java/text/DateFormat.java
View file

@ -294,28 +294,27 @@ public abstract class DateFormat extends Format {
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 @@ public abstract class DateFormat extends Format {
}
/**
* 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)
{

50
src/java.base/share/classes/java/text/DecimalFormat.java
View file

@ -480,8 +480,14 @@ public class DecimalFormat extends NumberFormat {
* @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 @@ public class DecimalFormat extends NumberFormat {
* 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 @@ public class DecimalFormat extends NumberFormat {
* 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 @@ public class DecimalFormat extends NumberFormat {
* 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 @@ public class DecimalFormat extends NumberFormat {
* 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

18
src/java.base/share/classes/java/text/MessageFormat.java
View file

@ -820,8 +820,8 @@ public class MessageFormat extends Format {
*
* @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 @@ public class MessageFormat extends Format {
*
* @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 @@ public class MessageFormat extends Format {
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

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

@ -240,8 +240,14 @@ public abstract class NumberFormat extends Format {
* @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 @@ public abstract class NumberFormat extends 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
* @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 @@ public abstract class NumberFormat extends 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
* @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

15
src/java.base/share/classes/java/text/SimpleDateFormat.java
View file

@ -942,8 +942,19 @@ public class SimpleDateFormat extends DateFormat {
*
* @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}.
*/