Formatted printing for the Java language is heavily inspired by C's - * printf. Although the format strings are similar to C, some + * {@code printf}. Although the format strings are similar to C, some * customizations have been made to accommodate the Java language and exploit * some of its features. Also, Java formatting is more strict than C's; for * example, if a conversion is incompatible with a flag, an exception will be @@ -115,7 +115,7 @@ * // -> "Unable to open file 'food': No such file or directory" * * - *
Like C's sprintf(3), Strings may be formatted using the static + *
Like C's {@code sprintf(3)}, Strings may be formatted using the static * method {@link String#format(String,Object...) String.format}: * *
@@ -157,16 +157,16 @@
* String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
* The optional argument_index is a decimal integer indicating the * position of the argument in the argument list. The first argument is - * referenced by "1$", the second by "2$", etc. + * referenced by "{@code 1$}", the second by "{@code 2$}", etc. * *
The optional flags is a set of characters that modify the output * format. The set of valid flags depends on the conversion. @@ -206,10 +206,10 @@ * defined as above. * *
The required conversion is a two character sequence. The first - * character is 't' or 'T'. The second character indicates + * character is {@code 't'} or {@code 'T'}. The second character indicates * the format to be used. These characters are similar to but not completely - * identical to those defined by GNU date and POSIX - * strftime(3c). + * identical to those defined by GNU {@code date} and POSIX + * {@code strftime(3c)}. * *
The following table summarizes the supported conversions. Conversions - * denoted by an upper-case character (i.e. 'B', 'H', - * 'S', 'C', 'X', 'E', 'G', - * 'A', and 'T') are the same as those for the corresponding + * 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 @@ -284,72 +284,72 @@ *
The following date and time conversion suffix characters are defined for - * the 't' and 'T' conversions. The types are similar to but - * not completely identical to those defined by GNU date and POSIX - * strftime(3c). Additional conversion types are provided to access - * Java-specific functionality (e.g. 'L' for milliseconds within the + * the {@code 't'} and {@code 'T'} conversions. The types are similar to but + * not completely identical to those defined by GNU {@code date} and POSIX + * {@code strftime(3c)}. Additional conversion types are provided to access + * Java-specific functionality (e.g. {@code 'L'} for milliseconds within the * second). * *
The following conversion characters are used for formatting times: @@ -371,68 +371,68 @@ * *
| 'H' + * | |
| {@code 'H'} * | Hour of the day for the 24-hour clock, formatted as two digits with - * a leading zero as necessary i.e. 00 - 23. + * a leading zero as necessary i.e. {@code 00 - 23}. * - * |
| 'I' + * | |
| {@code 'I'} * | Hour for the 12-hour clock, formatted as two digits with a leading - * zero as necessary, i.e. 01 - 12. + * zero as necessary, i.e. {@code 01 - 12}. * - * |
| 'k' - * | Hour of the day for the 24-hour clock, i.e. 0 - 23. + * |
| {@code 'k'} + * | Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}. * - * |
| 'l' - * | Hour for the 12-hour clock, i.e. 1 - 12. + * |
| {@code 'l'} + * | Hour for the 12-hour clock, i.e. {@code 1 - 12}. * - * |
| 'M' + * | |
| {@code 'M'} * | Minute within the hour formatted as two digits with a leading zero - * as necessary, i.e. 00 - 59. + * as necessary, i.e. {@code 00 - 59}. * - * |
| 'S' + * | |
| {@code 'S'} * | Seconds within the minute, formatted as two digits with a leading - * zero as necessary, i.e. 00 - 60 ("60" is a special + * zero as necessary, i.e. {@code 00 - 60} ("{@code 60}" is a special * value required to support leap seconds). * - * |
| 'L' + * | |
| {@code 'L'} * | Millisecond within the second formatted as three digits with - * leading zeros as necessary, i.e. 000 - 999. + * leading zeros as necessary, i.e. {@code 000 - 999}. * - * |
| 'N' + * | |
| {@code 'N'} * | Nanosecond within the second, formatted as nine digits with leading - * zeros as necessary, i.e. 000000000 - 999999999. + * zeros as necessary, i.e. {@code 000000000 - 999999999}. * - * |
| 'p' + * | |
| {@code 'p'} * | Locale-specific {@linkplain * java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} marker - * in lower case, e.g."am" or "pm". Use of the conversion - * prefix 'T' forces this output to upper case. + * in lower case, e.g."{@code am}" or "{@code pm}". Use of the conversion + * prefix {@code 'T'} forces this output to upper case. * - * |
| 'z' + * | |
| {@code 'z'} * | RFC 822 - * style numeric time zone offset from GMT, e.g. -0800. This + * style numeric time zone offset from GMT, e.g. {@code -0800}. This * value will be adjusted as necessary for Daylight Saving Time. For - * long, {@link Long}, and {@link Date} the time zone used is - * the {@plainlink TimeZone#getDefault() default time zone} for this + * {@code long}, {@link Long}, and {@link Date} the time zone used is + * the {@linkplain TimeZone#getDefault() default time zone} for this * instance of the Java virtual machine. * - * |
| 'Z' + * | |
| {@code 'Z'} * | A string representing the abbreviation for the time zone. This * value will be adjusted as necessary for Daylight Saving Time. For - * long, {@link Long}, and {@link Date} the time zone used is - * the {@plainlink TimeZone#getDefault() default time zone} for this + * {@code long}, {@link Long}, and {@link Date} the time zone used is + * the {@linkplain TimeZone#getDefault() default time zone} for this * instance of the Java virtual machine. The Formatter's locale will * supersede the locale of the argument (if any). * - * |
| 's' + * | |
| {@code 's'} * | Seconds since the beginning of the epoch starting at 1 January 1970 - * 00:00:00 UTC, i.e. Long.MIN_VALUE/1000 to - * Long.MAX_VALUE/1000. + * {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to + * {@code Long.MAX_VALUE/1000}. * - * |
| 'Q' + * | |
| {@code 'Q'} * | Milliseconds since the beginning of the epoch starting at 1 January - * 1970 00:00:00 UTC, i.e. Long.MIN_VALUE to - * Long.MAX_VALUE. + * 1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to + * {@code Long.MAX_VALUE}. * * |
| 'B' + * | |
| {@code 'B'} * | Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths - * full month name}, e.g. "January", "February". + * full month name}, e.g. {@code "January"}, {@code "February"}. * - * |
| 'b' + * | |
| {@code 'b'} * | Locale-specific {@linkplain * java.text.DateFormatSymbols#getShortMonths abbreviated month name}, - * e.g. "Jan", "Feb". + * e.g. {@code "Jan"}, {@code "Feb"}. * - * |
| 'h' - * | Same as 'b'. + * |
| {@code 'h'} + * | Same as {@code 'b'}. * - * |
| 'A' + * | |
| {@code 'A'} * | Locale-specific full name of the {@linkplain * java.text.DateFormatSymbols#getWeekdays day of the week}, - * e.g. "Sunday", "Monday" + * e.g. {@code "Sunday"}, {@code "Monday"} * - * |
| 'a' + * | |
| {@code 'a'} * | Locale-specific short name of the {@linkplain * java.text.DateFormatSymbols#getShortWeekdays day of the week}, - * e.g. "Sun", "Mon" + * e.g. {@code "Sun"}, {@code "Mon"} * - * |
| 'C' - * | Four-digit year divided by 100, formatted as two digits - * with leading zero as necessary, i.e. 00 - 99 + * |
| {@code 'C'} + * | Four-digit year divided by {@code 100}, formatted as two digits + * with leading zero as necessary, i.e. {@code 00 - 99} * - * |
| 'Y' + * | |
| {@code 'Y'} * | Year, formatted as at least four digits with leading zeros as - * necessary, e.g. 0092 equals 92 CE for the Gregorian + * necessary, e.g. {@code 0092} equals {@code 92} CE for the Gregorian * calendar. * - * |
| 'y' + * | |
| {@code 'y'} * | Last two digits of the year, formatted with leading zeros as - * necessary, i.e. 00 - 99. + * necessary, i.e. {@code 00 - 99}. * - * |
| 'j' + * | |
| {@code 'j'} * | Day of year, formatted as three digits with leading zeros as - * necessary, e.g. 001 - 366 for the Gregorian calendar. + * necessary, e.g. {@code 001 - 366} for the Gregorian calendar. * - * |
| 'm' + * | |
| {@code 'm'} * | Month, formatted as two digits with leading zeros as necessary, - * i.e. 01 - 13. + * i.e. {@code 01 - 13}. * - * |
| 'd' + * | |
| {@code 'd'} * | Day of month, formatted as two digits with leading zeros as - * necessary, i.e. 01 - 31 + * necessary, i.e. {@code 01 - 31} * - * |
| 'e' - * | Day of month, formatted as two digits, i.e. 1 - 31. + * |
| {@code 'e'} + * | Day of month, formatted as two digits, i.e. {@code 1 - 31}. * * |
| 'R' - * | Time formatted for the 24-hour clock as "%tH:%tM" + * |
| {@code 'R'} + * | Time formatted for the 24-hour clock as {@code "%tH:%tM"} * - * |
| 'T' - * | Time formatted for the 24-hour clock as "%tH:%tM:%tS". + * |
| {@code 'T'} + * | Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}. * - * |
| 'r' - * | Time formatted for the 12-hour clock as "%tI:%tM:%tS %Tp". - * The location of the morning or afternoon marker ('%Tp') may be + * |
| {@code 'r'} + * | 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. * - * |
| 'D' - * | Date formatted as "%tm/%td/%ty". + * |
| {@code 'D'} + * | Date formatted as {@code "%tm/%td/%ty"}. * - * |
| 'F' + * | |
| {@code 'F'} * | ISO 8601 - * complete date formatted as "%tY-%tm-%td". + * complete date formatted as {@code "%tY-%tm-%td"}. * - * |
| 'c' - * | Date and time formatted as "%ta %tb %td %tT %tZ %tY", - * e.g. "Sun Jul 20 16:17:00 EDT 1969". + * |
| {@code 'c'} + * | Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"}, + * e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}. * * |
1 Depends on the definition of {@link Formattable}. * - *
2 For 'd' conversion only. + *
2 For {@code 'd'} conversion only. * - *
3 For 'o', 'x', and 'X' + *
3 For {@code 'o'}, {@code 'x'}, and {@code 'X'} * conversions only. * - *
4 For 'd', 'o', 'x', and - * 'X' conversions applied to {@link java.math.BigInteger BigInteger} - * or 'd' applied to byte, {@link Byte}, short, {@link - * Short}, int and {@link Integer}, long, and {@link Long}. + *
4 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}. * - *
5 For 'e', 'E', 'f', - * 'g', and 'G' conversions only. + *
5 For {@code 'e'}, {@code 'E'}, {@code 'f'}, + * {@code 'g'}, and {@code 'G'} conversions only. * *
Any characters not explicitly defined as flags are illegal and are * reserved for future extensions. @@ -618,11 +618,11 @@ *
For general argument types, the precision is the maximum number of * characters to be written to the output. * - *
For the floating-point conversions 'e', 'E', and - * 'f' the precision is the number of digits after the decimal - * separator. If the conversion is 'g' or 'G', then the + *
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 'a' or 'A', then the + * rounding. If the conversion is {@code 'a'} or {@code 'A'}, then the * precision must not be specified. * *
For character, integral, and date/time argument types and the percent @@ -633,10 +633,10 @@ * *
The argument index is a decimal integer indicating the position of the * argument in the argument list. The first argument is referenced by - * "1$", the second by "2$", etc. + * "{@code 1$}", the second by "{@code 2$}", etc. * *
Another way to reference arguments by position is to use the - * '<' ('\u003c') flag, which causes the argument for + * {@code '<'} ('\u003c') flag, which causes the argument for * the previous format specifier to be re-used. For example, the following two * statements would produce identical strings: * @@ -670,14 +670,14 @@ * applicable to the corresponding argument, then an {@link * IllegalFormatConversionException} will be thrown. * - *
All specified exceptions may be thrown by any of the format - * methods of Formatter as well as by any format convenience + *
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}. * - *
Conversions denoted by an upper-case character (i.e. 'B', - * 'H', 'S', 'C', 'X', 'E', - * 'G', 'A', and 'T') are the same as those for the + *
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 @@ -692,56 +692,56 @@ * *
| 'b' + * | |||
| {@code 'b'} * | '\u0062' - * | Produces either "true" or "false" as returned by + * | Produces either "{@code true}" or "{@code false}" as returned by
* {@link Boolean#toString(boolean)}.
*
- * If the argument is null, then the result is - * "false". If the argument is a boolean or {@link + * 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 - * "true". + * "{@code true}". * - * If the '#' flag is given, then a {@link + * If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * - * |
| 'B' + * | |||
| {@code 'B'} * | '\u0042' - * | The upper-case variant of 'b'. + * | The upper-case variant of {@code 'b'}. * - * |
| 'h' + * | |||
| {@code 'h'} * | '\u0068' * | Produces a string representing the hash code value of the object.
*
- * If the argument, arg is null, then the - * result is "null". Otherwise, the result is obtained - * by invoking Integer.toHexString(arg.hashCode()). + * If the argument, arg is {@code null}, then the + * result is "{@code null}". Otherwise, the result is obtained + * by invoking {@code Integer.toHexString(arg.hashCode())}. * - * If the '#' flag is given, then a {@link + * If the {@code '#'} flag is given, then a {@link * FormatFlagsConversionMismatchException} will be thrown. * - * | |
| 'H' + * | |||
| {@code 'H'} * | '\u0048' - * | The upper-case variant of 'h'. + * | The upper-case variant of {@code 'h'}. * - * |
| 's' + * | |||
| {@code 's'} * | '\u0073' * | Produces a string.
*
- * If the argument is null, then the result is - * "null". If the argument implements {@link Formattable}, then + * 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 - * toString() method. + * {@code toString()} method. * - * If the '#' flag is given and the argument is not a {@link + * If the {@code '#'} flag is given and the argument is not a {@link * Formattable} , then a {@link FormatFlagsConversionMismatchException} * will be thrown. * - * | |
| 'S' + * | |||
| {@code 'S'} * | '\u0053' - * | The upper-case variant of 's'. + * | The upper-case variant of {@code 's'}. * * |