< prev index next >

src/java.base/share/classes/java/util/Formatter.java

Print this page




 273  * <li> <b>Line Separator</b> - produces the platform-specific line separator
 274  *
 275  * </ol>
 276  *
 277  * <p> For category <i>General</i>, <i>Character</i>, <i>Numberic</i>,
 278  * <i>Integral</i> and <i>Date/Time</i> conversion, unless otherwise specified,
 279  * if the argument <i>arg</i> is {@code null}, then the result is "{@code null}".
 280  *
 281  * <p> The following table summarizes the supported conversions.  Conversions
 282  * denoted by an upper-case character (i.e. {@code 'B'}, {@code 'H'},
 283  * {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, {@code 'G'},
 284  * {@code 'A'}, and {@code 'T'}) are the same as those for the corresponding
 285  * lower-case conversion characters except that the result is converted to
 286  * upper case according to the rules of the prevailing {@link java.util.Locale
 287  * Locale}.  The result is equivalent to the following invocation of {@link
 288  * String#toUpperCase(Locale)}
 289  *
 290  * <pre>
 291  *    out.toUpperCase(Locale.getDefault(Locale.Category.FORMAT)) </pre>
 292  *
 293  * <table cellpadding=5 summary="genConv">
 294  *

 295  * <tr><th style="vertical-align:bottom"> Conversion
 296  *     <th style="vertical-align:bottom"> Argument Category
 297  *     <th style="vertical-align:bottom"> Description
 298  *

 299  * <tr><td style="vertical-align:top"> {@code 'b'}, {@code 'B'}
 300  *     <td style="vertical-align:top"> general
 301  *     <td> If the argument <i>arg</i> is {@code null}, then the result is
 302  *     "{@code false}".  If <i>arg</i> is a {@code boolean} or {@link
 303  *     Boolean}, then the result is the string returned by {@link
 304  *     String#valueOf(boolean) String.valueOf(arg)}.  Otherwise, the result is
 305  *     "true".
 306  *
 307  * <tr><td style="vertical-align:top"> {@code 'h'}, {@code 'H'}
 308  *     <td style="vertical-align:top"> general
 309  *     <td> The result is obtained by invoking
 310  *     {@code Integer.toHexString(arg.hashCode())}.
 311  *
 312  * <tr><td style="vertical-align:top"> {@code 's'}, {@code 'S'}
 313  *     <td style="vertical-align:top"> general
 314  *     <td> If <i>arg</i> implements {@link Formattable}, then
 315  *     {@link Formattable#formatTo arg.formatTo} is invoked. Otherwise, the
 316  *     result is obtained by invoking {@code arg.toString()}.
 317  *
 318  * <tr><td style="vertical-align:top">{@code 'c'}, {@code 'C'}


 348  * <tr><td style="vertical-align:top">{@code 'a'}, {@code 'A'}
 349  *     <td style="vertical-align:top"> floating point
 350  *     <td> The result is formatted as a hexadecimal floating-point number with
 351  *     a significand and an exponent. This conversion is <b>not</b> supported
 352  *     for the {@code BigDecimal} type despite the latter's being in the
 353  *     <i>floating point</i> argument category.
 354  *
 355  * <tr><td style="vertical-align:top">{@code 't'}, {@code 'T'}
 356  *     <td style="vertical-align:top"> date/time
 357  *     <td> Prefix for date and time conversion characters.  See <a
 358  *     href="#dt">Date/Time Conversions</a>.
 359  *
 360  * <tr><td style="vertical-align:top">{@code '%'}
 361  *     <td style="vertical-align:top"> percent
 362  *     <td> The result is a literal {@code '%'} (<code>'\u0025'</code>)
 363  *
 364  * <tr><td style="vertical-align:top">{@code 'n'}
 365  *     <td style="vertical-align:top"> line separator
 366  *     <td> The result is the platform-specific line separator
 367  *

 368  * </table>
 369  *
 370  * <p> Any characters not explicitly defined as conversions are illegal and are
 371  * reserved for future extensions.
 372  *
 373  * <h4><a id="dt">Date/Time Conversions</a></h4>
 374  *
 375  * <p> The following date and time conversion suffix characters are defined for
 376  * the {@code 't'} and {@code 'T'} conversions.  The types are similar to but
 377  * not completely identical to those defined by GNU {@code date} and POSIX
 378  * {@code strftime(3c)}.  Additional conversion types are provided to access
 379  * Java-specific functionality (e.g. {@code 'L'} for milliseconds within the
 380  * second).
 381  *
 382  * <p> The following conversion characters are used for formatting times:
 383  *
 384  * <table cellpadding=5 summary="time">
 385  *

 386  * <tr><td style="vertical-align:top"> {@code 'H'}
 387  *     <td> Hour of the day for the 24-hour clock, formatted as two digits with
 388  *     a leading zero as necessary i.e. {@code 00 - 23}.
 389  *
 390  * <tr><td style="vertical-align:top">{@code 'I'}
 391  *     <td> Hour for the 12-hour clock, formatted as two digits with a leading
 392  *     zero as necessary, i.e.  {@code 01 - 12}.
 393  *
 394  * <tr><td style="vertical-align:top">{@code 'k'}
 395  *     <td> Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}.
 396  *
 397  * <tr><td style="vertical-align:top">{@code 'l'}
 398  *     <td> Hour for the 12-hour clock, i.e. {@code 1 - 12}.
 399  *
 400  * <tr><td style="vertical-align:top">{@code 'M'}
 401  *     <td> Minute within the hour formatted as two digits with a leading zero
 402  *     as necessary, i.e.  {@code 00 - 59}.
 403  *
 404  * <tr><td style="vertical-align:top">{@code 'S'}
 405  *     <td> Seconds within the minute, formatted as two digits with a leading


 429  *     instance of the Java virtual machine.
 430  *
 431  * <tr><td style="vertical-align:top">{@code 'Z'}
 432  *     <td> A string representing the abbreviation for the time zone.  This
 433  *     value will be adjusted as necessary for Daylight Saving Time.  For
 434  *     {@code long}, {@link Long}, and {@link Date} the  time zone used is
 435  *     the {@linkplain TimeZone#getDefault() default time zone} for this
 436  *     instance of the Java virtual machine.  The Formatter's locale will
 437  *     supersede the locale of the argument (if any).
 438  *
 439  * <tr><td style="vertical-align:top">{@code 's'}
 440  *     <td> Seconds since the beginning of the epoch starting at 1 January 1970
 441  *     {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to
 442  *     {@code Long.MAX_VALUE/1000}.
 443  *
 444  * <tr><td style="vertical-align:top">{@code 'Q'}
 445  *     <td> Milliseconds since the beginning of the epoch starting at 1 January
 446  *     1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to
 447  *     {@code Long.MAX_VALUE}.
 448  *

 449  * </table>
 450  *
 451  * <p> The following conversion characters are used for formatting dates:
 452  *
 453  * <table cellpadding=5 summary="date">


 454  *
 455  * <tr><td style="vertical-align:top">{@code 'B'}
 456  *     <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
 457  *     full month name}, e.g. {@code "January"}, {@code "February"}.
 458  *
 459  * <tr><td style="vertical-align:top">{@code 'b'}
 460  *     <td> Locale-specific {@linkplain
 461  *     java.text.DateFormatSymbols#getShortMonths abbreviated month name},
 462  *     e.g. {@code "Jan"}, {@code "Feb"}.
 463  *
 464  * <tr><td style="vertical-align:top">{@code 'h'}
 465  *     <td> Same as {@code 'b'}.
 466  *
 467  * <tr><td style="vertical-align:top">{@code 'A'}
 468  *     <td> Locale-specific full name of the {@linkplain
 469  *     java.text.DateFormatSymbols#getWeekdays day of the week},
 470  *     e.g. {@code "Sunday"}, {@code "Monday"}
 471  *
 472  * <tr><td style="vertical-align:top">{@code 'a'}
 473  *     <td> Locale-specific short name of the {@linkplain


 485  *
 486  * <tr><td style="vertical-align:top">{@code 'y'}
 487  *     <td> Last two digits of the year, formatted with leading zeros as
 488  *     necessary, i.e. {@code 00 - 99}.
 489  *
 490  * <tr><td style="vertical-align:top">{@code 'j'}
 491  *     <td> Day of year, formatted as three digits with leading zeros as
 492  *     necessary, e.g. {@code 001 - 366} for the Gregorian calendar.
 493  *
 494  * <tr><td style="vertical-align:top">{@code 'm'}
 495  *     <td> Month, formatted as two digits with leading zeros as necessary,
 496  *     i.e. {@code 01 - 13}.
 497  *
 498  * <tr><td style="vertical-align:top">{@code 'd'}
 499  *     <td> Day of month, formatted as two digits with leading zeros as
 500  *     necessary, i.e. {@code 01 - 31}
 501  *
 502  * <tr><td style="vertical-align:top">{@code 'e'}
 503  *     <td> Day of month, formatted as two digits, i.e. {@code 1 - 31}.
 504  *

 505  * </table>
 506  *
 507  * <p> The following conversion characters are used for formatting common
 508  * date/time compositions.
 509  *
 510  * <table cellpadding=5 summary="composites">


 511  *
 512  * <tr><td style="vertical-align:top">{@code 'R'}
 513  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM"}
 514  *
 515  * <tr><td style="vertical-align:top">{@code 'T'}
 516  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}.
 517  *
 518  * <tr><td style="vertical-align:top">{@code 'r'}
 519  *     <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS %Tp"}.
 520  *     The location of the morning or afternoon marker ({@code '%Tp'}) may be
 521  *     locale-dependent.
 522  *
 523  * <tr><td style="vertical-align:top">{@code 'D'}
 524  *     <td> Date formatted as {@code "%tm/%td/%ty"}.
 525  *
 526  * <tr><td style="vertical-align:top">{@code 'F'}
 527  *     <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO&nbsp;8601</a>
 528  *     complete date formatted as {@code "%tY-%tm-%td"}.
 529  *
 530  * <tr><td style="vertical-align:top">{@code 'c'}
 531  *     <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
 532  *     e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
 533  *

 534  * </table>
 535  *
 536  * <p> Any characters not explicitly defined as date/time conversion suffixes
 537  * are illegal and are reserved for future extensions.
 538  *
 539  * <h4> Flags </h4>
 540  *
 541  * <p> The following table summarizes the supported flags.  <i>y</i> means the
 542  * flag is supported for the indicated argument types.
 543  *
 544  * <table cellpadding=5 summary="genConv">
 545  *

 546  * <tr><th style="vertical-align:bottom"> Flag <th style="vertical-align:bottom"> General
 547  *     <th style="vertical-align:bottom"> Character <th style="vertical-align:bottom"> Integral
 548  *     <th style="vertical-align:bottom"> Floating Point
 549  *     <th style="vertical-align:bottom"> Date/Time
 550  *     <th style="vertical-align:bottom"> Description
 551  *

 552  * <tr><td> '-' <td style="text-align:center; vertical-align:top"> y
 553  *     <td style="text-align:center; vertical-align:top"> y
 554  *     <td style="text-align:center; vertical-align:top"> y
 555  *     <td style="text-align:center; vertical-align:top"> y
 556  *     <td style="text-align:center; vertical-align:top"> y
 557  *     <td> The result will be left-justified.
 558  *
 559  * <tr><td> '#' <td style="text-align:center; vertical-align:top"> y<sup>1</sup>
 560  *     <td style="text-align:center; vertical-align:top"> -
 561  *     <td style="text-align:center; vertical-align:top"> y<sup>3</sup>
 562  *     <td style="text-align:center; vertical-align:top"> y
 563  *     <td style="text-align:center; vertical-align:top"> -
 564  *     <td> The result should use a conversion-dependent alternate form
 565  *
 566  * <tr><td> '+' <td style="text-align:center; vertical-align:top"> -
 567  *     <td style="text-align:center; vertical-align:top"> -
 568  *     <td style="text-align:center; vertical-align:top"> y<sup>4</sup>
 569  *     <td style="text-align:center; vertical-align:top"> y
 570  *     <td style="text-align:center; vertical-align:top"> -
 571  *     <td> The result will always include a sign


 582  *     <td style="text-align:center; vertical-align:top"> y
 583  *     <td style="text-align:center; vertical-align:top"> y
 584  *     <td style="text-align:center; vertical-align:top"> -
 585  *     <td> The result will be zero-padded
 586  *
 587  * <tr><td> ',' <td style="text-align:center; vertical-align:top"> -
 588  *     <td style="text-align:center; vertical-align:top"> -
 589  *     <td style="text-align:center; vertical-align:top"> y<sup>2</sup>
 590  *     <td style="text-align:center; vertical-align:top"> y<sup>5</sup>
 591  *     <td style="text-align:center; vertical-align:top"> -
 592  *     <td> The result will include locale-specific {@linkplain
 593  *     java.text.DecimalFormatSymbols#getGroupingSeparator grouping separators}
 594  *
 595  * <tr><td> '(' <td style="text-align:center; vertical-align:top"> -
 596  *     <td style="text-align:center; vertical-align:top"> -
 597  *     <td style="text-align:center; vertical-align:top"> y<sup>4</sup>
 598  *     <td style="text-align:center; vertical-align:top"> y<sup>5</sup>
 599  *     <td style="text-align:center"> -
 600  *     <td> The result will enclose negative numbers in parentheses
 601  *

 602  * </table>
 603  *
 604  * <p> <sup>1</sup> Depends on the definition of {@link Formattable}.
 605  *
 606  * <p> <sup>2</sup> For {@code 'd'} conversion only.
 607  *
 608  * <p> <sup>3</sup> For {@code 'o'}, {@code 'x'}, and {@code 'X'}
 609  * conversions only.
 610  *
 611  * <p> <sup>4</sup> For {@code 'd'}, {@code 'o'}, {@code 'x'}, and
 612  * {@code 'X'} conversions applied to {@link java.math.BigInteger BigInteger}
 613  * or {@code 'd'} applied to {@code byte}, {@link Byte}, {@code short}, {@link
 614  * Short}, {@code int} and {@link Integer}, {@code long}, and {@link Long}.
 615  *
 616  * <p> <sup>5</sup> For {@code 'e'}, {@code 'E'}, {@code 'f'},
 617  * {@code 'g'}, and {@code 'G'} conversions only.
 618  *
 619  * <p> Any characters not explicitly defined as flags are illegal and are
 620  * reserved for future extensions.
 621  *


 688  *
 689  * <p> For category <i>General</i>, <i>Character</i>, <i>Numberic</i>,
 690  * <i>Integral</i> and <i>Date/Time</i> conversion, unless otherwise specified,
 691  * if the argument <i>arg</i> is {@code null}, then the result is "{@code null}".
 692  *
 693  * <p> Conversions denoted by an upper-case character (i.e. {@code 'B'},
 694  * {@code 'H'}, {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'},
 695  * {@code 'G'}, {@code 'A'}, and {@code 'T'}) are the same as those for the
 696  * corresponding lower-case conversion characters except that the result is
 697  * converted to upper case according to the rules of the prevailing {@link
 698  * java.util.Locale Locale}.  The result is equivalent to the following
 699  * invocation of {@link String#toUpperCase(Locale)}
 700  *
 701  * <pre>
 702  *    out.toUpperCase(Locale.getDefault(Locale.Category.FORMAT)) </pre>
 703  *
 704  * <h4><a id="dgen">General</a></h4>
 705  *
 706  * <p> The following general conversions may be applied to any argument type:
 707  *
 708  * <table cellpadding=5 summary="dgConv">


 709  *
 710  * <tr><td style="vertical-align:top"> {@code 'b'}
 711  *     <td style="vertical-align:top"> <code>'\u0062'</code>
 712  *     <td> Produces either "{@code true}" or "{@code false}" as returned by
 713  *     {@link Boolean#toString(boolean)}.
 714  *
 715  *     <p> If the argument is {@code null}, then the result is
 716  *     "{@code false}".  If the argument is a {@code boolean} or {@link
 717  *     Boolean}, then the result is the string returned by {@link
 718  *     String#valueOf(boolean) String.valueOf()}.  Otherwise, the result is
 719  *     "{@code true}".
 720  *
 721  *     <p> If the {@code '#'} flag is given, then a {@link
 722  *     FormatFlagsConversionMismatchException} will be thrown.
 723  *
 724  * <tr><td style="vertical-align:top"> {@code 'B'}
 725  *     <td style="vertical-align:top"> <code>'\u0042'</code>
 726  *     <td> The upper-case variant of {@code 'b'}.
 727  *
 728  * <tr><td style="vertical-align:top"> {@code 'h'}


 739  *     <td style="vertical-align:top"> <code>'\u0048'</code>
 740  *     <td> The upper-case variant of {@code 'h'}.
 741  *
 742  * <tr><td style="vertical-align:top"> {@code 's'}
 743  *     <td style="vertical-align:top"> <code>'\u0073'</code>
 744  *     <td> Produces a string.
 745  *
 746  *     <p> If the argument implements {@link Formattable}, then
 747  *     its {@link Formattable#formatTo formatTo} method is invoked.
 748  *     Otherwise, the result is obtained by invoking the argument's
 749  *     {@code toString()} method.
 750  *
 751  *     <p> If the {@code '#'} flag is given and the argument is not a {@link
 752  *     Formattable} , then a {@link FormatFlagsConversionMismatchException}
 753  *     will be thrown.
 754  *
 755  * <tr><td style="vertical-align:top"> {@code 'S'}
 756  *     <td style="vertical-align:top"> <code>'\u0053'</code>
 757  *     <td> The upper-case variant of {@code 's'}.
 758  *

 759  * </table>
 760  *
 761  * <p> The following <a id="dFlags">flags</a> apply to general conversions:
 762  *
 763  * <table cellpadding=5 summary="dFlags">


 764  *
 765  * <tr><td style="vertical-align:top"> {@code '-'}
 766  *     <td style="vertical-align:top"> <code>'\u002d'</code>
 767  *     <td> Left justifies the output.  Spaces (<code>'\u0020'</code>) will be
 768  *     added at the end of the converted value as required to fill the minimum
 769  *     width of the field.  If the width is not provided, then a {@link
 770  *     MissingFormatWidthException} will be thrown.  If this flag is not given
 771  *     then the output will be right-justified.
 772  *
 773  * <tr><td style="vertical-align:top"> {@code '#'}
 774  *     <td style="vertical-align:top"> <code>'\u0023'</code>
 775  *     <td> Requires the output use an alternate form.  The definition of the
 776  *     form is specified by the conversion.
 777  *

 778  * </table>
 779  *
 780  * <p> The <a id="genWidth">width</a> is the minimum number of characters to
 781  * be written to the
 782  * output.  If the length of the converted value is less than the width then
 783  * the output will be padded by <code>'&nbsp;&nbsp;'</code> (<code>'\u0020'</code>)
 784  * until the total number of characters equals the width.  The padding is on
 785  * the left by default.  If the {@code '-'} flag is given, then the padding
 786  * will be on the right.  If the width is not specified then there is no
 787  * minimum.
 788  *
 789  * <p> The precision is the maximum number of characters to be written to the
 790  * output.  The precision is applied before the width, thus the output will be
 791  * truncated to {@code precision} characters even if the width is greater than
 792  * the precision.  If the precision is not specified then there is no explicit
 793  * limit on the number of characters.
 794  *
 795  * <h4><a id="dchar">Character</a></h4>
 796  *
 797  * This conversion may be applied to {@code char} and {@link Character}.  It
 798  * may also be applied to the types {@code byte}, {@link Byte},
 799  * {@code short}, and {@link Short}, {@code int} and {@link Integer} when
 800  * {@link Character#isValidCodePoint} returns {@code true}.  If it returns
 801  * {@code false} then an {@link IllegalFormatCodePointException} will be
 802  * thrown.
 803  *
 804  * <table cellpadding=5 summary="charConv">


 805  *
 806  * <tr><td style="vertical-align:top"> {@code 'c'}
 807  *     <td style="vertical-align:top"> <code>'\u0063'</code>
 808  *     <td> Formats the argument as a Unicode character as described in <a
 809  *     href="../lang/Character.html#unicode">Unicode Character
 810  *     Representation</a>.  This may be more than one 16-bit {@code char} in
 811  *     the case where the argument represents a supplementary character.
 812  *
 813  *     <p> If the {@code '#'} flag is given, then a {@link
 814  *     FormatFlagsConversionMismatchException} will be thrown.
 815  *
 816  * <tr><td style="vertical-align:top"> {@code 'C'}
 817  *     <td style="vertical-align:top"> <code>'\u0043'</code>
 818  *     <td> The upper-case variant of {@code 'c'}.
 819  *

 820  * </table>
 821  *
 822  * <p> The {@code '-'} flag defined for <a href="#dFlags">General
 823  * conversions</a> applies.  If the {@code '#'} flag is given, then a {@link
 824  * FormatFlagsConversionMismatchException} will be thrown.
 825  *
 826  * <p> The width is defined as for <a href="#genWidth">General conversions</a>.
 827  *
 828  * <p> The precision is not applicable.  If the precision is specified then an
 829  * {@link IllegalFormatPrecisionException} will be thrown.
 830  *
 831  * <h4><a id="dnum">Numeric</a></h4>
 832  *
 833  * <p> Numeric conversions are divided into the following categories:
 834  *
 835  * <ol>
 836  *
 837  * <li> <a href="#dnint"><b>Byte, Short, Integer, and Long</b></a>
 838  *
 839  * <li> <a href="#dnbint"><b>BigInteger</b></a>


 885  * {@code '('} flag is not given, then a {@code '-'} (<code>'\u002d'</code>)
 886  * is prepended.
 887  *
 888  * <li> If the {@code '+'} flag is given and the value is positive or zero (or
 889  * floating-point positive zero), then a {@code '+'} (<code>'\u002b'</code>)
 890  * will be prepended.
 891  *
 892  * </ol>
 893  *
 894  * <p> If the value is NaN or positive infinity the literal strings "NaN" or
 895  * "Infinity" respectively, will be output.  If the value is negative infinity,
 896  * then the output will be "(Infinity)" if the {@code '('} flag is given
 897  * otherwise the output will be "-Infinity".  These values are not localized.
 898  *
 899  * <p><a id="dnint"><b> Byte, Short, Integer, and Long </b></a>
 900  *
 901  * <p> The following conversions may be applied to {@code byte}, {@link Byte},
 902  * {@code short}, {@link Short}, {@code int} and {@link Integer},
 903  * {@code long}, and {@link Long}.
 904  *
 905  * <table cellpadding=5 summary="IntConv">


 906  *
 907  * <tr><td style="vertical-align:top"> {@code 'd'}
 908  *     <td style="vertical-align:top"> <code>'\u0064'</code>
 909  *     <td> Formats the argument as a decimal integer. The <a
 910  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
 911  *
 912  *     <p> If the {@code '0'} flag is given and the value is negative, then
 913  *     the zero padding will occur after the sign.
 914  *
 915  *     <p> If the {@code '#'} flag is given then a {@link
 916  *     FormatFlagsConversionMismatchException} will be thrown.
 917  *
 918  * <tr><td style="vertical-align:top"> {@code 'o'}
 919  *     <td style="vertical-align:top"> <code>'\u006f'</code>
 920  *     <td> Formats the argument as an integer in base eight.  No localization
 921  *     is applied.
 922  *
 923  *     <p> If <i>x</i> is negative then the result will be an unsigned value
 924  *     generated by adding 2<sup>n</sup> to the value where {@code n} is the
 925  *     number of bits in the type as returned by the static {@code SIZE} field


 951  *
 952  *     <p> If the {@code '#'} flag is given then the output will always begin
 953  *     with the radix indicator {@code "0x"}.
 954  *
 955  *     <p> If the {@code '0'} flag is given then the output will be padded to
 956  *     the field width with leading zeros after the radix indicator or sign (if
 957  *     present).
 958  *
 959  *     <p> If {@code '('}, <code>'&nbsp;&nbsp;'</code>, {@code '+'}, or
 960  *     {@code ','} flags are given then a {@link
 961  *     FormatFlagsConversionMismatchException} will be thrown.
 962  *
 963  * <tr><td style="vertical-align:top"> {@code 'X'}
 964  *     <td style="vertical-align:top"> <code>'\u0058'</code>
 965  *     <td> The upper-case variant of {@code 'x'}.  The entire string
 966  *     representing the number will be converted to {@linkplain
 967  *     String#toUpperCase upper case} including the {@code 'x'} (if any) and
 968  *     all hexadecimal digits {@code 'a'} - {@code 'f'}
 969  *     (<code>'\u0061'</code> -  <code>'\u0066'</code>).
 970  *

 971  * </table>
 972  *
 973  * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and
 974  * both the {@code '#'} and the {@code '0'} flags are given, then result will
 975  * contain the radix indicator ({@code '0'} for octal and {@code "0x"} or
 976  * {@code "0X"} for hexadecimal), some number of zeros (based on the width),
 977  * and the value.
 978  *
 979  * <p> If the {@code '-'} flag is not given, then the space padding will occur
 980  * before the sign.
 981  *
 982  * <p> The following <a id="intFlags">flags</a> apply to numeric integral
 983  * conversions:
 984  *
 985  * <table cellpadding=5 summary="intFlags">


 986  *
 987  * <tr><td style="vertical-align:top"> {@code '+'}
 988  *     <td style="vertical-align:top"> <code>'\u002b'</code>
 989  *     <td> Requires the output to include a positive sign for all positive
 990  *     numbers.  If this flag is not given then only negative values will
 991  *     include a sign.
 992  *
 993  *     <p> If both the {@code '+'} and <code>'&nbsp;&nbsp;'</code> flags are given
 994  *     then an {@link IllegalFormatFlagsException} will be thrown.
 995  *
 996  * <tr><td style="vertical-align:top"> <code>'&nbsp;&nbsp;'</code>
 997  *     <td style="vertical-align:top"> <code>'\u0020'</code>
 998  *     <td> Requires the output to include a single extra space
 999  *     (<code>'\u0020'</code>) for non-negative values.
1000  *
1001  *     <p> If both the {@code '+'} and <code>'&nbsp;&nbsp;'</code> flags are given
1002  *     then an {@link IllegalFormatFlagsException} will be thrown.
1003  *
1004  * <tr><td style="vertical-align:top"> {@code '0'}
1005  *     <td style="vertical-align:top"> <code>'\u0030'</code>


1008  *     width following any sign or radix indicator except when converting NaN
1009  *     or infinity.  If the width is not provided, then a {@link
1010  *     MissingFormatWidthException} will be thrown.
1011  *
1012  *     <p> If both the {@code '-'} and {@code '0'} flags are given then an
1013  *     {@link IllegalFormatFlagsException} will be thrown.
1014  *
1015  * <tr><td style="vertical-align:top"> {@code ','}
1016  *     <td style="vertical-align:top"> <code>'\u002c'</code>
1017  *     <td> Requires the output to include the locale-specific {@linkplain
1018  *     java.text.DecimalFormatSymbols#getGroupingSeparator group separators} as
1019  *     described in the <a href="#L10nGroup">"group" section</a> of the
1020  *     localization algorithm.
1021  *
1022  * <tr><td style="vertical-align:top"> {@code '('}
1023  *     <td style="vertical-align:top"> <code>'\u0028'</code>
1024  *     <td> Requires the output to prepend a {@code '('}
1025  *     (<code>'\u0028'</code>) and append a {@code ')'}
1026  *     (<code>'\u0029'</code>) to negative values.
1027  *

1028  * </table>
1029  *
1030  * <p> If no <a id="intdFlags">flags</a> are given the default formatting is
1031  * as follows:
1032  *
1033  * <ul>
1034  *
1035  * <li> The output is right-justified within the {@code width}
1036  *
1037  * <li> Negative numbers begin with a {@code '-'} (<code>'\u002d'</code>)
1038  *
1039  * <li> Positive numbers and zero do not include a sign or extra leading
1040  * space
1041  *
1042  * <li> No grouping separators are included
1043  *
1044  * </ul>
1045  *
1046  * <p> The <a id="intWidth">width</a> is the minimum number of characters to
1047  * be written to the output.  This includes any signs, digits, grouping
1048  * separators, radix indicator, and parentheses.  If the length of the
1049  * converted value is less than the width then the output will be padded by
1050  * spaces (<code>'\u0020'</code>) until the total number of characters equals
1051  * width.  The padding is on the left by default.  If {@code '-'} flag is
1052  * given then the padding will be on the right.  If width is not specified then
1053  * there is no minimum.
1054  *
1055  * <p> The precision is not applicable.  If precision is specified then an
1056  * {@link IllegalFormatPrecisionException} will be thrown.
1057  *
1058  * <p><a id="dnbint"><b> BigInteger </b></a>
1059  *
1060  * <p> The following conversions may be applied to {@link
1061  * java.math.BigInteger}.
1062  *
1063  * <table cellpadding=5 summary="BIntConv">


1064  *
1065  * <tr><td style="vertical-align:top"> {@code 'd'}
1066  *     <td style="vertical-align:top"> <code>'\u0064'</code>
1067  *     <td> Requires the output to be formatted as a decimal integer. The <a
1068  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
1069  *
1070  *     <p> If the {@code '#'} flag is given {@link
1071  *     FormatFlagsConversionMismatchException} will be thrown.
1072  *
1073  * <tr><td style="vertical-align:top"> {@code 'o'}
1074  *     <td style="vertical-align:top"> <code>'\u006f'</code>
1075  *     <td> Requires the output to be formatted as an integer in base eight.
1076  *     No localization is applied.
1077  *
1078  *     <p> If <i>x</i> is negative then the result will be a signed value
1079  *     beginning with {@code '-'} (<code>'\u002d'</code>).  Signed output is
1080  *     allowed for this type because unlike the primitive types it is not
1081  *     possible to create an unsigned equivalent without assuming an explicit
1082  *     data-type size.
1083  *


1108  *     then the result will begin with {@code '+'} (<code>'\u002b'</code>).
1109  *
1110  *     <p> If the {@code '#'} flag is given then the output will always begin
1111  *     with the radix indicator {@code "0x"}.
1112  *
1113  *     <p> If the {@code '0'} flag is given then the output will be padded to
1114  *     the field width with leading zeros after the radix indicator or sign (if
1115  *     present).
1116  *
1117  *     <p> If the {@code ','} flag is given then a {@link
1118  *     FormatFlagsConversionMismatchException} will be thrown.
1119  *
1120  * <tr><td style="vertical-align:top"> {@code 'X'}
1121  *     <td style="vertical-align:top"> <code>'\u0058'</code>
1122  *     <td> The upper-case variant of {@code 'x'}.  The entire string
1123  *     representing the number will be converted to {@linkplain
1124  *     String#toUpperCase upper case} including the {@code 'x'} (if any) and
1125  *     all hexadecimal digits {@code 'a'} - {@code 'f'}
1126  *     (<code>'\u0061'</code> - <code>'\u0066'</code>).
1127  *

1128  * </table>
1129  *
1130  * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and
1131  * both the {@code '#'} and the {@code '0'} flags are given, then result will
1132  * contain the base indicator ({@code '0'} for octal and {@code "0x"} or
1133  * {@code "0X"} for hexadecimal), some number of zeros (based on the width),
1134  * and the value.
1135  *
1136  * <p> If the {@code '0'} flag is given and the value is negative, then the
1137  * zero padding will occur after the sign.
1138  *
1139  * <p> If the {@code '-'} flag is not given, then the space padding will occur
1140  * before the sign.
1141  *
1142  * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1143  * Long apply.  The <a href="#intdFlags">default behavior</a> when no flags are
1144  * given is the same as for Byte, Short, Integer, and Long.
1145  *
1146  * <p> The specification of <a href="#intWidth">width</a> is the same as
1147  * defined for Byte, Short, Integer, and Long.
1148  *
1149  * <p> The precision is not applicable.  If precision is specified then an
1150  * {@link IllegalFormatPrecisionException} will be thrown.
1151  *
1152  * <p><a id="dndec"><b> Float and Double</b></a>
1153  *
1154  * <p> The following conversions may be applied to {@code float}, {@link
1155  * Float}, {@code double} and {@link Double}.
1156  *
1157  * <table cellpadding=5 summary="floatConv">


1158  *
1159  * <tr><td style="vertical-align:top"> {@code 'e'}
1160  *     <td style="vertical-align:top"> <code>'\u0065'</code>
1161  *     <td> Requires the output to be formatted using <a
1162  *     id="scientific">computerized scientific notation</a>.  The <a
1163  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
1164  *
1165  *     <p> The formatting of the magnitude <i>m</i> depends upon its value.
1166  *
1167  *     <p> If <i>m</i> is NaN or infinite, the literal strings "NaN" or
1168  *     "Infinity", respectively, will be output.  These values are not
1169  *     localized.
1170  *
1171  *     <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1172  *     will be {@code "+00"}.
1173  *
1174  *     <p> Otherwise, the result is a string that represents the sign and
1175  *     magnitude (absolute value) of the argument.  The formatting of the sign
1176  *     is described in the <a href="#L10nAlgorithm">localization
1177  *     algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its


1314  *     {@code 'p-1022'}.  If the precision is in the interval
1315  *     [1,&nbsp;12], the subnormal value is normalized such that it
1316  *     begins with the characters {@code '0x1.'}, rounded to the number of
1317  *     hexadecimal digits of precision, and the exponent adjusted
1318  *     accordingly.  Note that there must be at least one nonzero digit in a
1319  *     subnormal significand.
1320  *
1321  *     </ul>
1322  *
1323  *     <p> If the {@code '('} or {@code ','} flags are given, then a {@link
1324  *     FormatFlagsConversionMismatchException} will be thrown.
1325  *
1326  * <tr><td style="vertical-align:top"> {@code 'A'}
1327  *     <td style="vertical-align:top"> <code>'\u0041'</code>
1328  *     <td> The upper-case variant of {@code 'a'}.  The entire string
1329  *     representing the number will be converted to upper case including the
1330  *     {@code 'x'} (<code>'\u0078'</code>) and {@code 'p'}
1331  *     (<code>'\u0070'</code> and all hexadecimal digits {@code 'a'} -
1332  *     {@code 'f'} (<code>'\u0061'</code> - <code>'\u0066'</code>).
1333  *

1334  * </table>
1335  *
1336  * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1337  * Long apply.
1338  *
1339  * <p> If the {@code '#'} flag is given, then the decimal separator will
1340  * always be present.
1341  *
1342  * <p> If no <a id="floatdFlags">flags</a> are given the default formatting
1343  * is as follows:
1344  *
1345  * <ul>
1346  *
1347  * <li> The output is right-justified within the {@code width}
1348  *
1349  * <li> Negative numbers begin with a {@code '-'}
1350  *
1351  * <li> Positive numbers and positive zero do not include a sign or extra
1352  * leading space
1353  *


1371  * {@code 'E'} or {@code 'f'}, then the precision is the number of digits
1372  * after the decimal separator.  If the precision is not specified, then it is
1373  * assumed to be {@code 6}.
1374  *
1375  * <p> If the conversion is {@code 'g'} or {@code 'G'}, then the precision is
1376  * the total number of significant digits in the resulting magnitude after
1377  * rounding.  If the precision is not specified, then the default value is
1378  * {@code 6}.  If the precision is {@code 0}, then it is taken to be
1379  * {@code 1}.
1380  *
1381  * <p> If the conversion is {@code 'a'} or {@code 'A'}, then the precision
1382  * is the number of hexadecimal digits after the radix point.  If the
1383  * precision is not provided, then all of the digits as returned by {@link
1384  * Double#toHexString(double)} will be output.
1385  *
1386  * <p><a id="dnbdec"><b> BigDecimal </b></a>
1387  *
1388  * <p> The following conversions may be applied {@link java.math.BigDecimal
1389  * BigDecimal}.
1390  *
1391  * <table cellpadding=5 summary="floatConv">


1392  *
1393  * <tr><td style="vertical-align:top"> {@code 'e'}
1394  *     <td style="vertical-align:top"> <code>'\u0065'</code>
1395  *     <td> Requires the output to be formatted using <a
1396  *     id="bscientific">computerized scientific notation</a>.  The <a
1397  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
1398  *
1399  *     <p> The formatting of the magnitude <i>m</i> depends upon its value.
1400  *
1401  *     <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1402  *     will be {@code "+00"}.
1403  *
1404  *     <p> Otherwise, the result is a string that represents the sign and
1405  *     magnitude (absolute value) of the argument.  The formatting of the sign
1406  *     is described in the <a href="#L10nAlgorithm">localization
1407  *     algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1408  *     value.
1409  *
1410  *     <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
1411  *     &lt;= <i>m</i> &lt; 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the


1475  *     <p> The result is a string that represents the sign and magnitude
1476  *     (absolute value) of the argument.  The formatting of the sign is
1477  *     described in the <a href="#L10nAlgorithm">localization
1478  *     algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1479  *     value.
1480  *
1481  *     <p> The magnitude is formatted as the integer part of <i>m</i>, with no
1482  *     leading zeroes, followed by the decimal separator followed by one or
1483  *     more decimal digits representing the fractional part of <i>m</i>.
1484  *
1485  *     <p> The number of digits in the result for the fractional part of
1486  *     <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1487  *     specified then the default value is {@code 6}.  If the precision is
1488  *     less than the number of digits to the right of the decimal point
1489  *     then the value will be rounded using the
1490  *     {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1491  *     algorithm}.  Otherwise, zeros may be appended to reach the precision.
1492  *     For a canonical representation of the value, use {@link
1493  *     BigDecimal#toString()}.
1494  *

1495  * </table>
1496  *
1497  * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1498  * Long apply.
1499  *
1500  * <p> If the {@code '#'} flag is given, then the decimal separator will
1501  * always be present.
1502  *
1503  * <p> The <a href="#floatdFlags">default behavior</a> when no flags are
1504  * given is the same as for Float and Double.
1505  *
1506  * <p> The specification of <a href="#floatDWidth">width</a> and <a
1507  * href="#floatDPrec">precision</a> is the same as defined for Float and
1508  * Double.
1509  *
1510  * <h4><a id="ddt">Date/Time</a></h4>
1511  *
1512  * <p> This conversion may be applied to {@code long}, {@link Long}, {@link
1513  * Calendar}, {@link Date} and {@link TemporalAccessor TemporalAccessor}
1514  *
1515  * <table cellpadding=5 summary="DTConv">


1516  *
1517  * <tr><td style="vertical-align:top"> {@code 't'}
1518  *     <td style="vertical-align:top"> <code>'\u0074'</code>
1519  *     <td> Prefix for date and time conversion characters.
1520  * <tr><td style="vertical-align:top"> {@code 'T'}
1521  *     <td style="vertical-align:top"> <code>'\u0054'</code>
1522  *     <td> The upper-case variant of {@code 't'}.
1523  *

1524  * </table>
1525  *
1526  * <p> The following date and time conversion character suffixes are defined
1527  * for the {@code 't'} and {@code 'T'} conversions.  The types are similar to
1528  * but not completely identical to those defined by GNU {@code date} and
1529  * POSIX {@code strftime(3c)}.  Additional conversion types are provided to
1530  * access Java-specific functionality (e.g. {@code 'L'} for milliseconds
1531  * within the second).
1532  *
1533  * <p> The following conversion characters are used for formatting times:
1534  *
1535  * <table cellpadding=5 summary="time">


1536  *
1537  * <tr><td style="vertical-align:top"> {@code 'H'}
1538  *     <td style="vertical-align:top"> <code>'\u0048'</code>
1539  *     <td> Hour of the day for the 24-hour clock, formatted as two digits with
1540  *     a leading zero as necessary i.e. {@code 00 - 23}. {@code 00}
1541  *     corresponds to midnight.
1542  *
1543  * <tr><td style="vertical-align:top">{@code 'I'}
1544  *     <td style="vertical-align:top"> <code>'\u0049'</code>
1545  *     <td> Hour for the 12-hour clock, formatted as two digits with a leading
1546  *     zero as necessary, i.e.  {@code 01 - 12}.  {@code 01} corresponds to
1547  *     one o'clock (either morning or afternoon).
1548  *
1549  * <tr><td style="vertical-align:top">{@code 'k'}
1550  *     <td style="vertical-align:top"> <code>'\u006b'</code>
1551  *     <td> Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}.
1552  *     {@code 0} corresponds to midnight.
1553  *
1554  * <tr><td style="vertical-align:top">{@code 'l'}
1555  *     <td style="vertical-align:top"> <code>'\u006c'</code>


1603  *     <td> A string representing the abbreviation for the time zone.  This
1604  *     value will be adjusted as necessary for Daylight Saving Time.  For
1605  *     {@code long}, {@link Long}, and {@link Date} the time zone used is
1606  *     the {@linkplain TimeZone#getDefault() default time zone} for this
1607  *     instance of the Java virtual machine.  The Formatter's locale will
1608  *     supersede the locale of the argument (if any).
1609  *
1610  * <tr><td style="vertical-align:top">{@code 's'}
1611  *     <td style="vertical-align:top"> <code>'\u0073'</code>
1612  *     <td> Seconds since the beginning of the epoch starting at 1 January 1970
1613  *     {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to
1614  *     {@code Long.MAX_VALUE/1000}.
1615  *
1616  * <tr><td style="vertical-align:top">{@code 'Q'}
1617  *     <td style="vertical-align:top"> <code>'\u004f'</code>
1618  *     <td> Milliseconds since the beginning of the epoch starting at 1 January
1619  *     1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to
1620  *     {@code Long.MAX_VALUE}. The precision of this value is limited by
1621  *     the resolution of the underlying operating system or hardware.
1622  *

1623  * </table>
1624  *
1625  * <p> The following conversion characters are used for formatting dates:
1626  *
1627  * <table cellpadding=5 summary="date">


1628  *
1629  * <tr><td style="vertical-align:top">{@code 'B'}
1630  *     <td style="vertical-align:top"> <code>'\u0042'</code>
1631  *     <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
1632  *     full month name}, e.g. {@code "January"}, {@code "February"}.
1633  *
1634  * <tr><td style="vertical-align:top">{@code 'b'}
1635  *     <td style="vertical-align:top"> <code>'\u0062'</code>
1636  *     <td> Locale-specific {@linkplain
1637  *     java.text.DateFormatSymbols#getShortMonths abbreviated month name},
1638  *     e.g. {@code "Jan"}, {@code "Feb"}.
1639  *
1640  * <tr><td style="vertical-align:top">{@code 'h'}
1641  *     <td style="vertical-align:top"> <code>'\u0068'</code>
1642  *     <td> Same as {@code 'b'}.
1643  *
1644  * <tr><td style="vertical-align:top">{@code 'A'}
1645  *     <td style="vertical-align:top"> <code>'\u0041'</code>
1646  *     <td> Locale-specific full name of the {@linkplain
1647  *     java.text.DateFormatSymbols#getWeekdays day of the week},


1675  *     {@code 001} corresponds to the first day of the year.
1676  *
1677  * <tr><td style="vertical-align:top">{@code 'm'}
1678  *     <td style="vertical-align:top"> <code>'\u006d'</code>
1679  *     <td> Month, formatted as two digits with leading zeros as necessary,
1680  *     i.e. {@code 01 - 13}, where "{@code 01}" is the first month of the
1681  *     year and ("{@code 13}" is a special value required to support lunar
1682  *     calendars).
1683  *
1684  * <tr><td style="vertical-align:top">{@code 'd'}
1685  *     <td style="vertical-align:top"> <code>'\u0064'</code>
1686  *     <td> Day of month, formatted as two digits with leading zeros as
1687  *     necessary, i.e. {@code 01 - 31}, where "{@code 01}" is the first day
1688  *     of the month.
1689  *
1690  * <tr><td style="vertical-align:top">{@code 'e'}
1691  *     <td style="vertical-align:top"> <code>'\u0065'</code>
1692  *     <td> Day of month, formatted as two digits, i.e. {@code 1 - 31} where
1693  *     "{@code 1}" is the first day of the month.
1694  *

1695  * </table>
1696  *
1697  * <p> The following conversion characters are used for formatting common
1698  * date/time compositions.
1699  *
1700  * <table cellpadding=5 summary="composites">


1701  *
1702  * <tr><td style="vertical-align:top">{@code 'R'}
1703  *     <td style="vertical-align:top"> <code>'\u0052'</code>
1704  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM"}
1705  *
1706  * <tr><td style="vertical-align:top">{@code 'T'}
1707  *     <td style="vertical-align:top"> <code>'\u0054'</code>
1708  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}.
1709  *
1710  * <tr><td style="vertical-align:top">{@code 'r'}
1711  *     <td style="vertical-align:top"> <code>'\u0072'</code>
1712  *     <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS
1713  *     %Tp"}.  The location of the morning or afternoon marker
1714  *     ({@code '%Tp'}) may be locale-dependent.
1715  *
1716  * <tr><td style="vertical-align:top">{@code 'D'}
1717  *     <td style="vertical-align:top"> <code>'\u0044'</code>
1718  *     <td> Date formatted as {@code "%tm/%td/%ty"}.
1719  *
1720  * <tr><td style="vertical-align:top">{@code 'F'}
1721  *     <td style="vertical-align:top"> <code>'\u0046'</code>
1722  *     <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO&nbsp;8601</a>
1723  *     complete date formatted as {@code "%tY-%tm-%td"}.
1724  *
1725  * <tr><td style="vertical-align:top">{@code 'c'}
1726  *     <td style="vertical-align:top"> <code>'\u0063'</code>
1727  *     <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
1728  *     e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
1729  *

1730  * </table>
1731  *
1732  * <p> The {@code '-'} flag defined for <a href="#dFlags">General
1733  * conversions</a> applies.  If the {@code '#'} flag is given, then a {@link
1734  * FormatFlagsConversionMismatchException} will be thrown.
1735  *
1736  * <p> The width is the minimum number of characters to
1737  * be written to the output.  If the length of the converted value is less than
1738  * the {@code width} then the output will be padded by spaces
1739  * (<code>'\u0020'</code>) until the total number of characters equals width.
1740  * The padding is on the left by default.  If the {@code '-'} flag is given
1741  * then the padding will be on the right.  If width is not specified then there
1742  * is no minimum.
1743  *
1744  * <p> The precision is not applicable.  If the precision is specified then an
1745  * {@link IllegalFormatPrecisionException} will be thrown.
1746  *
1747  * <h4><a id="dper">Percent</a></h4>
1748  *
1749  * <p> The conversion does not correspond to any argument.
1750  *
1751  * <table cellpadding=5 summary="DTConv">


1752  *
1753  * <tr><td style="vertical-align:top">{@code '%'}
1754  *     <td> The result is a literal {@code '%'} (<code>'\u0025'</code>)
1755  *
1756  * <p> The width is the minimum number of characters to
1757  * be written to the output including the {@code '%'}.  If the length of the
1758  * converted value is less than the {@code width} then the output will be
1759  * padded by spaces (<code>'\u0020'</code>) until the total number of
1760  * characters equals width.  The padding is on the left.  If width is not
1761  * specified then just the {@code '%'} is output.
1762  *
1763  * <p> The {@code '-'} flag defined for <a href="#dFlags">General
1764  * conversions</a> applies.  If any other flags are provided, then a
1765  * {@link FormatFlagsConversionMismatchException} will be thrown.
1766  *
1767  * <p> The precision is not applicable.  If the precision is specified an
1768  * {@link IllegalFormatPrecisionException} will be thrown.
1769  *

1770  * </table>
1771  *
1772  * <h4><a id="dls">Line Separator</a></h4>
1773  *
1774  * <p> The conversion does not correspond to any argument.
1775  *
1776  * <table cellpadding=5 summary="DTConv">


1777  *
1778  * <tr><td style="vertical-align:top">{@code 'n'}
1779  *     <td> the platform-specific line separator as returned by {@link
1780  *     System#lineSeparator()}.
1781  *

1782  * </table>
1783  *
1784  * <p> Flags, width, and precision are not applicable.  If any are provided an
1785  * {@link IllegalFormatFlagsException}, {@link IllegalFormatWidthException},
1786  * and {@link IllegalFormatPrecisionException}, respectively will be thrown.
1787  *
1788  * <h4><a id="dpos">Argument Index</a></h4>
1789  *
1790  * <p> Format specifiers can reference arguments in three ways:
1791  *
1792  * <ul>
1793  *
1794  * <li> <i>Explicit indexing</i> is used when the format specifier contains an
1795  * argument index.  The argument index is a decimal integer indicating the
1796  * position of the argument in the argument list.  The first argument is
1797  * referenced by "{@code 1$}", the second by "{@code 2$}", etc.  An argument
1798  * may be referenced more than once.
1799  *
1800  * <p> For example:
1801  *




 273  * <li> <b>Line Separator</b> - produces the platform-specific line separator
 274  *
 275  * </ol>
 276  *
 277  * <p> For category <i>General</i>, <i>Character</i>, <i>Numberic</i>,
 278  * <i>Integral</i> and <i>Date/Time</i> conversion, unless otherwise specified,
 279  * if the argument <i>arg</i> is {@code null}, then the result is "{@code null}".
 280  *
 281  * <p> The following table summarizes the supported conversions.  Conversions
 282  * denoted by an upper-case character (i.e. {@code 'B'}, {@code 'H'},
 283  * {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, {@code 'G'},
 284  * {@code 'A'}, and {@code 'T'}) are the same as those for the corresponding
 285  * lower-case conversion characters except that the result is converted to
 286  * upper case according to the rules of the prevailing {@link java.util.Locale
 287  * Locale}.  The result is equivalent to the following invocation of {@link
 288  * String#toUpperCase(Locale)}
 289  *
 290  * <pre>
 291  *    out.toUpperCase(Locale.getDefault(Locale.Category.FORMAT)) </pre>
 292  *
 293  * <table class="altrows">
 294  * <caption style="display:none">genConv</caption>
 295  * <thead>
 296  * <tr><th style="vertical-align:bottom"> Conversion
 297  *     <th style="vertical-align:bottom"> Argument Category
 298  *     <th style="vertical-align:bottom"> Description
 299  * </thead>
 300  * <tbody>
 301  * <tr><td style="vertical-align:top"> {@code 'b'}, {@code 'B'}
 302  *     <td style="vertical-align:top"> general
 303  *     <td> If the argument <i>arg</i> is {@code null}, then the result is
 304  *     "{@code false}".  If <i>arg</i> is a {@code boolean} or {@link
 305  *     Boolean}, then the result is the string returned by {@link
 306  *     String#valueOf(boolean) String.valueOf(arg)}.  Otherwise, the result is
 307  *     "true".
 308  *
 309  * <tr><td style="vertical-align:top"> {@code 'h'}, {@code 'H'}
 310  *     <td style="vertical-align:top"> general
 311  *     <td> The result is obtained by invoking
 312  *     {@code Integer.toHexString(arg.hashCode())}.
 313  *
 314  * <tr><td style="vertical-align:top"> {@code 's'}, {@code 'S'}
 315  *     <td style="vertical-align:top"> general
 316  *     <td> If <i>arg</i> implements {@link Formattable}, then
 317  *     {@link Formattable#formatTo arg.formatTo} is invoked. Otherwise, the
 318  *     result is obtained by invoking {@code arg.toString()}.
 319  *
 320  * <tr><td style="vertical-align:top">{@code 'c'}, {@code 'C'}


 350  * <tr><td style="vertical-align:top">{@code 'a'}, {@code 'A'}
 351  *     <td style="vertical-align:top"> floating point
 352  *     <td> The result is formatted as a hexadecimal floating-point number with
 353  *     a significand and an exponent. This conversion is <b>not</b> supported
 354  *     for the {@code BigDecimal} type despite the latter's being in the
 355  *     <i>floating point</i> argument category.
 356  *
 357  * <tr><td style="vertical-align:top">{@code 't'}, {@code 'T'}
 358  *     <td style="vertical-align:top"> date/time
 359  *     <td> Prefix for date and time conversion characters.  See <a
 360  *     href="#dt">Date/Time Conversions</a>.
 361  *
 362  * <tr><td style="vertical-align:top">{@code '%'}
 363  *     <td style="vertical-align:top"> percent
 364  *     <td> The result is a literal {@code '%'} (<code>'\u0025'</code>)
 365  *
 366  * <tr><td style="vertical-align:top">{@code 'n'}
 367  *     <td style="vertical-align:top"> line separator
 368  *     <td> The result is the platform-specific line separator
 369  *
 370  * </tbody>
 371  * </table>
 372  *
 373  * <p> Any characters not explicitly defined as conversions are illegal and are
 374  * reserved for future extensions.
 375  *
 376  * <h4><a id="dt">Date/Time Conversions</a></h4>
 377  *
 378  * <p> The following date and time conversion suffix characters are defined for
 379  * the {@code 't'} and {@code 'T'} conversions.  The types are similar to but
 380  * not completely identical to those defined by GNU {@code date} and POSIX
 381  * {@code strftime(3c)}.  Additional conversion types are provided to access
 382  * Java-specific functionality (e.g. {@code 'L'} for milliseconds within the
 383  * second).
 384  *
 385  * <p> The following conversion characters are used for formatting times:
 386  *
 387  * <table class="altrows">
 388  * <caption style="display:none">time</caption>
 389  * <tbody>
 390  * <tr><td style="vertical-align:top"> {@code 'H'}
 391  *     <td> Hour of the day for the 24-hour clock, formatted as two digits with
 392  *     a leading zero as necessary i.e. {@code 00 - 23}.
 393  *
 394  * <tr><td style="vertical-align:top">{@code 'I'}
 395  *     <td> Hour for the 12-hour clock, formatted as two digits with a leading
 396  *     zero as necessary, i.e.  {@code 01 - 12}.
 397  *
 398  * <tr><td style="vertical-align:top">{@code 'k'}
 399  *     <td> Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}.
 400  *
 401  * <tr><td style="vertical-align:top">{@code 'l'}
 402  *     <td> Hour for the 12-hour clock, i.e. {@code 1 - 12}.
 403  *
 404  * <tr><td style="vertical-align:top">{@code 'M'}
 405  *     <td> Minute within the hour formatted as two digits with a leading zero
 406  *     as necessary, i.e.  {@code 00 - 59}.
 407  *
 408  * <tr><td style="vertical-align:top">{@code 'S'}
 409  *     <td> Seconds within the minute, formatted as two digits with a leading


 433  *     instance of the Java virtual machine.
 434  *
 435  * <tr><td style="vertical-align:top">{@code 'Z'}
 436  *     <td> A string representing the abbreviation for the time zone.  This
 437  *     value will be adjusted as necessary for Daylight Saving Time.  For
 438  *     {@code long}, {@link Long}, and {@link Date} the  time zone used is
 439  *     the {@linkplain TimeZone#getDefault() default time zone} for this
 440  *     instance of the Java virtual machine.  The Formatter's locale will
 441  *     supersede the locale of the argument (if any).
 442  *
 443  * <tr><td style="vertical-align:top">{@code 's'}
 444  *     <td> Seconds since the beginning of the epoch starting at 1 January 1970
 445  *     {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to
 446  *     {@code Long.MAX_VALUE/1000}.
 447  *
 448  * <tr><td style="vertical-align:top">{@code 'Q'}
 449  *     <td> Milliseconds since the beginning of the epoch starting at 1 January
 450  *     1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to
 451  *     {@code Long.MAX_VALUE}.
 452  *
 453  * </tbody>
 454  * </table>
 455  *
 456  * <p> The following conversion characters are used for formatting dates:
 457  *
 458  * <table class="altrows">
 459  * <caption style="display:none">date</caption>
 460  * <tbody>
 461  *
 462  * <tr><td style="vertical-align:top">{@code 'B'}
 463  *     <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
 464  *     full month name}, e.g. {@code "January"}, {@code "February"}.
 465  *
 466  * <tr><td style="vertical-align:top">{@code 'b'}
 467  *     <td> Locale-specific {@linkplain
 468  *     java.text.DateFormatSymbols#getShortMonths abbreviated month name},
 469  *     e.g. {@code "Jan"}, {@code "Feb"}.
 470  *
 471  * <tr><td style="vertical-align:top">{@code 'h'}
 472  *     <td> Same as {@code 'b'}.
 473  *
 474  * <tr><td style="vertical-align:top">{@code 'A'}
 475  *     <td> Locale-specific full name of the {@linkplain
 476  *     java.text.DateFormatSymbols#getWeekdays day of the week},
 477  *     e.g. {@code "Sunday"}, {@code "Monday"}
 478  *
 479  * <tr><td style="vertical-align:top">{@code 'a'}
 480  *     <td> Locale-specific short name of the {@linkplain


 492  *
 493  * <tr><td style="vertical-align:top">{@code 'y'}
 494  *     <td> Last two digits of the year, formatted with leading zeros as
 495  *     necessary, i.e. {@code 00 - 99}.
 496  *
 497  * <tr><td style="vertical-align:top">{@code 'j'}
 498  *     <td> Day of year, formatted as three digits with leading zeros as
 499  *     necessary, e.g. {@code 001 - 366} for the Gregorian calendar.
 500  *
 501  * <tr><td style="vertical-align:top">{@code 'm'}
 502  *     <td> Month, formatted as two digits with leading zeros as necessary,
 503  *     i.e. {@code 01 - 13}.
 504  *
 505  * <tr><td style="vertical-align:top">{@code 'd'}
 506  *     <td> Day of month, formatted as two digits with leading zeros as
 507  *     necessary, i.e. {@code 01 - 31}
 508  *
 509  * <tr><td style="vertical-align:top">{@code 'e'}
 510  *     <td> Day of month, formatted as two digits, i.e. {@code 1 - 31}.
 511  *
 512  * </tbody>
 513  * </table>
 514  *
 515  * <p> The following conversion characters are used for formatting common
 516  * date/time compositions.
 517  *
 518  * <table class="altrows">
 519  * <caption style="display:none">composites</caption>
 520  * <tbody>
 521  *
 522  * <tr><td style="vertical-align:top">{@code 'R'}
 523  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM"}
 524  *
 525  * <tr><td style="vertical-align:top">{@code 'T'}
 526  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}.
 527  *
 528  * <tr><td style="vertical-align:top">{@code 'r'}
 529  *     <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS %Tp"}.
 530  *     The location of the morning or afternoon marker ({@code '%Tp'}) may be
 531  *     locale-dependent.
 532  *
 533  * <tr><td style="vertical-align:top">{@code 'D'}
 534  *     <td> Date formatted as {@code "%tm/%td/%ty"}.
 535  *
 536  * <tr><td style="vertical-align:top">{@code 'F'}
 537  *     <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO&nbsp;8601</a>
 538  *     complete date formatted as {@code "%tY-%tm-%td"}.
 539  *
 540  * <tr><td style="vertical-align:top">{@code 'c'}
 541  *     <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
 542  *     e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
 543  * 
 544  * </tbody>
 545  * </table>
 546  *
 547  * <p> Any characters not explicitly defined as date/time conversion suffixes
 548  * are illegal and are reserved for future extensions.
 549  *
 550  * <h4> Flags </h4>
 551  *
 552  * <p> The following table summarizes the supported flags.  <i>y</i> means the
 553  * flag is supported for the indicated argument types.
 554  *
 555  * <table class="altrows">
 556  * <caption style="display:none">genConv</caption>
 557  * <thead>
 558  * <tr><th style="vertical-align:bottom"> Flag <th style="vertical-align:bottom"> General
 559  *     <th style="vertical-align:bottom"> Character <th style="vertical-align:bottom"> Integral
 560  *     <th style="vertical-align:bottom"> Floating Point
 561  *     <th style="vertical-align:bottom"> Date/Time
 562  *     <th style="vertical-align:bottom"> Description
 563  * </thead>
 564  * <tbody>
 565  * <tr><td> '-' <td style="text-align:center; vertical-align:top"> y
 566  *     <td style="text-align:center; vertical-align:top"> y
 567  *     <td style="text-align:center; vertical-align:top"> y
 568  *     <td style="text-align:center; vertical-align:top"> y
 569  *     <td style="text-align:center; vertical-align:top"> y
 570  *     <td> The result will be left-justified.
 571  *
 572  * <tr><td> '#' <td style="text-align:center; vertical-align:top"> y<sup>1</sup>
 573  *     <td style="text-align:center; vertical-align:top"> -
 574  *     <td style="text-align:center; vertical-align:top"> y<sup>3</sup>
 575  *     <td style="text-align:center; vertical-align:top"> y
 576  *     <td style="text-align:center; vertical-align:top"> -
 577  *     <td> The result should use a conversion-dependent alternate form
 578  *
 579  * <tr><td> '+' <td style="text-align:center; vertical-align:top"> -
 580  *     <td style="text-align:center; vertical-align:top"> -
 581  *     <td style="text-align:center; vertical-align:top"> y<sup>4</sup>
 582  *     <td style="text-align:center; vertical-align:top"> y
 583  *     <td style="text-align:center; vertical-align:top"> -
 584  *     <td> The result will always include a sign


 595  *     <td style="text-align:center; vertical-align:top"> y
 596  *     <td style="text-align:center; vertical-align:top"> y
 597  *     <td style="text-align:center; vertical-align:top"> -
 598  *     <td> The result will be zero-padded
 599  *
 600  * <tr><td> ',' <td style="text-align:center; vertical-align:top"> -
 601  *     <td style="text-align:center; vertical-align:top"> -
 602  *     <td style="text-align:center; vertical-align:top"> y<sup>2</sup>
 603  *     <td style="text-align:center; vertical-align:top"> y<sup>5</sup>
 604  *     <td style="text-align:center; vertical-align:top"> -
 605  *     <td> The result will include locale-specific {@linkplain
 606  *     java.text.DecimalFormatSymbols#getGroupingSeparator grouping separators}
 607  *
 608  * <tr><td> '(' <td style="text-align:center; vertical-align:top"> -
 609  *     <td style="text-align:center; vertical-align:top"> -
 610  *     <td style="text-align:center; vertical-align:top"> y<sup>4</sup>
 611  *     <td style="text-align:center; vertical-align:top"> y<sup>5</sup>
 612  *     <td style="text-align:center"> -
 613  *     <td> The result will enclose negative numbers in parentheses
 614  *
 615  * </tbody>
 616  * </table>
 617  *
 618  * <p> <sup>1</sup> Depends on the definition of {@link Formattable}.
 619  *
 620  * <p> <sup>2</sup> For {@code 'd'} conversion only.
 621  *
 622  * <p> <sup>3</sup> For {@code 'o'}, {@code 'x'}, and {@code 'X'}
 623  * conversions only.
 624  *
 625  * <p> <sup>4</sup> For {@code 'd'}, {@code 'o'}, {@code 'x'}, and
 626  * {@code 'X'} conversions applied to {@link java.math.BigInteger BigInteger}
 627  * or {@code 'd'} applied to {@code byte}, {@link Byte}, {@code short}, {@link
 628  * Short}, {@code int} and {@link Integer}, {@code long}, and {@link Long}.
 629  *
 630  * <p> <sup>5</sup> For {@code 'e'}, {@code 'E'}, {@code 'f'},
 631  * {@code 'g'}, and {@code 'G'} conversions only.
 632  *
 633  * <p> Any characters not explicitly defined as flags are illegal and are
 634  * reserved for future extensions.
 635  *


 702  *
 703  * <p> For category <i>General</i>, <i>Character</i>, <i>Numberic</i>,
 704  * <i>Integral</i> and <i>Date/Time</i> conversion, unless otherwise specified,
 705  * if the argument <i>arg</i> is {@code null}, then the result is "{@code null}".
 706  *
 707  * <p> Conversions denoted by an upper-case character (i.e. {@code 'B'},
 708  * {@code 'H'}, {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'},
 709  * {@code 'G'}, {@code 'A'}, and {@code 'T'}) are the same as those for the
 710  * corresponding lower-case conversion characters except that the result is
 711  * converted to upper case according to the rules of the prevailing {@link
 712  * java.util.Locale Locale}.  The result is equivalent to the following
 713  * invocation of {@link String#toUpperCase(Locale)}
 714  *
 715  * <pre>
 716  *    out.toUpperCase(Locale.getDefault(Locale.Category.FORMAT)) </pre>
 717  *
 718  * <h4><a id="dgen">General</a></h4>
 719  *
 720  * <p> The following general conversions may be applied to any argument type:
 721  *
 722  * <table class="altrows">
 723  * <caption style="display:none">dgConv</caption>
 724  * <tbody>
 725  *
 726  * <tr><td style="vertical-align:top"> {@code 'b'}
 727  *     <td style="vertical-align:top"> <code>'\u0062'</code>
 728  *     <td> Produces either "{@code true}" or "{@code false}" as returned by
 729  *     {@link Boolean#toString(boolean)}.
 730  *
 731  *     <p> If the argument is {@code null}, then the result is
 732  *     "{@code false}".  If the argument is a {@code boolean} or {@link
 733  *     Boolean}, then the result is the string returned by {@link
 734  *     String#valueOf(boolean) String.valueOf()}.  Otherwise, the result is
 735  *     "{@code true}".
 736  *
 737  *     <p> If the {@code '#'} flag is given, then a {@link
 738  *     FormatFlagsConversionMismatchException} will be thrown.
 739  *
 740  * <tr><td style="vertical-align:top"> {@code 'B'}
 741  *     <td style="vertical-align:top"> <code>'\u0042'</code>
 742  *     <td> The upper-case variant of {@code 'b'}.
 743  *
 744  * <tr><td style="vertical-align:top"> {@code 'h'}


 755  *     <td style="vertical-align:top"> <code>'\u0048'</code>
 756  *     <td> The upper-case variant of {@code 'h'}.
 757  *
 758  * <tr><td style="vertical-align:top"> {@code 's'}
 759  *     <td style="vertical-align:top"> <code>'\u0073'</code>
 760  *     <td> Produces a string.
 761  *
 762  *     <p> If the argument implements {@link Formattable}, then
 763  *     its {@link Formattable#formatTo formatTo} method is invoked.
 764  *     Otherwise, the result is obtained by invoking the argument's
 765  *     {@code toString()} method.
 766  *
 767  *     <p> If the {@code '#'} flag is given and the argument is not a {@link
 768  *     Formattable} , then a {@link FormatFlagsConversionMismatchException}
 769  *     will be thrown.
 770  *
 771  * <tr><td style="vertical-align:top"> {@code 'S'}
 772  *     <td style="vertical-align:top"> <code>'\u0053'</code>
 773  *     <td> The upper-case variant of {@code 's'}.
 774  *
 775  * </tbody>
 776  * </table>
 777  *
 778  * <p> The following <a id="dFlags">flags</a> apply to general conversions:
 779  *
 780  * <table class="altrows">
 781  * <caption style="display:none">dFlags</caption>
 782  * <tbody>
 783  *
 784  * <tr><td style="vertical-align:top"> {@code '-'}
 785  *     <td style="vertical-align:top"> <code>'\u002d'</code>
 786  *     <td> Left justifies the output.  Spaces (<code>'\u0020'</code>) will be
 787  *     added at the end of the converted value as required to fill the minimum
 788  *     width of the field.  If the width is not provided, then a {@link
 789  *     MissingFormatWidthException} will be thrown.  If this flag is not given
 790  *     then the output will be right-justified.
 791  *
 792  * <tr><td style="vertical-align:top"> {@code '#'}
 793  *     <td style="vertical-align:top"> <code>'\u0023'</code>
 794  *     <td> Requires the output use an alternate form.  The definition of the
 795  *     form is specified by the conversion.
 796  *
 797  * </tbody>
 798  * </table>
 799  *
 800  * <p> The <a id="genWidth">width</a> is the minimum number of characters to
 801  * be written to the
 802  * output.  If the length of the converted value is less than the width then
 803  * the output will be padded by <code>'&nbsp;&nbsp;'</code> (<code>'\u0020'</code>)
 804  * until the total number of characters equals the width.  The padding is on
 805  * the left by default.  If the {@code '-'} flag is given, then the padding
 806  * will be on the right.  If the width is not specified then there is no
 807  * minimum.
 808  *
 809  * <p> The precision is the maximum number of characters to be written to the
 810  * output.  The precision is applied before the width, thus the output will be
 811  * truncated to {@code precision} characters even if the width is greater than
 812  * the precision.  If the precision is not specified then there is no explicit
 813  * limit on the number of characters.
 814  *
 815  * <h4><a id="dchar">Character</a></h4>
 816  *
 817  * This conversion may be applied to {@code char} and {@link Character}.  It
 818  * may also be applied to the types {@code byte}, {@link Byte},
 819  * {@code short}, and {@link Short}, {@code int} and {@link Integer} when
 820  * {@link Character#isValidCodePoint} returns {@code true}.  If it returns
 821  * {@code false} then an {@link IllegalFormatCodePointException} will be
 822  * thrown.
 823  *
 824  * <table class="altrows">
 825  * <caption style="display:none">charConv</caption>
 826  * <tbody>
 827  *
 828  * <tr><td style="vertical-align:top"> {@code 'c'}
 829  *     <td style="vertical-align:top"> <code>'\u0063'</code>
 830  *     <td> Formats the argument as a Unicode character as described in <a
 831  *     href="../lang/Character.html#unicode">Unicode Character
 832  *     Representation</a>.  This may be more than one 16-bit {@code char} in
 833  *     the case where the argument represents a supplementary character.
 834  *
 835  *     <p> If the {@code '#'} flag is given, then a {@link
 836  *     FormatFlagsConversionMismatchException} will be thrown.
 837  *
 838  * <tr><td style="vertical-align:top"> {@code 'C'}
 839  *     <td style="vertical-align:top"> <code>'\u0043'</code>
 840  *     <td> The upper-case variant of {@code 'c'}.
 841  *
 842  * </tbody>
 843  * </table>
 844  *
 845  * <p> The {@code '-'} flag defined for <a href="#dFlags">General
 846  * conversions</a> applies.  If the {@code '#'} flag is given, then a {@link
 847  * FormatFlagsConversionMismatchException} will be thrown.
 848  *
 849  * <p> The width is defined as for <a href="#genWidth">General conversions</a>.
 850  *
 851  * <p> The precision is not applicable.  If the precision is specified then an
 852  * {@link IllegalFormatPrecisionException} will be thrown.
 853  *
 854  * <h4><a id="dnum">Numeric</a></h4>
 855  *
 856  * <p> Numeric conversions are divided into the following categories:
 857  *
 858  * <ol>
 859  *
 860  * <li> <a href="#dnint"><b>Byte, Short, Integer, and Long</b></a>
 861  *
 862  * <li> <a href="#dnbint"><b>BigInteger</b></a>


 908  * {@code '('} flag is not given, then a {@code '-'} (<code>'\u002d'</code>)
 909  * is prepended.
 910  *
 911  * <li> If the {@code '+'} flag is given and the value is positive or zero (or
 912  * floating-point positive zero), then a {@code '+'} (<code>'\u002b'</code>)
 913  * will be prepended.
 914  *
 915  * </ol>
 916  *
 917  * <p> If the value is NaN or positive infinity the literal strings "NaN" or
 918  * "Infinity" respectively, will be output.  If the value is negative infinity,
 919  * then the output will be "(Infinity)" if the {@code '('} flag is given
 920  * otherwise the output will be "-Infinity".  These values are not localized.
 921  *
 922  * <p><a id="dnint"><b> Byte, Short, Integer, and Long </b></a>
 923  *
 924  * <p> The following conversions may be applied to {@code byte}, {@link Byte},
 925  * {@code short}, {@link Short}, {@code int} and {@link Integer},
 926  * {@code long}, and {@link Long}.
 927  *
 928  * <table class="altrows">
 929  * <caption style="display:none">IntConv</caption>
 930  * <tbody>
 931  *
 932  * <tr><td style="vertical-align:top"> {@code 'd'}
 933  *     <td style="vertical-align:top"> <code>'\u0064'</code>
 934  *     <td> Formats the argument as a decimal integer. The <a
 935  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
 936  *
 937  *     <p> If the {@code '0'} flag is given and the value is negative, then
 938  *     the zero padding will occur after the sign.
 939  *
 940  *     <p> If the {@code '#'} flag is given then a {@link
 941  *     FormatFlagsConversionMismatchException} will be thrown.
 942  *
 943  * <tr><td style="vertical-align:top"> {@code 'o'}
 944  *     <td style="vertical-align:top"> <code>'\u006f'</code>
 945  *     <td> Formats the argument as an integer in base eight.  No localization
 946  *     is applied.
 947  *
 948  *     <p> If <i>x</i> is negative then the result will be an unsigned value
 949  *     generated by adding 2<sup>n</sup> to the value where {@code n} is the
 950  *     number of bits in the type as returned by the static {@code SIZE} field


 976  *
 977  *     <p> If the {@code '#'} flag is given then the output will always begin
 978  *     with the radix indicator {@code "0x"}.
 979  *
 980  *     <p> If the {@code '0'} flag is given then the output will be padded to
 981  *     the field width with leading zeros after the radix indicator or sign (if
 982  *     present).
 983  *
 984  *     <p> If {@code '('}, <code>'&nbsp;&nbsp;'</code>, {@code '+'}, or
 985  *     {@code ','} flags are given then a {@link
 986  *     FormatFlagsConversionMismatchException} will be thrown.
 987  *
 988  * <tr><td style="vertical-align:top"> {@code 'X'}
 989  *     <td style="vertical-align:top"> <code>'\u0058'</code>
 990  *     <td> The upper-case variant of {@code 'x'}.  The entire string
 991  *     representing the number will be converted to {@linkplain
 992  *     String#toUpperCase upper case} including the {@code 'x'} (if any) and
 993  *     all hexadecimal digits {@code 'a'} - {@code 'f'}
 994  *     (<code>'\u0061'</code> -  <code>'\u0066'</code>).
 995  *
 996  * </tbody>
 997  * </table>
 998  *
 999  * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and
1000  * both the {@code '#'} and the {@code '0'} flags are given, then result will
1001  * contain the radix indicator ({@code '0'} for octal and {@code "0x"} or
1002  * {@code "0X"} for hexadecimal), some number of zeros (based on the width),
1003  * and the value.
1004  *
1005  * <p> If the {@code '-'} flag is not given, then the space padding will occur
1006  * before the sign.
1007  *
1008  * <p> The following <a id="intFlags">flags</a> apply to numeric integral
1009  * conversions:
1010  *
1011  * <table class="altrows">
1012  * <caption style="display:none">intFlags</caption>
1013  * <tbody>
1014  *
1015  * <tr><td style="vertical-align:top"> {@code '+'}
1016  *     <td style="vertical-align:top"> <code>'\u002b'</code>
1017  *     <td> Requires the output to include a positive sign for all positive
1018  *     numbers.  If this flag is not given then only negative values will
1019  *     include a sign.
1020  *
1021  *     <p> If both the {@code '+'} and <code>'&nbsp;&nbsp;'</code> flags are given
1022  *     then an {@link IllegalFormatFlagsException} will be thrown.
1023  *
1024  * <tr><td style="vertical-align:top"> <code>'&nbsp;&nbsp;'</code>
1025  *     <td style="vertical-align:top"> <code>'\u0020'</code>
1026  *     <td> Requires the output to include a single extra space
1027  *     (<code>'\u0020'</code>) for non-negative values.
1028  *
1029  *     <p> If both the {@code '+'} and <code>'&nbsp;&nbsp;'</code> flags are given
1030  *     then an {@link IllegalFormatFlagsException} will be thrown.
1031  *
1032  * <tr><td style="vertical-align:top"> {@code '0'}
1033  *     <td style="vertical-align:top"> <code>'\u0030'</code>


1036  *     width following any sign or radix indicator except when converting NaN
1037  *     or infinity.  If the width is not provided, then a {@link
1038  *     MissingFormatWidthException} will be thrown.
1039  *
1040  *     <p> If both the {@code '-'} and {@code '0'} flags are given then an
1041  *     {@link IllegalFormatFlagsException} will be thrown.
1042  *
1043  * <tr><td style="vertical-align:top"> {@code ','}
1044  *     <td style="vertical-align:top"> <code>'\u002c'</code>
1045  *     <td> Requires the output to include the locale-specific {@linkplain
1046  *     java.text.DecimalFormatSymbols#getGroupingSeparator group separators} as
1047  *     described in the <a href="#L10nGroup">"group" section</a> of the
1048  *     localization algorithm.
1049  *
1050  * <tr><td style="vertical-align:top"> {@code '('}
1051  *     <td style="vertical-align:top"> <code>'\u0028'</code>
1052  *     <td> Requires the output to prepend a {@code '('}
1053  *     (<code>'\u0028'</code>) and append a {@code ')'}
1054  *     (<code>'\u0029'</code>) to negative values.
1055  *
1056  * </tbody>
1057  * </table>
1058  *
1059  * <p> If no <a id="intdFlags">flags</a> are given the default formatting is
1060  * as follows:
1061  *
1062  * <ul>
1063  *
1064  * <li> The output is right-justified within the {@code width}
1065  *
1066  * <li> Negative numbers begin with a {@code '-'} (<code>'\u002d'</code>)
1067  *
1068  * <li> Positive numbers and zero do not include a sign or extra leading
1069  * space
1070  *
1071  * <li> No grouping separators are included
1072  *
1073  * </ul>
1074  *
1075  * <p> The <a id="intWidth">width</a> is the minimum number of characters to
1076  * be written to the output.  This includes any signs, digits, grouping
1077  * separators, radix indicator, and parentheses.  If the length of the
1078  * converted value is less than the width then the output will be padded by
1079  * spaces (<code>'\u0020'</code>) until the total number of characters equals
1080  * width.  The padding is on the left by default.  If {@code '-'} flag is
1081  * given then the padding will be on the right.  If width is not specified then
1082  * there is no minimum.
1083  *
1084  * <p> The precision is not applicable.  If precision is specified then an
1085  * {@link IllegalFormatPrecisionException} will be thrown.
1086  *
1087  * <p><a id="dnbint"><b> BigInteger </b></a>
1088  *
1089  * <p> The following conversions may be applied to {@link
1090  * java.math.BigInteger}.
1091  *
1092  * <table class="altrows">
1093  * <caption style="display:none">bIntConv</caption>
1094  * <tbody>
1095  *
1096  * <tr><td style="vertical-align:top"> {@code 'd'}
1097  *     <td style="vertical-align:top"> <code>'\u0064'</code>
1098  *     <td> Requires the output to be formatted as a decimal integer. The <a
1099  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
1100  *
1101  *     <p> If the {@code '#'} flag is given {@link
1102  *     FormatFlagsConversionMismatchException} will be thrown.
1103  *
1104  * <tr><td style="vertical-align:top"> {@code 'o'}
1105  *     <td style="vertical-align:top"> <code>'\u006f'</code>
1106  *     <td> Requires the output to be formatted as an integer in base eight.
1107  *     No localization is applied.
1108  *
1109  *     <p> If <i>x</i> is negative then the result will be a signed value
1110  *     beginning with {@code '-'} (<code>'\u002d'</code>).  Signed output is
1111  *     allowed for this type because unlike the primitive types it is not
1112  *     possible to create an unsigned equivalent without assuming an explicit
1113  *     data-type size.
1114  *


1139  *     then the result will begin with {@code '+'} (<code>'\u002b'</code>).
1140  *
1141  *     <p> If the {@code '#'} flag is given then the output will always begin
1142  *     with the radix indicator {@code "0x"}.
1143  *
1144  *     <p> If the {@code '0'} flag is given then the output will be padded to
1145  *     the field width with leading zeros after the radix indicator or sign (if
1146  *     present).
1147  *
1148  *     <p> If the {@code ','} flag is given then a {@link
1149  *     FormatFlagsConversionMismatchException} will be thrown.
1150  *
1151  * <tr><td style="vertical-align:top"> {@code 'X'}
1152  *     <td style="vertical-align:top"> <code>'\u0058'</code>
1153  *     <td> The upper-case variant of {@code 'x'}.  The entire string
1154  *     representing the number will be converted to {@linkplain
1155  *     String#toUpperCase upper case} including the {@code 'x'} (if any) and
1156  *     all hexadecimal digits {@code 'a'} - {@code 'f'}
1157  *     (<code>'\u0061'</code> - <code>'\u0066'</code>).
1158  *
1159  * </tbody>
1160  * </table>
1161  *
1162  * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and
1163  * both the {@code '#'} and the {@code '0'} flags are given, then result will
1164  * contain the base indicator ({@code '0'} for octal and {@code "0x"} or
1165  * {@code "0X"} for hexadecimal), some number of zeros (based on the width),
1166  * and the value.
1167  *
1168  * <p> If the {@code '0'} flag is given and the value is negative, then the
1169  * zero padding will occur after the sign.
1170  *
1171  * <p> If the {@code '-'} flag is not given, then the space padding will occur
1172  * before the sign.
1173  *
1174  * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1175  * Long apply.  The <a href="#intdFlags">default behavior</a> when no flags are
1176  * given is the same as for Byte, Short, Integer, and Long.
1177  *
1178  * <p> The specification of <a href="#intWidth">width</a> is the same as
1179  * defined for Byte, Short, Integer, and Long.
1180  *
1181  * <p> The precision is not applicable.  If precision is specified then an
1182  * {@link IllegalFormatPrecisionException} will be thrown.
1183  *
1184  * <p><a id="dndec"><b> Float and Double</b></a>
1185  *
1186  * <p> The following conversions may be applied to {@code float}, {@link
1187  * Float}, {@code double} and {@link Double}.
1188  *
1189  * <table class="altrows">
1190  * <caption style="display:none">floatConv</caption>
1191  * <tbody>
1192  *
1193  * <tr><td style="vertical-align:top"> {@code 'e'}
1194  *     <td style="vertical-align:top"> <code>'\u0065'</code>
1195  *     <td> Requires the output to be formatted using <a
1196  *     id="scientific">computerized scientific notation</a>.  The <a
1197  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
1198  *
1199  *     <p> The formatting of the magnitude <i>m</i> depends upon its value.
1200  *
1201  *     <p> If <i>m</i> is NaN or infinite, the literal strings "NaN" or
1202  *     "Infinity", respectively, will be output.  These values are not
1203  *     localized.
1204  *
1205  *     <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1206  *     will be {@code "+00"}.
1207  *
1208  *     <p> Otherwise, the result is a string that represents the sign and
1209  *     magnitude (absolute value) of the argument.  The formatting of the sign
1210  *     is described in the <a href="#L10nAlgorithm">localization
1211  *     algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its


1348  *     {@code 'p-1022'}.  If the precision is in the interval
1349  *     [1,&nbsp;12], the subnormal value is normalized such that it
1350  *     begins with the characters {@code '0x1.'}, rounded to the number of
1351  *     hexadecimal digits of precision, and the exponent adjusted
1352  *     accordingly.  Note that there must be at least one nonzero digit in a
1353  *     subnormal significand.
1354  *
1355  *     </ul>
1356  *
1357  *     <p> If the {@code '('} or {@code ','} flags are given, then a {@link
1358  *     FormatFlagsConversionMismatchException} will be thrown.
1359  *
1360  * <tr><td style="vertical-align:top"> {@code 'A'}
1361  *     <td style="vertical-align:top"> <code>'\u0041'</code>
1362  *     <td> The upper-case variant of {@code 'a'}.  The entire string
1363  *     representing the number will be converted to upper case including the
1364  *     {@code 'x'} (<code>'\u0078'</code>) and {@code 'p'}
1365  *     (<code>'\u0070'</code> and all hexadecimal digits {@code 'a'} -
1366  *     {@code 'f'} (<code>'\u0061'</code> - <code>'\u0066'</code>).
1367  *
1368  * </tbody>
1369  * </table>
1370  *
1371  * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1372  * Long apply.
1373  *
1374  * <p> If the {@code '#'} flag is given, then the decimal separator will
1375  * always be present.
1376  *
1377  * <p> If no <a id="floatdFlags">flags</a> are given the default formatting
1378  * is as follows:
1379  *
1380  * <ul>
1381  *
1382  * <li> The output is right-justified within the {@code width}
1383  *
1384  * <li> Negative numbers begin with a {@code '-'}
1385  *
1386  * <li> Positive numbers and positive zero do not include a sign or extra
1387  * leading space
1388  *


1406  * {@code 'E'} or {@code 'f'}, then the precision is the number of digits
1407  * after the decimal separator.  If the precision is not specified, then it is
1408  * assumed to be {@code 6}.
1409  *
1410  * <p> If the conversion is {@code 'g'} or {@code 'G'}, then the precision is
1411  * the total number of significant digits in the resulting magnitude after
1412  * rounding.  If the precision is not specified, then the default value is
1413  * {@code 6}.  If the precision is {@code 0}, then it is taken to be
1414  * {@code 1}.
1415  *
1416  * <p> If the conversion is {@code 'a'} or {@code 'A'}, then the precision
1417  * is the number of hexadecimal digits after the radix point.  If the
1418  * precision is not provided, then all of the digits as returned by {@link
1419  * Double#toHexString(double)} will be output.
1420  *
1421  * <p><a id="dnbdec"><b> BigDecimal </b></a>
1422  *
1423  * <p> The following conversions may be applied {@link java.math.BigDecimal
1424  * BigDecimal}.
1425  *
1426  * <table class="altrows">
1427  * <caption style="display:none">floatConv</caption>
1428  * <tbody>
1429  *
1430  * <tr><td style="vertical-align:top"> {@code 'e'}
1431  *     <td style="vertical-align:top"> <code>'\u0065'</code>
1432  *     <td> Requires the output to be formatted using <a
1433  *     id="bscientific">computerized scientific notation</a>.  The <a
1434  *     href="#L10nAlgorithm">localization algorithm</a> is applied.
1435  *
1436  *     <p> The formatting of the magnitude <i>m</i> depends upon its value.
1437  *
1438  *     <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1439  *     will be {@code "+00"}.
1440  *
1441  *     <p> Otherwise, the result is a string that represents the sign and
1442  *     magnitude (absolute value) of the argument.  The formatting of the sign
1443  *     is described in the <a href="#L10nAlgorithm">localization
1444  *     algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1445  *     value.
1446  *
1447  *     <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
1448  *     &lt;= <i>m</i> &lt; 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the


1512  *     <p> The result is a string that represents the sign and magnitude
1513  *     (absolute value) of the argument.  The formatting of the sign is
1514  *     described in the <a href="#L10nAlgorithm">localization
1515  *     algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1516  *     value.
1517  *
1518  *     <p> The magnitude is formatted as the integer part of <i>m</i>, with no
1519  *     leading zeroes, followed by the decimal separator followed by one or
1520  *     more decimal digits representing the fractional part of <i>m</i>.
1521  *
1522  *     <p> The number of digits in the result for the fractional part of
1523  *     <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1524  *     specified then the default value is {@code 6}.  If the precision is
1525  *     less than the number of digits to the right of the decimal point
1526  *     then the value will be rounded using the
1527  *     {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1528  *     algorithm}.  Otherwise, zeros may be appended to reach the precision.
1529  *     For a canonical representation of the value, use {@link
1530  *     BigDecimal#toString()}.
1531  *
1532  * </tbody>
1533  * </table>
1534  *
1535  * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1536  * Long apply.
1537  *
1538  * <p> If the {@code '#'} flag is given, then the decimal separator will
1539  * always be present.
1540  *
1541  * <p> The <a href="#floatdFlags">default behavior</a> when no flags are
1542  * given is the same as for Float and Double.
1543  *
1544  * <p> The specification of <a href="#floatDWidth">width</a> and <a
1545  * href="#floatDPrec">precision</a> is the same as defined for Float and
1546  * Double.
1547  *
1548  * <h4><a id="ddt">Date/Time</a></h4>
1549  *
1550  * <p> This conversion may be applied to {@code long}, {@link Long}, {@link
1551  * Calendar}, {@link Date} and {@link TemporalAccessor TemporalAccessor}
1552  *
1553  * <table class="altrows">
1554  * <caption style="display:none">DTConv</caption>
1555  * <tbody>
1556  *
1557  * <tr><td style="vertical-align:top"> {@code 't'}
1558  *     <td style="vertical-align:top"> <code>'\u0074'</code>
1559  *     <td> Prefix for date and time conversion characters.
1560  * <tr><td style="vertical-align:top"> {@code 'T'}
1561  *     <td style="vertical-align:top"> <code>'\u0054'</code>
1562  *     <td> The upper-case variant of {@code 't'}.
1563  *
1564  * </tbody>
1565  * </table>
1566  *
1567  * <p> The following date and time conversion character suffixes are defined
1568  * for the {@code 't'} and {@code 'T'} conversions.  The types are similar to
1569  * but not completely identical to those defined by GNU {@code date} and
1570  * POSIX {@code strftime(3c)}.  Additional conversion types are provided to
1571  * access Java-specific functionality (e.g. {@code 'L'} for milliseconds
1572  * within the second).
1573  *
1574  * <p> The following conversion characters are used for formatting times:
1575  *
1576  * <table class="altrows">
1577  * <caption style="display:none">time</caption>
1578  * <tbody>
1579  *
1580  * <tr><td style="vertical-align:top"> {@code 'H'}
1581  *     <td style="vertical-align:top"> <code>'\u0048'</code>
1582  *     <td> Hour of the day for the 24-hour clock, formatted as two digits with
1583  *     a leading zero as necessary i.e. {@code 00 - 23}. {@code 00}
1584  *     corresponds to midnight.
1585  *
1586  * <tr><td style="vertical-align:top">{@code 'I'}
1587  *     <td style="vertical-align:top"> <code>'\u0049'</code>
1588  *     <td> Hour for the 12-hour clock, formatted as two digits with a leading
1589  *     zero as necessary, i.e.  {@code 01 - 12}.  {@code 01} corresponds to
1590  *     one o'clock (either morning or afternoon).
1591  *
1592  * <tr><td style="vertical-align:top">{@code 'k'}
1593  *     <td style="vertical-align:top"> <code>'\u006b'</code>
1594  *     <td> Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}.
1595  *     {@code 0} corresponds to midnight.
1596  *
1597  * <tr><td style="vertical-align:top">{@code 'l'}
1598  *     <td style="vertical-align:top"> <code>'\u006c'</code>


1646  *     <td> A string representing the abbreviation for the time zone.  This
1647  *     value will be adjusted as necessary for Daylight Saving Time.  For
1648  *     {@code long}, {@link Long}, and {@link Date} the time zone used is
1649  *     the {@linkplain TimeZone#getDefault() default time zone} for this
1650  *     instance of the Java virtual machine.  The Formatter's locale will
1651  *     supersede the locale of the argument (if any).
1652  *
1653  * <tr><td style="vertical-align:top">{@code 's'}
1654  *     <td style="vertical-align:top"> <code>'\u0073'</code>
1655  *     <td> Seconds since the beginning of the epoch starting at 1 January 1970
1656  *     {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to
1657  *     {@code Long.MAX_VALUE/1000}.
1658  *
1659  * <tr><td style="vertical-align:top">{@code 'Q'}
1660  *     <td style="vertical-align:top"> <code>'\u004f'</code>
1661  *     <td> Milliseconds since the beginning of the epoch starting at 1 January
1662  *     1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to
1663  *     {@code Long.MAX_VALUE}. The precision of this value is limited by
1664  *     the resolution of the underlying operating system or hardware.
1665  *
1666  * </tbody>
1667  * </table>
1668  *
1669  * <p> The following conversion characters are used for formatting dates:
1670  *
1671  * <table class="altrows">
1672  * <caption style="display:none">date</caption>
1673  * <tbody>
1674  *
1675  * <tr><td style="vertical-align:top">{@code 'B'}
1676  *     <td style="vertical-align:top"> <code>'\u0042'</code>
1677  *     <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
1678  *     full month name}, e.g. {@code "January"}, {@code "February"}.
1679  *
1680  * <tr><td style="vertical-align:top">{@code 'b'}
1681  *     <td style="vertical-align:top"> <code>'\u0062'</code>
1682  *     <td> Locale-specific {@linkplain
1683  *     java.text.DateFormatSymbols#getShortMonths abbreviated month name},
1684  *     e.g. {@code "Jan"}, {@code "Feb"}.
1685  *
1686  * <tr><td style="vertical-align:top">{@code 'h'}
1687  *     <td style="vertical-align:top"> <code>'\u0068'</code>
1688  *     <td> Same as {@code 'b'}.
1689  *
1690  * <tr><td style="vertical-align:top">{@code 'A'}
1691  *     <td style="vertical-align:top"> <code>'\u0041'</code>
1692  *     <td> Locale-specific full name of the {@linkplain
1693  *     java.text.DateFormatSymbols#getWeekdays day of the week},


1721  *     {@code 001} corresponds to the first day of the year.
1722  *
1723  * <tr><td style="vertical-align:top">{@code 'm'}
1724  *     <td style="vertical-align:top"> <code>'\u006d'</code>
1725  *     <td> Month, formatted as two digits with leading zeros as necessary,
1726  *     i.e. {@code 01 - 13}, where "{@code 01}" is the first month of the
1727  *     year and ("{@code 13}" is a special value required to support lunar
1728  *     calendars).
1729  *
1730  * <tr><td style="vertical-align:top">{@code 'd'}
1731  *     <td style="vertical-align:top"> <code>'\u0064'</code>
1732  *     <td> Day of month, formatted as two digits with leading zeros as
1733  *     necessary, i.e. {@code 01 - 31}, where "{@code 01}" is the first day
1734  *     of the month.
1735  *
1736  * <tr><td style="vertical-align:top">{@code 'e'}
1737  *     <td style="vertical-align:top"> <code>'\u0065'</code>
1738  *     <td> Day of month, formatted as two digits, i.e. {@code 1 - 31} where
1739  *     "{@code 1}" is the first day of the month.
1740  *
1741  * </tbody>
1742  * </table>
1743  *
1744  * <p> The following conversion characters are used for formatting common
1745  * date/time compositions.
1746  *
1747  * <table class="altrows">
1748  * <caption style="display:none">composites</caption>
1749  * <tbody>
1750  *
1751  * <tr><td style="vertical-align:top">{@code 'R'}
1752  *     <td style="vertical-align:top"> <code>'\u0052'</code>
1753  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM"}
1754  *
1755  * <tr><td style="vertical-align:top">{@code 'T'}
1756  *     <td style="vertical-align:top"> <code>'\u0054'</code>
1757  *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}.
1758  *
1759  * <tr><td style="vertical-align:top">{@code 'r'}
1760  *     <td style="vertical-align:top"> <code>'\u0072'</code>
1761  *     <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS
1762  *     %Tp"}.  The location of the morning or afternoon marker
1763  *     ({@code '%Tp'}) may be locale-dependent.
1764  *
1765  * <tr><td style="vertical-align:top">{@code 'D'}
1766  *     <td style="vertical-align:top"> <code>'\u0044'</code>
1767  *     <td> Date formatted as {@code "%tm/%td/%ty"}.
1768  *
1769  * <tr><td style="vertical-align:top">{@code 'F'}
1770  *     <td style="vertical-align:top"> <code>'\u0046'</code>
1771  *     <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO&nbsp;8601</a>
1772  *     complete date formatted as {@code "%tY-%tm-%td"}.
1773  *
1774  * <tr><td style="vertical-align:top">{@code 'c'}
1775  *     <td style="vertical-align:top"> <code>'\u0063'</code>
1776  *     <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
1777  *     e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
1778  *
1779  * </tbody>
1780  * </table>
1781  *
1782  * <p> The {@code '-'} flag defined for <a href="#dFlags">General
1783  * conversions</a> applies.  If the {@code '#'} flag is given, then a {@link
1784  * FormatFlagsConversionMismatchException} will be thrown.
1785  *
1786  * <p> The width is the minimum number of characters to
1787  * be written to the output.  If the length of the converted value is less than
1788  * the {@code width} then the output will be padded by spaces
1789  * (<code>'\u0020'</code>) until the total number of characters equals width.
1790  * The padding is on the left by default.  If the {@code '-'} flag is given
1791  * then the padding will be on the right.  If width is not specified then there
1792  * is no minimum.
1793  *
1794  * <p> The precision is not applicable.  If the precision is specified then an
1795  * {@link IllegalFormatPrecisionException} will be thrown.
1796  *
1797  * <h4><a id="dper">Percent</a></h4>
1798  *
1799  * <p> The conversion does not correspond to any argument.
1800  *
1801  * <table class="altrows">
1802  * <caption style="display:none">DTConv</caption>
1803  * <tbody>
1804  *
1805  * <tr><td style="vertical-align:top">{@code '%'}
1806  *     <td> The result is a literal {@code '%'} (<code>'\u0025'</code>)
1807  *
1808  * <p> The width is the minimum number of characters to
1809  * be written to the output including the {@code '%'}.  If the length of the
1810  * converted value is less than the {@code width} then the output will be
1811  * padded by spaces (<code>'\u0020'</code>) until the total number of
1812  * characters equals width.  The padding is on the left.  If width is not
1813  * specified then just the {@code '%'} is output.
1814  *
1815  * <p> The {@code '-'} flag defined for <a href="#dFlags">General
1816  * conversions</a> applies.  If any other flags are provided, then a
1817  * {@link FormatFlagsConversionMismatchException} will be thrown.
1818  *
1819  * <p> The precision is not applicable.  If the precision is specified an
1820  * {@link IllegalFormatPrecisionException} will be thrown.
1821  *
1822  * </tbody>
1823  * </table>
1824  *
1825  * <h4><a id="dls">Line Separator</a></h4>
1826  *
1827  * <p> The conversion does not correspond to any argument.
1828  *
1829  * <table class="altrows">
1830  * <caption style="display:none">DTConv</caption>
1831  * <tbody>
1832  *
1833  * <tr><td style="vertical-align:top">{@code 'n'}
1834  *     <td> the platform-specific line separator as returned by {@link
1835  *     System#lineSeparator()}.
1836  *
1837  * </tbody>
1838  * </table>
1839  *
1840  * <p> Flags, width, and precision are not applicable.  If any are provided an
1841  * {@link IllegalFormatFlagsException}, {@link IllegalFormatWidthException},
1842  * and {@link IllegalFormatPrecisionException}, respectively will be thrown.
1843  *
1844  * <h4><a id="dpos">Argument Index</a></h4>
1845  *
1846  * <p> Format specifiers can reference arguments in three ways:
1847  *
1848  * <ul>
1849  *
1850  * <li> <i>Explicit indexing</i> is used when the format specifier contains an
1851  * argument index.  The argument index is a decimal integer indicating the
1852  * position of the argument in the argument list.  The first argument is
1853  * referenced by "{@code 1$}", the second by "{@code 2$}", etc.  An argument
1854  * may be referenced more than once.
1855  *
1856  * <p> For example:
1857  *


< prev index next >