A control string is a Java string that contains a control specification. The control specification starts at the first percent sign (%) in the string, provided that this percent sign
A control specification usually takes the form:
% ['-+ #0]* [0..9]* { . [0..9]* }+ { [hlL] }+ [idfgGoxXeEcs] There are variants of this basic form that are discussed below. The format is composed of zero or more directives defined as follows:
The results are undefined if there are insufficient arguments for the format. Usually an unchecked exception will be thrown. If the format is exhausted while arguments remain, the excess arguments are evaluated but are otherwise ignored. In format strings containing the % form of conversion specifications, each argument in the argument list is used exactly once.
Conversions can be applied to the nth argument after the format in the argument list, rather than to the next unused argument. In this case, the conversion characer % is replaced by the sequence %n$, where n is a decimal integer giving the position of the argument in the argument list.
In format strings containing the %n$ form of conversion specifications, each argument in the argument list is used exactly once.
The following table lists escape sequences and associated actions on display devices capable of the action.
| Sequence | Name | Description |
|---|---|---|
| \\ | backlash | None. |
| \a | alert | Attempts to alert the user through audible or visible notification. |
| \b | backspace | Moves the printing position to one column before the current position, unless the current position is the start of a line. |
| \f | form-feed | Moves the printing position to the initial printing position of the next logical page. |
| \n | newline | Moves the printing position to the start of the next line. |
| \r | carriage-return | Moves the printing position to the start of the current line. |
| \t | tab | Moves the printing position to the next implementation- defined horizontal tab position. |
| \v | vertical-tab | Moves the printing position to the start of the next implementation-defined vertical tab position. |
Each conversion specification is introduced by the percent sign character (%). After the character %, the following appear in sequence:
Zero or more flags (in any order), which modify the meaning of the conversion specification.
An optional minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces by default on the left; t will be padded on the right, if the left- adjustment flag (-), described below, is given to the field width. The field width takes the form of a decimal integer. If the conversion character is s, the field width is the the minimum number of characters to be printed.
An optional precision that gives the minumum number of digits to appear for the d, i, o, x or X conversions (the field is padded with leading zeros); the number of digits to appear after the radix character for the e, E, and f conversions, the maximum number of significant digits for the g and G conversions; or the maximum number of characters to be written from a string is s and S conversions. The precision takes the form of an optional decimal digit string, where a null digit string is treated as 0. If a precision appears with a c conversion character the precision is ignored.
An optional h specifies that a following d, i, o, x, or X conversion character applies to a type short argument (the argument will be promoted according to the integral promotions and its value converted to type short before printing).
An optional l (ell) specifies that a following d, i, o, x, or X conversion character applies to a type long argument.
A field width or precision may be indicated by an asterisk (*) instead of a digit string. In this case, an integer argument supplised the field width precision. The argument that is actually converted is not fetched until the conversion letter is seen, so the the arguments specifying field width or precision must appear before the argument (if any) to be converted. If the precision argument is negative, it will be changed to zero. A negative field width argument is taken as a - flag, followed by a positive field width.
In format strings containing the %n$ form of a conversion specification, a field width or precision may be indicated by the sequence m$, where m is a decimal integer giving the position in the argument list (after the format argument) of an integer argument containing the field width or precision.
The format can contain either numbered argument specifications (that is, % n$ and *m$), or unnumbered argument specifications (that is % and *), but normally not both. The only exception to this is that %% can be mixed with the %n$ form. The results of mixing numbered and unnumbered argument specifications in a format string are undefined.
The flags and their meanings are:
Each conversion character results in fetching zero or more arguments. The results are undefined if there are insufficient arguments for the format. Usually, an unchecked exception will be thrown. If the format is exhausted while arguments remain, the excess arguments are ignored.
The conversion characters and their meanings are:
If a conversion specification does not match one of the above forms, an IllegalArgumentException is thrown and the instance of PrintfFormat is not created.
If a floating point value is the internal representation for infinity, the output is [+]Infinity, where Infinity is either Infinity or Inf, depending on the desired output string length. Printing of the sign follows the rules described above.
If a floating point value is the internal representation for "not-a-number," the output is [+]NaN. Printing of the sign follows the rules described above.
In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is simply expanded to contain the conversion result.
The behavior is like printf. One exception is that the minimum number of exponent digits is 3 instead of 2 for e and E formats when the optional L is used before the e, E, g, or G conversion character. The optional L does not imply conversion to a long long double.
The biggest divergence from the C printf specification is in the use of 16 bit characters. This allows the handling of characters beyond the small ASCII character set and allows the utility to interoperate correctly with the rest of the Java runtime environment.
Omissions from the C printf specification are numerous. All the known omissions are present because Java never uses bytes to represent characters and does not have pointers:
Most of this specification is quoted from the Unix man page for the sprintf utility.
@author Allan Jacobs @version 1 Release 1: Initial release. Release 2: Asterisk field widths andprecisions %n$ and *m$ Bug fixes g format fix (2 digits in e form corrupt) rounding in f format implemented round up when digit not printed is 5 formatting of -0.0f round up/down when last digits are 50000... | |
| |
| |
| |
| |
| |
| |
| |
| |
| |