609 * or {@code 'd'} applied to {@code byte}, {@link Byte}, {@code short}, {@link
610 * Short}, {@code int} and {@link Integer}, {@code long}, and {@link Long}.
611 *
612 * <p> <sup>5</sup> For {@code 'e'}, {@code 'E'}, {@code 'f'},
613 * {@code 'g'}, and {@code 'G'} conversions only.
614 *
615 * <p> Any characters not explicitly defined as flags are illegal and are
616 * reserved for future extensions.
617 *
618 * <h4> Width </h4>
619 *
620 * <p> The width is the minimum number of characters to be written to the
621 * output. For the line separator conversion, width is not applicable; if it
622 * is provided, an exception will be thrown.
623 *
624 * <h4> Precision </h4>
625 *
626 * <p> For general argument types, the precision is the maximum number of
627 * characters to be written to the output.
628 *
629 * <p> For the floating-point conversions {@code 'e'}, {@code 'E'}, and
630 * {@code 'f'} the precision is the number of digits after the decimal
631 * separator. If the conversion is {@code 'g'} or {@code 'G'}, then the
632 * precision is the total number of digits in the resulting magnitude after
633 * rounding. If the conversion is {@code 'a'} or {@code 'A'}, then the
634 * precision must not be specified.
635 *
636 * <p> For character, integral, and date/time argument types and the percent
637 * and line separator conversions, the precision is not applicable; if a
638 * precision is provided, an exception will be thrown.
639 *
640 * <h4> Argument Index </h4>
641 *
642 * <p> The argument index is a decimal integer indicating the position of the
643 * argument in the argument list. The first argument is referenced by
644 * "{@code 1$}", the second by "{@code 2$}", etc.
645 *
646 * <p> Another way to reference arguments by position is to use the
647 * {@code '<'} (<tt>'\u003c'</tt>) flag, which causes the argument for
648 * the previous format specifier to be re-used. For example, the following two
649 * statements would produce identical strings:
650 *
651 * <blockquote><pre>
652 * Calendar c = ...;
653 * String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
654 *
1280 * {@code '+'} flag is given then the result will begin with {@code '+'}
1281 * (<tt>'\u002b'</tt>).
1282 *
1283 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1284 *
1285 * <ul>
1286 *
1287 * <li> If the value is NaN or infinite, the literal strings "NaN" or
1288 * "Infinity", respectively, will be output.
1289 *
1290 * <li> If <i>m</i> is zero then it is represented by the string
1291 * {@code "0x0.0p0"}.
1292 *
1293 * <li> If <i>m</i> is a {@code double} value with a normalized
1294 * representation then substrings are used to represent the significand and
1295 * exponent fields. The significand is represented by the characters
1296 * {@code "0x1."} followed by the hexadecimal representation of the rest
1297 * of the significand as a fraction. The exponent is represented by
1298 * {@code 'p'} (<tt>'\u0070'</tt>) followed by a decimal string of the
1299 * unbiased exponent as if produced by invoking {@link
1300 * Integer#toString(int) Integer.toString} on the exponent value.
1301 *
1302 * <li> If <i>m</i> is a {@code double} value with a subnormal
1303 * representation then the significand is represented by the characters
1304 * {@code '0x0.'} followed by the hexadecimal representation of the rest
1305 * of the significand as a fraction. The exponent is represented by
1306 * {@code 'p-1022'}. Note that there must be at least one nonzero digit
1307 * in a subnormal significand.
1308 *
1309 * </ul>
1310 *
1311 * <p> If the {@code '('} or {@code ','} flags are given, then a {@link
1312 * FormatFlagsConversionMismatchException} will be thrown.
1313 *
1314 * <tr><td valign="top"> {@code 'A'}
1315 * <td valign="top"> <tt>'\u0041'</tt>
1316 * <td> The upper-case variant of {@code 'a'}. The entire string
1317 * representing the number will be converted to upper case including the
1318 * {@code 'x'} (<tt>'\u0078'</tt>) and {@code 'p'}
1319 * (<tt>'\u0070'</tt> and all hexadecimal digits {@code 'a'} -
1320 * {@code 'f'} (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
1321 *
1322 * </table>
1323 *
1324 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1325 * Long apply.
1326 *
1327 * <p> If the {@code '#'} flag is given, then the decimal separator will
1350 * separators, decimal separators, exponential symbol, radix indicator,
1351 * parentheses, and strings representing infinity and NaN as applicable. If
1352 * the length of the converted value is less than the width then the output
1353 * will be padded by spaces (<tt>'\u0020'</tt>) until the total number of
1354 * characters equals width. The padding is on the left by default. If the
1355 * {@code '-'} flag is given then the padding will be on the right. If width
1356 * is not specified then there is no minimum.
1357 *
1358 * <p> If the <a name="floatDPrec">conversion</a> is {@code 'e'},
1359 * {@code 'E'} or {@code 'f'}, then the precision is the number of digits
1360 * after the decimal separator. If the precision is not specified, then it is
1361 * assumed to be {@code 6}.
1362 *
1363 * <p> If the conversion is {@code 'g'} or {@code 'G'}, then the precision is
1364 * the total number of significant digits in the resulting magnitude after
1365 * rounding. If the precision is not specified, then the default value is
1366 * {@code 6}. If the precision is {@code 0}, then it is taken to be
1367 * {@code 1}.
1368 *
1369 * <p> If the conversion is {@code 'a'} or {@code 'A'}, then the precision
1370 * is the number of hexadecimal digits after the decimal separator. If the
1371 * precision is not provided, then all of the digits as returned by {@link
1372 * Double#toHexString(double)} will be output.
1373 *
1374 * <p><a name="dnbdec"><b> BigDecimal </b></a>
1375 *
1376 * <p> The following conversions may be applied {@link java.math.BigDecimal
1377 * BigDecimal}.
1378 *
1379 * <table cellpadding=5 summary="floatConv">
1380 *
1381 * <tr><td valign="top"> {@code 'e'}
1382 * <td valign="top"> <tt>'\u0065'</tt>
1383 * <td> Requires the output to be formatted using <a
1384 * name="bscientific">computerized scientific notation</a>. The <a
1385 * href="#L10nAlgorithm">localization algorithm</a> is applied.
1386 *
1387 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1388 *
1389 * <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1390 * will be {@code "+00"}.
|
609 * or {@code 'd'} applied to {@code byte}, {@link Byte}, {@code short}, {@link
610 * Short}, {@code int} and {@link Integer}, {@code long}, and {@link Long}.
611 *
612 * <p> <sup>5</sup> For {@code 'e'}, {@code 'E'}, {@code 'f'},
613 * {@code 'g'}, and {@code 'G'} conversions only.
614 *
615 * <p> Any characters not explicitly defined as flags are illegal and are
616 * reserved for future extensions.
617 *
618 * <h4> Width </h4>
619 *
620 * <p> The width is the minimum number of characters to be written to the
621 * output. For the line separator conversion, width is not applicable; if it
622 * is provided, an exception will be thrown.
623 *
624 * <h4> Precision </h4>
625 *
626 * <p> For general argument types, the precision is the maximum number of
627 * characters to be written to the output.
628 *
629 * <p> For the floating-point conversions {@code 'a'}, {@code 'A'}, {@code 'e'},
630 * {@code 'E'}, and {@code 'f'} the precision is the number of digits after the
631 * radix point. If the conversion is {@code 'g'} or {@code 'G'}, then the
632 * precision is the total number of digits in the resulting magnitude after
633 * rounding.
634 *
635 * <p> For character, integral, and date/time argument types and the percent
636 * and line separator conversions, the precision is not applicable; if a
637 * precision is provided, an exception will be thrown.
638 *
639 * <h4> Argument Index </h4>
640 *
641 * <p> The argument index is a decimal integer indicating the position of the
642 * argument in the argument list. The first argument is referenced by
643 * "{@code 1$}", the second by "{@code 2$}", etc.
644 *
645 * <p> Another way to reference arguments by position is to use the
646 * {@code '<'} (<tt>'\u003c'</tt>) flag, which causes the argument for
647 * the previous format specifier to be re-used. For example, the following two
648 * statements would produce identical strings:
649 *
650 * <blockquote><pre>
651 * Calendar c = ...;
652 * String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
653 *
1279 * {@code '+'} flag is given then the result will begin with {@code '+'}
1280 * (<tt>'\u002b'</tt>).
1281 *
1282 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1283 *
1284 * <ul>
1285 *
1286 * <li> If the value is NaN or infinite, the literal strings "NaN" or
1287 * "Infinity", respectively, will be output.
1288 *
1289 * <li> If <i>m</i> is zero then it is represented by the string
1290 * {@code "0x0.0p0"}.
1291 *
1292 * <li> If <i>m</i> is a {@code double} value with a normalized
1293 * representation then substrings are used to represent the significand and
1294 * exponent fields. The significand is represented by the characters
1295 * {@code "0x1."} followed by the hexadecimal representation of the rest
1296 * of the significand as a fraction. The exponent is represented by
1297 * {@code 'p'} (<tt>'\u0070'</tt>) followed by a decimal string of the
1298 * unbiased exponent as if produced by invoking {@link
1299 * Integer#toString(int) Integer.toString} on the exponent value. If the
1300 * precision is specified, the value is rounded to the given number of
1301 * hexadecimal digits.
1302 *
1303 * <li> If <i>m</i> is a {@code double} value with a subnormal
1304 * representation then, unless the precision is specified to be in the range
1305 * 1 through 12, inclusive, the significand is represented by the characters
1306 * {@code '0x0.'} followed by the hexadecimal representation of the rest of
1307 * the significand as a fraction, and the exponent represented by
1308 * {@code 'p-1022'}. If the precision is in the interval
1309 * [1, 12], the subnormal value is normalized such that it
1310 * begins with the characters {@code '0x1.'}, rounded to the number of
1311 * hexadecimal digits of precision, and the exponent adjusted
1312 * accordingly. Note that there must be at least one nonzero digit in a
1313 * subnormal significand.
1314 *
1315 * </ul>
1316 *
1317 * <p> If the {@code '('} or {@code ','} flags are given, then a {@link
1318 * FormatFlagsConversionMismatchException} will be thrown.
1319 *
1320 * <tr><td valign="top"> {@code 'A'}
1321 * <td valign="top"> <tt>'\u0041'</tt>
1322 * <td> The upper-case variant of {@code 'a'}. The entire string
1323 * representing the number will be converted to upper case including the
1324 * {@code 'x'} (<tt>'\u0078'</tt>) and {@code 'p'}
1325 * (<tt>'\u0070'</tt> and all hexadecimal digits {@code 'a'} -
1326 * {@code 'f'} (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
1327 *
1328 * </table>
1329 *
1330 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1331 * Long apply.
1332 *
1333 * <p> If the {@code '#'} flag is given, then the decimal separator will
1356 * separators, decimal separators, exponential symbol, radix indicator,
1357 * parentheses, and strings representing infinity and NaN as applicable. If
1358 * the length of the converted value is less than the width then the output
1359 * will be padded by spaces (<tt>'\u0020'</tt>) until the total number of
1360 * characters equals width. The padding is on the left by default. If the
1361 * {@code '-'} flag is given then the padding will be on the right. If width
1362 * is not specified then there is no minimum.
1363 *
1364 * <p> If the <a name="floatDPrec">conversion</a> is {@code 'e'},
1365 * {@code 'E'} or {@code 'f'}, then the precision is the number of digits
1366 * after the decimal separator. If the precision is not specified, then it is
1367 * assumed to be {@code 6}.
1368 *
1369 * <p> If the conversion is {@code 'g'} or {@code 'G'}, then the precision is
1370 * the total number of significant digits in the resulting magnitude after
1371 * rounding. If the precision is not specified, then the default value is
1372 * {@code 6}. If the precision is {@code 0}, then it is taken to be
1373 * {@code 1}.
1374 *
1375 * <p> If the conversion is {@code 'a'} or {@code 'A'}, then the precision
1376 * is the number of hexadecimal digits after the radix point. If the
1377 * precision is not provided, then all of the digits as returned by {@link
1378 * Double#toHexString(double)} will be output.
1379 *
1380 * <p><a name="dnbdec"><b> BigDecimal </b></a>
1381 *
1382 * <p> The following conversions may be applied {@link java.math.BigDecimal
1383 * BigDecimal}.
1384 *
1385 * <table cellpadding=5 summary="floatConv">
1386 *
1387 * <tr><td valign="top"> {@code 'e'}
1388 * <td valign="top"> <tt>'\u0065'</tt>
1389 * <td> Requires the output to be formatted using <a
1390 * name="bscientific">computerized scientific notation</a>. The <a
1391 * href="#L10nAlgorithm">localization algorithm</a> is applied.
1392 *
1393 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1394 *
1395 * <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1396 * will be {@code "+00"}.
|