src/share/classes/java/util/Formatter.java
Print this page
rev 7582 : 8019857: Fix doclint errors in java.util.Format*
Summary: Fix doclint errors in java.util.Format*.
Reviewed-by: TBD
Contributed-by: Brian Burkhalter <brian.burkhalter@oracle.com>
*** 839,849 ****
*
* </ol>
*
* <p> Numeric types will be formatted according to the following algorithm:
*
! * <p><b><a name="l10n algorithm"> Number Localization Algorithm</a></b>
*
* <p> After digits are obtained for the integer part, fractional part, and
* exponent (as appropriate for the data type), the following transformation
* is applied:
*
--- 839,849 ----
*
* </ol>
*
* <p> Numeric types will be formatted according to the following algorithm:
*
! * <p><b><a name="L10nAlgorithm"> Number Localization Algorithm</a></b>
*
* <p> After digits are obtained for the integer part, fractional part, and
* exponent (as appropriate for the data type), the following transformation
* is applied:
*
*** 858,868 ****
* <li> If a decimal separator is present, a locale-specific {@linkplain
* java.text.DecimalFormatSymbols#getDecimalSeparator decimal separator} is
* substituted.
*
* <li> If the {@code ','} (<tt>'\u002c'</tt>)
! * <a name="l10n group">flag</a> is given, then the locale-specific {@linkplain
* java.text.DecimalFormatSymbols#getGroupingSeparator grouping separator} is
* inserted by scanning the integer part of the string from least significant
* to most significant digits and inserting a separator at intervals defined by
* the locale's {@linkplain java.text.DecimalFormat#getGroupingSize() grouping
* size}.
--- 858,868 ----
* <li> If a decimal separator is present, a locale-specific {@linkplain
* java.text.DecimalFormatSymbols#getDecimalSeparator decimal separator} is
* substituted.
*
* <li> If the {@code ','} (<tt>'\u002c'</tt>)
! * <a name="L10nGroup">flag</a> is given, then the locale-specific {@linkplain
* java.text.DecimalFormatSymbols#getGroupingSeparator grouping separator} is
* inserted by scanning the integer part of the string from least significant
* to most significant digits and inserting a separator at intervals defined by
* the locale's {@linkplain java.text.DecimalFormat#getGroupingSize() grouping
* size}.
*** 900,910 ****
* <table cellpadding=5 summary="IntConv">
*
* <tr><td valign="top"> {@code 'd'}
* <td valign="top"> <tt>'\u0054'</tt>
* <td> Formats the argument as a decimal integer. The <a
! * href="#l10n algorithm">localization algorithm</a> is applied.
*
* <p> If the {@code '0'} flag is given and the value is negative, then
* the zero padding will occur after the sign.
*
* <p> If the {@code '#'} flag is given then a {@link
--- 900,910 ----
* <table cellpadding=5 summary="IntConv">
*
* <tr><td valign="top"> {@code 'd'}
* <td valign="top"> <tt>'\u0054'</tt>
* <td> Formats the argument as a decimal integer. The <a
! * href="#L10nAlgorithm">localization algorithm</a> is applied.
*
* <p> If the {@code '0'} flag is given and the value is negative, then
* the zero padding will occur after the sign.
*
* <p> If the {@code '#'} flag is given then a {@link
*** 1009,1019 ****
*
* <tr><td valign="top"> {@code ','}
* <td valign="top"> <tt>'\u002c'</tt>
* <td> Requires the output to include the locale-specific {@linkplain
* java.text.DecimalFormatSymbols#getGroupingSeparator group separators} as
! * described in the <a href="#l10n group">"group" section</a> of the
* localization algorithm.
*
* <tr><td valign="top"> {@code '('}
* <td valign="top"> <tt>'\u0028'</tt>
* <td> Requires the output to prepend a {@code '('}
--- 1009,1019 ----
*
* <tr><td valign="top"> {@code ','}
* <td valign="top"> <tt>'\u002c'</tt>
* <td> Requires the output to include the locale-specific {@linkplain
* java.text.DecimalFormatSymbols#getGroupingSeparator group separators} as
! * described in the <a href="#L10nGroup">"group" section</a> of the
* localization algorithm.
*
* <tr><td valign="top"> {@code '('}
* <td valign="top"> <tt>'\u0028'</tt>
* <td> Requires the output to prepend a {@code '('}
*** 1058,1068 ****
* <table cellpadding=5 summary="BIntConv">
*
* <tr><td valign="top"> {@code 'd'}
* <td valign="top"> <tt>'\u0054'</tt>
* <td> Requires the output to be formatted as a decimal integer. The <a
! * href="#l10n algorithm">localization algorithm</a> is applied.
*
* <p> If the {@code '#'} flag is given {@link
* FormatFlagsConversionMismatchException} will be thrown.
*
* <tr><td valign="top"> {@code 'o'}
--- 1058,1068 ----
* <table cellpadding=5 summary="BIntConv">
*
* <tr><td valign="top"> {@code 'd'}
* <td valign="top"> <tt>'\u0054'</tt>
* <td> Requires the output to be formatted as a decimal integer. The <a
! * href="#L10nAlgorithm">localization algorithm</a> is applied.
*
* <p> If the {@code '#'} flag is given {@link
* FormatFlagsConversionMismatchException} will be thrown.
*
* <tr><td valign="top"> {@code 'o'}
*** 1153,1163 ****
*
* <tr><td valign="top"> {@code 'e'}
* <td valign="top"> <tt>'\u0065'</tt>
* <td> Requires the output to be formatted using <a
* name="scientific">computerized scientific notation</a>. The <a
! * href="#l10n algorithm">localization algorithm</a> is applied.
*
* <p> The formatting of the magnitude <i>m</i> depends upon its value.
*
* <p> If <i>m</i> is NaN or infinite, the literal strings "NaN" or
* "Infinity", respectively, will be output. These values are not
--- 1153,1163 ----
*
* <tr><td valign="top"> {@code 'e'}
* <td valign="top"> <tt>'\u0065'</tt>
* <td> Requires the output to be formatted using <a
* name="scientific">computerized scientific notation</a>. The <a
! * href="#L10nAlgorithm">localization algorithm</a> is applied.
*
* <p> The formatting of the magnitude <i>m</i> depends upon its value.
*
* <p> If <i>m</i> is NaN or infinite, the literal strings "NaN" or
* "Infinity", respectively, will be output. These values are not
*** 1166,1176 ****
* <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
* will be {@code "+00"}.
*
* <p> Otherwise, the result is a string that represents the sign and
* magnitude (absolute value) of the argument. The formatting of the sign
! * is described in the <a href="#l10n algorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
* <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
--- 1166,1176 ----
* <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
* will be {@code "+00"}.
*
* <p> Otherwise, the result is a string that represents the sign and
* magnitude (absolute value) of the argument. The formatting of the sign
! * is described in the <a href="#L10nAlgorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
* <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
*** 1205,1215 ****
* will be {@code 'E'} (<tt>'\u0045'</tt>).
*
* <tr><td valign="top"> {@code 'g'}
* <td valign="top"> <tt>'\u0067'</tt>
* <td> Requires the output to be formatted in general scientific notation
! * as described below. The <a href="#l10n algorithm">localization
* algorithm</a> is applied.
*
* <p> After rounding for the precision, the formatting of the resulting
* magnitude <i>m</i> depends on its value.
*
--- 1205,1215 ----
* will be {@code 'E'} (<tt>'\u0045'</tt>).
*
* <tr><td valign="top"> {@code 'g'}
* <td valign="top"> <tt>'\u0067'</tt>
* <td> Requires the output to be formatted in general scientific notation
! * as described below. The <a href="#L10nAlgorithm">localization
* algorithm</a> is applied.
*
* <p> After rounding for the precision, the formatting of the resulting
* magnitude <i>m</i> depends on its value.
*
*** 1234,1249 ****
* <td> The upper-case variant of {@code 'g'}.
*
* <tr><td valign="top"> {@code 'f'}
* <td valign="top"> <tt>'\u0066'</tt>
* <td> Requires the output to be formatted using <a name="decimal">decimal
! * format</a>. The <a href="#l10n algorithm">localization algorithm</a> is
* applied.
*
* <p> The result is a string that represents the sign and magnitude
* (absolute value) of the argument. The formatting of the sign is
! * described in the <a href="#l10n algorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> If <i>m</i> NaN or infinite, the literal strings "NaN" or
* "Infinity", respectively, will be output. These values are not
--- 1234,1249 ----
* <td> The upper-case variant of {@code 'g'}.
*
* <tr><td valign="top"> {@code 'f'}
* <td valign="top"> <tt>'\u0066'</tt>
* <td> Requires the output to be formatted using <a name="decimal">decimal
! * format</a>. The <a href="#L10nAlgorithm">localization algorithm</a> is
* applied.
*
* <p> The result is a string that represents the sign and magnitude
* (absolute value) of the argument. The formatting of the sign is
! * described in the <a href="#L10nAlgorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> If <i>m</i> NaN or infinite, the literal strings "NaN" or
* "Infinity", respectively, will be output. These values are not
*** 1380,1399 ****
*
* <tr><td valign="top"> {@code 'e'}
* <td valign="top"> <tt>'\u0065'</tt>
* <td> Requires the output to be formatted using <a
* name="bscientific">computerized scientific notation</a>. The <a
! * href="#l10n algorithm">localization algorithm</a> is applied.
*
* <p> The formatting of the magnitude <i>m</i> depends upon its value.
*
* <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
* will be {@code "+00"}.
*
* <p> Otherwise, the result is a string that represents the sign and
* magnitude (absolute value) of the argument. The formatting of the sign
! * is described in the <a href="#l10n algorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
* <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
--- 1380,1399 ----
*
* <tr><td valign="top"> {@code 'e'}
* <td valign="top"> <tt>'\u0065'</tt>
* <td> Requires the output to be formatted using <a
* name="bscientific">computerized scientific notation</a>. The <a
! * href="#L10nAlgorithm">localization algorithm</a> is applied.
*
* <p> The formatting of the magnitude <i>m</i> depends upon its value.
*
* <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
* will be {@code "+00"}.
*
* <p> Otherwise, the result is a string that represents the sign and
* magnitude (absolute value) of the argument. The formatting of the sign
! * is described in the <a href="#L10nAlgorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
* <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
*** 1426,1436 ****
* will be {@code 'E'} (<tt>'\u0045'</tt>).
*
* <tr><td valign="top"> {@code 'g'}
* <td valign="top"> <tt>'\u0067'</tt>
* <td> Requires the output to be formatted in general scientific notation
! * as described below. The <a href="#l10n algorithm">localization
* algorithm</a> is applied.
*
* <p> After rounding for the precision, the formatting of the resulting
* magnitude <i>m</i> depends on its value.
*
--- 1426,1436 ----
* will be {@code 'E'} (<tt>'\u0045'</tt>).
*
* <tr><td valign="top"> {@code 'g'}
* <td valign="top"> <tt>'\u0067'</tt>
* <td> Requires the output to be formatted in general scientific notation
! * as described below. The <a href="#L10nAlgorithm">localization
* algorithm</a> is applied.
*
* <p> After rounding for the precision, the formatting of the resulting
* magnitude <i>m</i> depends on its value.
*
*** 1455,1470 ****
* <td> The upper-case variant of {@code 'g'}.
*
* <tr><td valign="top"> {@code 'f'}
* <td valign="top"> <tt>'\u0066'</tt>
* <td> Requires the output to be formatted using <a name="bdecimal">decimal
! * format</a>. The <a href="#l10n algorithm">localization algorithm</a> is
* applied.
*
* <p> The result is a string that represents the sign and magnitude
* (absolute value) of the argument. The formatting of the sign is
! * described in the <a href="#l10n algorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> The magnitude is formatted as the integer part of <i>m</i>, with no
* leading zeroes, followed by the decimal separator followed by one or
--- 1455,1470 ----
* <td> The upper-case variant of {@code 'g'}.
*
* <tr><td valign="top"> {@code 'f'}
* <td valign="top"> <tt>'\u0066'</tt>
* <td> Requires the output to be formatted using <a name="bdecimal">decimal
! * format</a>. The <a href="#L10nAlgorithm">localization algorithm</a> is
* applied.
*
* <p> The result is a string that represents the sign and magnitude
* (absolute value) of the argument. The formatting of the sign is
! * described in the <a href="#L10nAlgorithm">localization
* algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
* value.
*
* <p> The magnitude is formatted as the integer part of <i>m</i>, with no
* leading zeroes, followed by the decimal separator followed by one or
*** 1719,1729 ****
*
* <p> The {@code '-'} flag defined for <a href="#dFlags">General
* conversions</a> applies. If the {@code '#'} flag is given, then a {@link
* FormatFlagsConversionMismatchException} will be thrown.
*
! * <p> The <a name="dtWidth">width</a> is the minimum number of characters to
* be written to the output. If the length of the converted value is less than
* the {@code width} then the output will be padded by spaces
* (<tt>'\u0020'</tt>) until the total number of characters equals width.
* The padding is on the left by default. If the {@code '-'} flag is given
* then the padding will be on the right. If width is not specified then there
--- 1719,1729 ----
*
* <p> The {@code '-'} flag defined for <a href="#dFlags">General
* conversions</a> applies. If the {@code '#'} flag is given, then a {@link
* FormatFlagsConversionMismatchException} will be thrown.
*
! * <p> The width is the minimum number of characters to
* be written to the output. If the length of the converted value is less than
* the {@code width} then the output will be padded by spaces
* (<tt>'\u0020'</tt>) until the total number of characters equals width.
* The padding is on the left by default. If the {@code '-'} flag is given
* then the padding will be on the right. If width is not specified then there
*** 1739,1749 ****
* <table cellpadding=5 summary="DTConv">
*
* <tr><td valign="top">{@code '%'}
* <td> The result is a literal {@code '%'} (<tt>'\u0025'</tt>)
*
! * <p> The <a name="dtWidth">width</a> is the minimum number of characters to
* be written to the output including the {@code '%'}. If the length of the
* converted value is less than the {@code width} then the output will be
* padded by spaces (<tt>'\u0020'</tt>) until the total number of
* characters equals width. The padding is on the left. If width is not
* specified then just the {@code '%'} is output.
--- 1739,1749 ----
* <table cellpadding=5 summary="DTConv">
*
* <tr><td valign="top">{@code '%'}
* <td> The result is a literal {@code '%'} (<tt>'\u0025'</tt>)
*
! * <p> The width is the minimum number of characters to
* be written to the output including the {@code '%'}. If the length of the
* converted value is less than the {@code width} then the output will be
* padded by spaces (<tt>'\u0020'</tt>) until the total number of
* characters equals width. The padding is on the left. If width is not
* specified then just the {@code '%'} is output.
*** 2588,2598 ****
public void print(Object arg, Locale l)
throws IOException { a.append(s); }
public String toString() { return s; }
}
! public enum BigDecimalLayoutForm { SCIENTIFIC, DECIMAL_FLOAT };
private class FormatSpecifier implements FormatString {
private int index = -1;
private Flags f = Flags.NONE;
private int width;
--- 2588,2611 ----
public void print(Object arg, Locale l)
throws IOException { a.append(s); }
public String toString() { return s; }
}
! /**
! * Enum for {@code BigDecimal} formatting.
! */
! public enum BigDecimalLayoutForm {
! /**
! * Format the {@code BigDecimal} in computerized scientific notation.
! */
! SCIENTIFIC,
!
! /**
! * Format the {@code BigDecimal} as a decimal number.
! */
! DECIMAL_FLOAT
! };
private class FormatSpecifier implements FormatString {
private int index = -1;
private Flags f = Flags.NONE;
private int width;