* * <tr><td valign="top">{@code 'T'} * <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}. * * <tr><td valign="top">{@code 'r'} * <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS %Tp"}. * The location of the morning or afternoon marker ({@code '%Tp'}) may be * locale-dependent. * * <tr><td valign="top">{@code 'D'} * <td> Date formatted as {@code "%tm/%td/%ty"}. * * <tr><td valign="top">{@code 'F'} * <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a> * complete date formatted as {@code "%tY-%tm-%td"}. * * <tr><td valign="top">{@code 'c'} * <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"}, * e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}. * * </table> * * <p> Any characters not explicitly defined as date/time conversion suffixes * are illegal and are reserved for future extensions. * * <h4> Flags </h4> * * <p> The following table summarizes the supported flags. <i>y</i> means the * flag is supported for the indicated argument types. * * <table cellpadding=5 summary="genConv"> * * <tr><th valign="bottom"> Flag <th valign="bottom"> General * <th valign="bottom"> Character <th valign="bottom"> Integral * <th valign="bottom"> Floating Point * <th valign="bottom"> Date/Time * <th valign="bottom"> Description * * <tr><td> '-' <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td> The result will be left-justified. * * <tr><td> '#' <td align="center" valign="top"> y<sup>1</sup> * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>3</sup> * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result should use a conversion-dependent alternate form * * <tr><td> '+' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>4</sup> * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result will always include a sign * * <tr><td> ' ' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>4</sup> * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result will include a leading space for positive values * * <tr><td> '0' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result will be zero-padded * * <tr><td> ',' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>2</sup> * <td align="center" valign="top"> y<sup>5</sup> * <td align="center" valign="top"> - * <td> The result will include locale-specific {@linkplain * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separators} * * <tr><td> '(' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>4</sup> * <td align="center" valign="top"> y<sup>5</sup> * <td align="center"> - * <td> The result will enclose negative numbers in parentheses * * </table> * * <p> <sup>1</sup> Depends on the definition of {@link Formattable}. * * <p> <sup>2</sup> For {@code 'd'} conversion only. * * <p> <sup>3</sup> For {@code 'o'}, {@code 'x'}, and {@code 'X'} * conversions only. * * <p> <sup>4</sup> For {@code 'd'}, {@code 'o'}, {@code 'x'}, and * {@code 'X'} conversions applied to {@link java.math.BigInteger BigInteger} * or {@code 'd'} applied to {@code byte}, {@link Byte}, {@code short}, {@link * Short}, {@code int} and {@link Integer}, {@code long}, and {@link Long}. * * <p> <sup>5</sup> For {@code 'e'}, {@code 'E'}, {@code 'f'}, * {@code 'g'}, and {@code 'G'} conversions only. * * <p> Any characters not explicitly defined as flags are illegal and are * reserved for future extensions. * * <h4> Width </h4> * * <p> The width is the minimum number of characters to be written to the * output. For the line separator conversion, width is not applicable; if it * is provided, an exception will be thrown. * * <h4> Precision </h4> * * <p> For general argument types, the precision is the maximum number of * characters to be written to the output. * * <p> For the floating-point conversions {@code 'e'}, {@code 'E'}, and * {@code 'f'} the precision is the number of digits after the decimal * separator. If the conversion is {@code 'g'} or {@code 'G'}, then the * precision is the total number of digits in the resulting magnitude after * rounding. If the conversion is {@code 'a'} or {@code 'A'}, then the * precision must not be specified. * * <p> For character, integral, and date/time argument types and the percent * and line separator conversions, the precision is not applicable; if a * precision is provided, an exception will be thrown. * * <h4> Argument Index </h4> * * <p> The argument index is a decimal integer indicating the position of the * argument in the argument list. The first argument is referenced by * "{@code 1$}", the second by "{@code 2$}", etc. * * <p> Another way to reference arguments by position is to use the * {@code '<'} (<tt>'\u003c'</tt>) flag, which causes the argument for * the previous format specifier to be re-used. For example, the following two * statements would produce identical strings: * * <blockquote><pre> * Calendar c = ...; * String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); * * String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c); * </pre></blockquote> * * <hr> * <h3><a name="detail">Details</a></h3> * * <p> This section is intended to provide behavioral details for formatting, * including conditions and exceptions, supported data types, localization, and * interactions between flags, conversions, and data types. For an overview of * formatting concepts, refer to the <a href="#summary">Summary</a> * * <p> Any characters not explicitly defined as conversions, date/time * conversion suffixes, or flags are illegal and are reserved for * future extensions. Use of such a character in a format string will * cause an {@link UnknownFormatConversionException} or {@link * UnknownFormatFlagsException} to be thrown. * * <p> If the format specifier contains a width or precision with an invalid * value or which is otherwise unsupported, then a {@link * IllegalFormatWidthException} or {@link IllegalFormatPrecisionException} * respectively will be thrown. * * <p> If a format specifier contains a conversion character that is not * applicable to the corresponding argument, then an {@link * IllegalFormatConversionException} will be thrown. * * <p> All specified exceptions may be thrown by any of the {@code format} * methods of {@code Formatter} as well as by any {@code format} convenience * methods such as {@link String#format(String,Object...) String.format} and * {@link java.io.PrintStream#printf(String,Object...) PrintStream.printf}. * * <p> Conversions denoted by an upper-case character (i.e. {@code 'B'}, * {@code 'H'}, {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, * {@code 'G'}, {@code 'A'}, and {@code 'T'}) are the same as those for the * corresponding lower-case conversion characters except that the result is * converted to upper case according to the rules of the prevailing {@link * java.util.Locale Locale}. The result is equivalent to the following * invocation of {@link String#toUpperCase()} * * <pre> * out.toUpperCase() </pre> * * <h4><a name="dgen">General</a></h4> * * <p> The following general conversions may be applied to any argument type: * * <table cellpadding=5 summary="dgConv"> * * <tr><td valign="top"> {@code 'b'} * <td valign="top"> <tt>'\u0062'</tt> * <td> Produces either "{@code true}" or "{@code false}" as returned by * {@link Boolean#toString(boolean)}. * * <p> If the argument is {@code null}, then the result is * "{@code false}". If the argument is a {@code boolean} or {@link * Boolean}, then the result is the string returned by {@link * String#valueOf(boolean) String.valueOf()}. Otherwise, the result is * "{@code true}". * * <p> If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'B'} * <td valign="top"> <tt>'\u0042'</tt> * <td> The upper-case variant of {@code 'b'}. * * <tr><td valign="top"> {@code 'h'} * <td valign="top"> <tt>'\u0068'</tt> * <td> Produces a string representing the hash code value of the object. * * <p> If the argument, <i>arg</i> is {@code null}, then the * result is "{@code null}". Otherwise, the result is obtained * by invoking {@code Integer.toHexString(arg.hashCode())}. * * <p> If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'H'} * <td valign="top"> <tt>'\u0048'</tt> * <td> The upper-case variant of {@code 'h'}. * * <tr><td valign="top"> {@code 's'} * <td valign="top"> <tt>'\u0073'</tt> * <td> Produces a string. * * <p> If the argument is {@code null}, then the result is * "{@code null}". If the argument implements {@link Formattable}, then * its {@link Formattable#formatTo formatTo} method is invoked. * Otherwise, the result is obtained by invoking the argument's * {@code toString()} method. * * <p> If the {@code '#'} flag is given and the argument is not a {@link * Formattable} , then a {@link FormatFlagsConversionMismatchException} * will be thrown. * * <tr><td valign="top"> {@code 'S'} * <td valign="top"> <tt>'\u0053'</tt> * <td> The upper-case variant of {@code 's'}. * * </table> * * <p> The following <a name="dFlags">flags</a> apply to general conversions: * * <table cellpadding=5 summary="dFlags"> * * <tr><td valign="top"> {@code '-'} * <td valign="top"> <tt>'\u002d'</tt> * <td> Left justifies the output. Spaces (<tt>'\u0020'</tt>) will be * added at the end of the converted value as required to fill the minimum * width of the field. If the width is not provided, then a {@link * MissingFormatWidthException} will be thrown. If this flag is not given * then the output will be right-justified. * * <tr><td valign="top"> {@code '#'} * <td valign="top"> <tt>'\u0023'</tt> * <td> Requires the output use an alternate form. The definition of the * form is specified by the conversion. * * </table> * * <p> The <a name="genWidth">width</a> is the minimum number of characters to * be written to the * output. If the length of the converted value is less than the width then * the output will be padded by <tt>' '</tt> (<tt>'\u0020'</tt>) * until the total number of characters equals the width. The padding is on * the left by default. If the {@code '-'} flag is given, then the padding * will be on the right. If the width is not specified then there is no * minimum. * * <p> The precision is the maximum number of characters to be written to the * output. The precision is applied before the width, thus the output will be * truncated to {@code precision} characters even if the width is greater than * the precision. If the precision is not specified then there is no explicit * limit on the number of characters. * * <h4><a name="dchar">Character</a></h4> * * This conversion may be applied to {@code char} and {@link Character}. It * may also be applied to the types {@code byte}, {@link Byte}, * {@code short}, and {@link Short}, {@code int} and {@link Integer} when * {@link Character#isValidCodePoint} returns {@code true}. If it returns * {@code false} then an {@link IllegalFormatCodePointException} will be * thrown. * * <table cellpadding=5 summary="charConv"> * * <tr><td valign="top"> {@code 'c'} * <td valign="top"> <tt>'\u0063'</tt> * <td> Formats the argument as a Unicode character as described in <a * href="../lang/Character.html#unicode">Unicode Character * Representation</a>. This may be more than one 16-bit {@code char} in * the case where the argument represents a supplementary character. * * <p> If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'C'} * <td valign="top"> <tt>'\u0043'</tt> * <td> The upper-case variant of {@code 'c'}. * * </table> * * <p> The {@code '-'} flag defined for <a href="#dFlags">General * conversions</a> applies. If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <p> The width is defined as for <a href="#genWidth">General conversions</a>. * * <p> The precision is not applicable. If the precision is specified then an * {@link IllegalFormatPrecisionException} will be thrown. * * <h4><a name="dnum">Numeric</a></h4> * * <p> Numeric conversions are divided into the following categories: * * <ol> * * <li> <a href="#dnint"><b>Byte, Short, Integer, and Long</b></a> * * <li> <a href="#dnbint"><b>BigInteger</b></a> * * <li> <a href="#dndec"><b>Float and Double</b></a> * * <li> <a href="#dnbdec"><b>BigDecimal</b></a> * * </ol> * * <p> Numeric types will be formatted according to the following algorithm: * * <p><b><a name="l10n algorithm"> Number Localization Algorithm</a></b> * * <p> After digits are obtained for the integer part, fractional part, and * exponent (as appropriate for the data type), the following transformation * is applied: * * <ol> * * <li> Each digit character <i>d</i> in the string is replaced by a * locale-specific digit computed relative to the current locale's * {@linkplain java.text.DecimalFormatSymbols#getZeroDigit() zero digit} * <i>z</i>; that is <i>d - </i> {@code '0'} * <i> + z</i>. * * <li> If a decimal separator is present, a locale-specific {@linkplain * java.text.DecimalFormatSymbols#getDecimalSeparator decimal separator} is * substituted. * * <li> If the {@code ','} (<tt>'\u002c'</tt>) * <a name="l10n group">flag</a> is given, then the locale-specific {@linkplain * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separator} is * inserted by scanning the integer part of the string from least significant * to most significant digits and inserting a separator at intervals defined by * the locale's {@linkplain java.text.DecimalFormat#getGroupingSize() grouping * size}. * * <li> If the {@code '0'} flag is given, then the locale-specific {@linkplain * java.text.DecimalFormatSymbols#getZeroDigit() zero digits} are inserted * after the sign character, if any, and before the first non-zero digit, until * the length of the string is equal to the requested field width. * * <li> If the value is negative and the {@code '('} flag is given, then a * {@code '('} (<tt>'\u0028'</tt>) is prepended and a {@code ')'} * (<tt>'\u0029'</tt>) is appended. * * <li> If the value is negative (or floating-point negative zero) and * {@code '('} flag is not given, then a {@code '-'} (<tt>'\u002d'</tt>) * is prepended. * * <li> If the {@code '+'} flag is given and the value is positive or zero (or * floating-point positive zero), then a {@code '+'} (<tt>'\u002b'</tt>) * will be prepended. * * </ol> * * <p> If the value is NaN or positive infinity the literal strings "NaN" or * "Infinity" respectively, will be output. If the value is negative infinity, * then the output will be "(Infinity)" if the {@code '('} flag is given * otherwise the output will be "-Infinity". These values are not localized. * * <p><a name="dnint"><b> Byte, Short, Integer, and Long </b></a> * * <p> The following conversions may be applied to {@code byte}, {@link Byte}, * {@code short}, {@link Short}, {@code int} and {@link Integer}, * {@code long}, and {@link Long}. * * <table cellpadding=5 summary="IntConv"> * * <tr><td valign="top"> {@code 'd'} * <td valign="top"> <tt>'\u0054'</tt> * <td> Formats the argument as a decimal integer. The <a * href="#l10n algorithm">localization algorithm</a> is applied. * * <p> If the {@code '0'} flag is given and the value is negative, then * the zero padding will occur after the sign. * * <p> If the {@code '#'} flag is given then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'o'} * <td valign="top"> <tt>'\u006f'</tt> * <td> Formats the argument as an integer in base eight. No localization * is applied. * * <p> If <i>x</i> is negative then the result will be an unsigned value * generated by adding 2<sup>n</sup> to the value where {@code n} is the * number of bits in the type as returned by the static {@code SIZE} field * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long} * classes as appropriate. * * <p> If the {@code '#'} flag is given then the output will always begin * with the radix indicator {@code '0'}. * * <p> If the {@code '0'} flag is given then the output will be padded * with leading zeros to the field width following any indication of sign. * * <p> If {@code '('}, {@code '+'}, '  ', or {@code ','} flags * are given then a {@link FormatFlagsConversionMismatchException} will be * thrown. * * <tr><td valign="top"> {@code 'x'} * <td valign="top"> <tt>'\u0078'</tt> * <td> Formats the argument as an integer in base sixteen. No * localization is applied. * * <p> If <i>x</i> is negative then the result will be an unsigned value * generated by adding 2<sup>n</sup> to the value where {@code n} is the * number of bits in the type as returned by the static {@code SIZE} field * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long} * classes as appropriate. * * <p> If the {@code '#'} flag is given then the output will always begin * with the radix indicator {@code "0x"}. * * <p> If the {@code '0'} flag is given then the output will be padded to * the field width with leading zeros after the radix indicator or sign (if * present). * * <p> If {@code '('}, <tt>' '</tt>, {@code '+'}, or * {@code ','} flags are given then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'X'} * <td valign="top"> <tt>'\u0058'</tt> * <td> The upper-case variant of {@code 'x'}. The entire string * representing the number will be converted to {@linkplain * String#toUpperCase upper case} including the {@code 'x'} (if any) and * all hexadecimal digits {@code 'a'} - {@code 'f'} * (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>). * * </table> * * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and * both the {@code '#'} and the {@code '0'} flags are given, then result will * contain the radix indicator ({@code '0'} for octal and {@code "0x"} or * {@code "0X"} for hexadecimal), some number of zeros (based on the width), * and the value. * * <p> If the {@code '-'} flag is not given, then the space padding will occur * before the sign. * * <p> The following <a name="intFlags">flags</a> apply to numeric integral * conversions: * * <table cellpadding=5 summary="intFlags"> * * <tr><td valign="top"> {@code '+'} * <td valign="top"> <tt>'\u002b'</tt> * <td> Requires the output to include a positive sign for all positive * numbers. If this flag is not given then only negative values will * include a sign. * * <p> If both the {@code '+'} and <tt>' '</tt> flags are given * then an {@link IllegalFormatFlagsException} will be thrown. * * <tr><td valign="top"> <tt>' '</tt> * <td valign="top"> <tt>'\u0020'</tt> * <td> Requires the output to include a single extra space * (<tt>'\u0020'</tt>) for non-negative values. * * <p> If both the {@code '+'} and <tt>' '</tt> flags are given * then an {@link IllegalFormatFlagsException} will be thrown. * * <tr><td valign="top"> {@code '0'} * <td valign="top"> <tt>'\u0030'</tt> * <td> Requires the output to be padded with leading {@linkplain * java.text.DecimalFormatSymbols#getZeroDigit zeros} to the minimum field * width following any sign or radix indicator except when converting NaN * or infinity. If the width is not provided, then a {@link * MissingFormatWidthException} will be thrown. * * <p> If both the {@code '-'} and {@code '0'} flags are given then an * {@link IllegalFormatFlagsException} will be thrown. *Lines 501–1000 of 4441. Previous lines Load more
* * <tr><td valign="top">{@code 'T'} * <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}. * * <tr><td valign="top">{@code 'r'} * <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS %Tp"}. * The location of the morning or afternoon marker ({@code '%Tp'}) may be * locale-dependent. * * <tr><td valign="top">{@code 'D'} * <td> Date formatted as {@code "%tm/%td/%ty"}. * * <tr><td valign="top">{@code 'F'} * <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a> * complete date formatted as {@code "%tY-%tm-%td"}. * * <tr><td valign="top">{@code 'c'} * <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"}, * e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}. * * </table> * * <p> Any characters not explicitly defined as date/time conversion suffixes * are illegal and are reserved for future extensions. * * <h4> Flags </h4> * * <p> The following table summarizes the supported flags. <i>y</i> means the * flag is supported for the indicated argument types. * * <table cellpadding=5 summary="genConv"> * * <tr><th valign="bottom"> Flag <th valign="bottom"> General * <th valign="bottom"> Character <th valign="bottom"> Integral * <th valign="bottom"> Floating Point * <th valign="bottom"> Date/Time * <th valign="bottom"> Description * * <tr><td> '-' <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td> The result will be left-justified. * * <tr><td> '#' <td align="center" valign="top"> y<sup>1</sup> * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>3</sup> * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result should use a conversion-dependent alternate form * * <tr><td> '+' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>4</sup> * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result will always include a sign * * <tr><td> ' ' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>4</sup> * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result will include a leading space for positive values * * <tr><td> '0' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y * <td align="center" valign="top"> y * <td align="center" valign="top"> - * <td> The result will be zero-padded * * <tr><td> ',' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>2</sup> * <td align="center" valign="top"> y<sup>5</sup> * <td align="center" valign="top"> - * <td> The result will include locale-specific {@linkplain * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separators} * * <tr><td> '(' <td align="center" valign="top"> - * <td align="center" valign="top"> - * <td align="center" valign="top"> y<sup>4</sup> * <td align="center" valign="top"> y<sup>5</sup> * <td align="center"> - * <td> The result will enclose negative numbers in parentheses * * </table> * * <p> <sup>1</sup> Depends on the definition of {@link Formattable}. * * <p> <sup>2</sup> For {@code 'd'} conversion only. * * <p> <sup>3</sup> For {@code 'o'}, {@code 'x'}, and {@code 'X'} * conversions only. * * <p> <sup>4</sup> For {@code 'd'}, {@code 'o'}, {@code 'x'}, and * {@code 'X'} conversions applied to {@link java.math.BigInteger BigInteger} * or {@code 'd'} applied to {@code byte}, {@link Byte}, {@code short}, {@link * Short}, {@code int} and {@link Integer}, {@code long}, and {@link Long}. * * <p> <sup>5</sup> For {@code 'e'}, {@code 'E'}, {@code 'f'}, * {@code 'g'}, and {@code 'G'} conversions only. * * <p> Any characters not explicitly defined as flags are illegal and are * reserved for future extensions. * * <h4> Width </h4> * * <p> The width is the minimum number of characters to be written to the * output. For the line separator conversion, width is not applicable; if it * is provided, an exception will be thrown. * * <h4> Precision </h4> * * <p> For general argument types, the precision is the maximum number of * characters to be written to the output. * * <p> For the floating-point conversions {@code 'e'}, {@code 'E'}, and * {@code 'f'} the precision is the number of digits after the decimal * separator. If the conversion is {@code 'g'} or {@code 'G'}, then the * precision is the total number of digits in the resulting magnitude after * rounding. If the conversion is {@code 'a'} or {@code 'A'}, then the * precision must not be specified. * * <p> For character, integral, and date/time argument types and the percent * and line separator conversions, the precision is not applicable; if a * precision is provided, an exception will be thrown. * * <h4> Argument Index </h4> * * <p> The argument index is a decimal integer indicating the position of the * argument in the argument list. The first argument is referenced by * "{@code 1$}", the second by "{@code 2$}", etc. * * <p> Another way to reference arguments by position is to use the * {@code '<'} (<tt>'\u003c'</tt>) flag, which causes the argument for * the previous format specifier to be re-used. For example, the following two * statements would produce identical strings: * * <blockquote><pre> * Calendar c = ...; * String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); * * String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c); * </pre></blockquote> * * <hr> * <h3><a name="detail">Details</a></h3> * * <p> This section is intended to provide behavioral details for formatting, * including conditions and exceptions, supported data types, localization, and * interactions between flags, conversions, and data types. For an overview of * formatting concepts, refer to the <a href="#summary">Summary</a> * * <p> Any characters not explicitly defined as conversions, date/time * conversion suffixes, or flags are illegal and are reserved for * future extensions. Use of such a character in a format string will * cause an {@link UnknownFormatConversionException} or {@link * UnknownFormatFlagsException} to be thrown. * * <p> If the format specifier contains a width or precision with an invalid * value or which is otherwise unsupported, then a {@link * IllegalFormatWidthException} or {@link IllegalFormatPrecisionException} * respectively will be thrown. * * <p> If a format specifier contains a conversion character that is not * applicable to the corresponding argument, then an {@link * IllegalFormatConversionException} will be thrown. * * <p> All specified exceptions may be thrown by any of the {@code format} * methods of {@code Formatter} as well as by any {@code format} convenience * methods such as {@link String#format(String,Object...) String.format} and * {@link java.io.PrintStream#printf(String,Object...) PrintStream.printf}. * * <p> Conversions denoted by an upper-case character (i.e. {@code 'B'}, * {@code 'H'}, {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, * {@code 'G'}, {@code 'A'}, and {@code 'T'}) are the same as those for the * corresponding lower-case conversion characters except that the result is * converted to upper case according to the rules of the prevailing {@link * java.util.Locale Locale}. The result is equivalent to the following * invocation of {@link String#toUpperCase()} * * <pre> * out.toUpperCase() </pre> * * <h4><a name="dgen">General</a></h4> * * <p> The following general conversions may be applied to any argument type: * * <table cellpadding=5 summary="dgConv"> * * <tr><td valign="top"> {@code 'b'} * <td valign="top"> <tt>'\u0062'</tt> * <td> Produces either "{@code true}" or "{@code false}" as returned by * {@link Boolean#toString(boolean)}. * * <p> If the argument is {@code null}, then the result is * "{@code false}". If the argument is a {@code boolean} or {@link * Boolean}, then the result is the string returned by {@link * String#valueOf(boolean) String.valueOf()}. Otherwise, the result is * "{@code true}". * * <p> If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'B'} * <td valign="top"> <tt>'\u0042'</tt> * <td> The upper-case variant of {@code 'b'}. * * <tr><td valign="top"> {@code 'h'} * <td valign="top"> <tt>'\u0068'</tt> * <td> Produces a string representing the hash code value of the object. * * <p> If the argument, <i>arg</i> is {@code null}, then the * result is "{@code null}". Otherwise, the result is obtained * by invoking {@code Integer.toHexString(arg.hashCode())}. * * <p> If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'H'} * <td valign="top"> <tt>'\u0048'</tt> * <td> The upper-case variant of {@code 'h'}. * * <tr><td valign="top"> {@code 's'} * <td valign="top"> <tt>'\u0073'</tt> * <td> Produces a string. * * <p> If the argument is {@code null}, then the result is * "{@code null}". If the argument implements {@link Formattable}, then * its {@link Formattable#formatTo formatTo} method is invoked. * Otherwise, the result is obtained by invoking the argument's * {@code toString()} method. * * <p> If the {@code '#'} flag is given and the argument is not a {@link * Formattable} , then a {@link FormatFlagsConversionMismatchException} * will be thrown. * * <tr><td valign="top"> {@code 'S'} * <td valign="top"> <tt>'\u0053'</tt> * <td> The upper-case variant of {@code 's'}. * * </table> * * <p> The following <a name="dFlags">flags</a> apply to general conversions: * * <table cellpadding=5 summary="dFlags"> * * <tr><td valign="top"> {@code '-'} * <td valign="top"> <tt>'\u002d'</tt> * <td> Left justifies the output. Spaces (<tt>'\u0020'</tt>) will be * added at the end of the converted value as required to fill the minimum * width of the field. If the width is not provided, then a {@link * MissingFormatWidthException} will be thrown. If this flag is not given * then the output will be right-justified. * * <tr><td valign="top"> {@code '#'} * <td valign="top"> <tt>'\u0023'</tt> * <td> Requires the output use an alternate form. The definition of the * form is specified by the conversion. * * </table> * * <p> The <a name="genWidth">width</a> is the minimum number of characters to * be written to the * output. If the length of the converted value is less than the width then * the output will be padded by <tt>' '</tt> (<tt>'\u0020'</tt>) * until the total number of characters equals the width. The padding is on * the left by default. If the {@code '-'} flag is given, then the padding * will be on the right. If the width is not specified then there is no * minimum. * * <p> The precision is the maximum number of characters to be written to the * output. The precision is applied before the width, thus the output will be * truncated to {@code precision} characters even if the width is greater than * the precision. If the precision is not specified then there is no explicit * limit on the number of characters. * * <h4><a name="dchar">Character</a></h4> * * This conversion may be applied to {@code char} and {@link Character}. It * may also be applied to the types {@code byte}, {@link Byte}, * {@code short}, and {@link Short}, {@code int} and {@link Integer} when * {@link Character#isValidCodePoint} returns {@code true}. If it returns * {@code false} then an {@link IllegalFormatCodePointException} will be * thrown. * * <table cellpadding=5 summary="charConv"> * * <tr><td valign="top"> {@code 'c'} * <td valign="top"> <tt>'\u0063'</tt> * <td> Formats the argument as a Unicode character as described in <a * href="../lang/Character.html#unicode">Unicode Character * Representation</a>. This may be more than one 16-bit {@code char} in * the case where the argument represents a supplementary character. * * <p> If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'C'} * <td valign="top"> <tt>'\u0043'</tt> * <td> The upper-case variant of {@code 'c'}. * * </table> * * <p> The {@code '-'} flag defined for <a href="#dFlags">General * conversions</a> applies. If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <p> The width is defined as for <a href="#genWidth">General conversions</a>. * * <p> The precision is not applicable. If the precision is specified then an * {@link IllegalFormatPrecisionException} will be thrown. * * <h4><a name="dnum">Numeric</a></h4> * * <p> Numeric conversions are divided into the following categories: * * <ol> * * <li> <a href="#dnint"><b>Byte, Short, Integer, and Long</b></a> * * <li> <a href="#dnbint"><b>BigInteger</b></a> * * <li> <a href="#dndec"><b>Float and Double</b></a> * * <li> <a href="#dnbdec"><b>BigDecimal</b></a> * * </ol> * * <p> Numeric types will be formatted according to the following algorithm: * * <p><b><a name="l10n algorithm"> Number Localization Algorithm</a></b> * * <p> After digits are obtained for the integer part, fractional part, and * exponent (as appropriate for the data type), the following transformation * is applied: * * <ol> * * <li> Each digit character <i>d</i> in the string is replaced by a * locale-specific digit computed relative to the current locale's * {@linkplain java.text.DecimalFormatSymbols#getZeroDigit() zero digit} * <i>z</i>; that is <i>d - </i> {@code '0'} * <i> + z</i>. * * <li> If a decimal separator is present, a locale-specific {@linkplain * java.text.DecimalFormatSymbols#getDecimalSeparator decimal separator} is * substituted. * * <li> If the {@code ','} (<tt>'\u002c'</tt>) * <a name="l10n group">flag</a> is given, then the locale-specific {@linkplain * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separator} is * inserted by scanning the integer part of the string from least significant * to most significant digits and inserting a separator at intervals defined by * the locale's {@linkplain java.text.DecimalFormat#getGroupingSize() grouping * size}. * * <li> If the {@code '0'} flag is given, then the locale-specific {@linkplain * java.text.DecimalFormatSymbols#getZeroDigit() zero digits} are inserted * after the sign character, if any, and before the first non-zero digit, until * the length of the string is equal to the requested field width. * * <li> If the value is negative and the {@code '('} flag is given, then a * {@code '('} (<tt>'\u0028'</tt>) is prepended and a {@code ')'} * (<tt>'\u0029'</tt>) is appended. * * <li> If the value is negative (or floating-point negative zero) and * {@code '('} flag is not given, then a {@code '-'} (<tt>'\u002d'</tt>) * is prepended. * * <li> If the {@code '+'} flag is given and the value is positive or zero (or * floating-point positive zero), then a {@code '+'} (<tt>'\u002b'</tt>) * will be prepended. * * </ol> * * <p> If the value is NaN or positive infinity the literal strings "NaN" or * "Infinity" respectively, will be output. If the value is negative infinity, * then the output will be "(Infinity)" if the {@code '('} flag is given * otherwise the output will be "-Infinity". These values are not localized. * * <p><a name="dnint"><b> Byte, Short, Integer, and Long </b></a> * * <p> The following conversions may be applied to {@code byte}, {@link Byte}, * {@code short}, {@link Short}, {@code int} and {@link Integer}, * {@code long}, and {@link Long}. * * <table cellpadding=5 summary="IntConv"> * * <tr><td valign="top"> {@code 'd'} * <td valign="top"> <tt>'\u0054'</tt> * <td> Formats the argument as a decimal integer. The <a * href="#l10n algorithm">localization algorithm</a> is applied. * * <p> If the {@code '0'} flag is given and the value is negative, then * the zero padding will occur after the sign. * * <p> If the {@code '#'} flag is given then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'o'} * <td valign="top"> <tt>'\u006f'</tt> * <td> Formats the argument as an integer in base eight. No localization * is applied. * * <p> If <i>x</i> is negative then the result will be an unsigned value * generated by adding 2<sup>n</sup> to the value where {@code n} is the * number of bits in the type as returned by the static {@code SIZE} field * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long} * classes as appropriate. * * <p> If the {@code '#'} flag is given then the output will always begin * with the radix indicator {@code '0'}. * * <p> If the {@code '0'} flag is given then the output will be padded * with leading zeros to the field width following any indication of sign. * * <p> If {@code '('}, {@code '+'}, '  ', or {@code ','} flags * are given then a {@link FormatFlagsConversionMismatchException} will be * thrown. * * <tr><td valign="top"> {@code 'x'} * <td valign="top"> <tt>'\u0078'</tt> * <td> Formats the argument as an integer in base sixteen. No * localization is applied. * * <p> If <i>x</i> is negative then the result will be an unsigned value * generated by adding 2<sup>n</sup> to the value where {@code n} is the * number of bits in the type as returned by the static {@code SIZE} field * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long} * classes as appropriate. * * <p> If the {@code '#'} flag is given then the output will always begin * with the radix indicator {@code "0x"}. * * <p> If the {@code '0'} flag is given then the output will be padded to * the field width with leading zeros after the radix indicator or sign (if * present). * * <p> If {@code '('}, <tt>' '</tt>, {@code '+'}, or * {@code ','} flags are given then a {@link * FormatFlagsConversionMismatchException} will be thrown. * * <tr><td valign="top"> {@code 'X'} * <td valign="top"> <tt>'\u0058'</tt> * <td> The upper-case variant of {@code 'x'}. The entire string * representing the number will be converted to {@linkplain * String#toUpperCase upper case} including the {@code 'x'} (if any) and * all hexadecimal digits {@code 'a'} - {@code 'f'} * (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>). * * </table> * * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and * both the {@code '#'} and the {@code '0'} flags are given, then result will * contain the radix indicator ({@code '0'} for octal and {@code "0x"} or * {@code "0X"} for hexadecimal), some number of zeros (based on the width), * and the value. * * <p> If the {@code '-'} flag is not given, then the space padding will occur * before the sign. * * <p> The following <a name="intFlags">flags</a> apply to numeric integral * conversions: * * <table cellpadding=5 summary="intFlags"> * * <tr><td valign="top"> {@code '+'} * <td valign="top"> <tt>'\u002b'</tt> * <td> Requires the output to include a positive sign for all positive * numbers. If this flag is not given then only negative values will * include a sign. * * <p> If both the {@code '+'} and <tt>' '</tt> flags are given * then an {@link IllegalFormatFlagsException} will be thrown. * * <tr><td valign="top"> <tt>' '</tt> * <td valign="top"> <tt>'\u0020'</tt> * <td> Requires the output to include a single extra space * (<tt>'\u0020'</tt>) for non-negative values. * * <p> If both the {@code '+'} and <tt>' '</tt> flags are given * then an {@link IllegalFormatFlagsException} will be thrown. * * <tr><td valign="top"> {@code '0'} * <td valign="top"> <tt>'\u0030'</tt> * <td> Requires the output to be padded with leading {@linkplain * java.text.DecimalFormatSymbols#getZeroDigit zeros} to the minimum field * width following any sign or radix indicator except when converting NaN * or infinity. If the width is not provided, then a {@link * MissingFormatWidthException} will be thrown. * * <p> If both the {@code '-'} and {@code '0'} flags are given then an * {@link IllegalFormatFlagsException} will be thrown. *