Java String Formatting

Formatting a string, allows other characters, sub-strings or numeric values, to be inserted into a main string, in a particular way. Consider the code:

The output is:

There are five arguments in this static format() method of the String class. The first argument is the main string of interest, whose content has four placeholders, each of which is %s. Together, the rest of the arguments are referred to as an argument list. Everything being equal, the first argument in the argument list corresponds to the first placeholder in the main string (from left). The second argument in the list corresponds to the second placeholder in the main string. The third argument in the argument list corresponds to the third placeholder in the main string, and so on. At the output, the placeholders are replaced by their corresponding arguments in a predetermined way from the argument list.

Five arguments are considered here. The very first one is not part of the considered argument list. It is actually called the format string, though it is still to be formatted. It is always a string. The rest of the arguments, forming the argument list, may be of different types, not necessarily, strings. Note: a placeholder here is called format specifier.

All the arguments above, can be replaced with variables, as the following code segment shows:

This article explains the basics of formatting a string in Java using format specifiers.

Format Specifier Syntax

The syntax for the format specifier is:

It must begin with the percentage sign, %. It must end with a character called the conversion. In the above code, each specifier consists of % and ‘s’. ‘s’ is the conversion. ‘s’ stands for string. The rest of the parameters, indicated in square brackets in the syntax, are optional and are explained below.

argument_index$
argument_index is a decimal integer. It begins from 1. It can be 1$, 2$, 3$, etc. The normal correspondences for the specifiers and arguments in the argument list are as follows: the first specifier on the left, in the format string, corresponds to the first argument in the argument list (from the left); the second specifier from the left, in the format string, corresponds to the second argument in the argument list; the third specifier from the left, in the format string, corresponds to the third argument in the argument list; and so on. argument_index can be used to change this order. The following code segment reverses the order:

The output is:

‘c’ in a specifier corresponds to a character in the argument list. The normal order is 1$, 2$, 3$, 4$. Since this order was reversed in the format string, so the output came out in reverse order.

Conversion

Conversion in string formatting is a special character. Each format specifier, with its conversion, corresponds to an argument in the argument list. A conversion is a character. The following table gives conversions and their meanings:

The use of ‘s’ and ‘c’ has been illustrated above. The rest of the conversion meta-characters will be illustrated in this section.

The b Conversion Character
The following code segment shows how a format specifier for a bool is replaced by the boolean value of its corresponding argument:

The output is:

Note that the argument, true, is not in quotes.

The d Conversion Character
The following code segment shows how a format specifier for a decimal integer is replaced by the value of its corresponding argument:

The output is:

Note that argument, 5, is not in quotes because it is not a character.

The f Conversion Character
The following code segment shows how a format specifier for a number with a decimal point, is replaced by its corresponding argument value:

First, note that the argument, 2.5, is not in quotes because it is not a string. The output is:

2.5 has been formatted to 2.500000, the default formatting. It can be restricted to 2.5 as given – see below.

The % Conversion Character
Since the percentage symbol is used to identify the format specifier, a scheme has to be developed to have the % symbol as an ordinary character in the format string. The scheme is simple: have % as a character argument in the argument list. Then use the % conversion character in the position in the format string, where the percentage symbol should appear. The following code segment illustrates this:

The output is:

The format specifier is %%. The first % of the pair, %%, is what identifies the specifier. The second % is the conversion character. As an argument, % is in single quotes.

The n Conversion Character
To cause the rest of the text on the right of the format string to go on the next line at the output, use n. n is a conversion character to be used in a format specifier. Illustration:

The output is:

The .precision Parameter of the Format Specifier

This parameter indicates the number of decimal places for a number with decimal places. It is a whole number preceded by the point. As noticed above, the expected number of decimal places for 2.5 is one character; but 6 characters were used, giving 2.500000. The following code segment limits this to 3 decimal places:

The output is:

The precision code here is .3 .

The width Parameter of the Format Specifier

The width is the minimum number of characters for replacement in the format string. Some argument types replace the format specifier with their expected width. However, others may replace it with a smaller or larger width. As noticed above, the expected width for 2.5 is three characters; but 8 characters were used, giving 2.500000. The following code segment should limit this to a width of 4 characters, and three decimal places:

The output is:

The format specifier is %4.3f, where 4 is the width, and 3 is the number of decimal places. There are actually 5 characters at the output, including the decimal point, so 4 were actually ignored. The following code segment produces a width of 7 characters and 3 decimal places:

The output is:

Notice that two space characters precede the number for the complete number to make up for a seven-character width. The number of decimal places is 3 . There are 7 characters here, all together, including the decimal point.

The flags Parameter of the Format Specifier

The 0 Flag
Instead of preceding a number with spaces, the number can be preceded with 0’s. The following code segment illustrates this:

The output is:

The exact format specifier here is,

which should be compared with the format specifier syntax,

The order of the meta-characters of the exact format specifier respects the order of the syntax of the format specifier. The optional flag, 0, comes before the optional width, 7, which comes before the optional precision, .3, in accordance with the syntax. ‘f’ is the conversion (still a meta-character).

The + Flag
With the + flag, the integer result is always preceded by – or + . The following program illustrates this:

The output is:

The optional width and precision parameters are not included with the exact format specifier, %+d. Here, d is the conversion for the integer.

Consider the code segment,

The output is,

Conclusion

The arguments for the String format method are divided into two sections. The first section is the first argument, which must be a string. It is the string of interest. It is called the format string, though it still has some of its sub-strings proper (formatted). The rest of the arguments are referred to as the argument list. The argument list has the real substrings that need formatting. Each of these substrings corresponds to a format specifier in the format string. The format specifier uses meta-characters to format.