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 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>' '</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>' '</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>' '</code> flags are given
994 * then an {@link IllegalFormatFlagsException} will be thrown.
995 *
996 * <tr><td style="vertical-align:top"> <code>' '</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>' '</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, 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 * <= <i>m</i> < 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 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 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>' '</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>' '</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>' '</code> flags are given
1022 * then an {@link IllegalFormatFlagsException} will be thrown.
1023 *
1024 * <tr><td style="vertical-align:top"> <code>' '</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>' '</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, 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 * <= <i>m</i> < 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 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 *
|