printf: Format Specifiers, Width and Precision

Amara is printing a contest leaderboard. Her names are different lengths, so the solved column starts in a different place on every row. The whole thing looks like a ransom note. She has been adding spaces by hand for twenty minutes.

The fix is four characters. printf has had a small layout language inside it since 1972, and almost nobody is taught it properly. This lesson teaches it properly.

A format string is text with holes in it

The first argument to printf is a template. Everything in it is printed as it stands, except a run starting with %, which is a conversion specification: a hole, plus instructions for filling it.

The values after the format string fill the holes in order. There is no checking at run time, and that fact is the source of every mistake in this lesson.

%[flags][width][.precision]conversion

flags        -  left align inside the field
             0  pad the field with zeros instead of spaces
             +  always print a sign, even for a positive number
                a space, print a space where the plus sign would go

width        a whole number: the smallest number of characters to use

.precision   for a float, the digits after the point
             for a string, the most characters to print

conversion   d  i  a signed int              u  an unsigned int
             ld    a long                    lld   a long long
             f     a double, fixed point      e  a double, scientific
             g     a double, whichever is shorter
             c     one character              s   a string
             x  X  hexadecimal, lower or upper case
             o     octal                      p   a pointer
             zu    a size_t                   %%  a literal percent sign

Width is the smallest field a value may occupy

A width pads the value with spaces until the field is that wide. By default the padding goes on the left, so the value sits to the right of its field.

Two flags change that. The minus sign moves the padding to the right, so the value sits on the left. The zero pads with zeros instead of spaces, which only makes sense for a number.

#include <stdio.h>

int main(void)
{
    printf("[%d]\n", 42);
    printf("[%8d]\n", 42);
    printf("[%-8d]\n", 42);
    printf("[%08d]\n", 42);
    printf("[%+d]\n", 42);
    printf("[% d]\n", 42);
    printf("[%8.3f]\n", 3.14159);
    printf("[%-8.3f]\n", 3.14159);
    printf("[%.3s]\n", "Progsity");
    printf("[%%]\n");
    return 0;
}

[42]
[      42]
[42      ]
[00000042]
[+42]
[ 42]
[   3.142]
[3.142   ]
[Pro]
[%]

Every square bracket in that output is exactly where the field starts and ends. Count the characters between them and each rule explains itself.

The ninth line is the surprising one. On a string, a precision is a maximum rather than a minimum, so %.3s printed three letters of eight.

The last line is how you print a percent sign. A lone % starts a specifier, so you write two.

Precision means two different things

On a float, the precision is the number of digits after the point, and the value is rounded to fit. %.2f is the shape almost every money and measurement problem asks for.

On a string, the precision is the largest number of characters to print, and the rest is dropped.

On an integer, a precision is the smallest number of digits, padded with zeros, which is a rare thing to want and worth recognising.

So the same two characters mean round to, cut to, or pad to, depending on one letter three places to the right.

A lined-up table is width and nothing else

Amara's leaderboard needs one width per column, and the text column needs the minus flag so that names start at the same place.

#include <stdio.h>

int main(void)
{
    printf("%-14s%8s%10s\n", "PLAYER", "SOLVED", "PENALTY");
    printf("%-14s%8d%10d\n", "Amara", 9, 412);
    printf("%-14s%8d%10d\n", "Kenji", 9, 1207);
    printf("%-14s%8d%10d\n", "Zara", 7, 388);
    printf("%-14s%8d%10d\n", "Bob", 2, 44);
    return 0;
}

PLAYER          SOLVED   PENALTY
Amara                9       412
Kenji                9      1207
Zara                 7       388
Bob                  2        44

One format string, used five times. The header row uses %s for the numbers' column titles, which is why the widths match across all five lines.

Notice there is no space between the specifiers. The widths already provide the gaps, and adding spaces as well is how a table ends up one character out.

printf hands you a number back

Almost nobody knows this. printf returns the number of characters it wrote, or a negative number if the write failed.

Most programs ignore it, which is fine. It is the honest way to answer "how wide was that line". It also matters because a returned value is how scanf is used properly in the next lesson.

#include <stdio.h>

int main(void)
{
    int written = printf("Amara scored %d\n", 97);

    printf("that line was %d characters long\n", written);
    printf("a %%d holds %d, a %%x holds %x, a %%o holds %o\n", 255, 255, 255);
    printf("a size_t needs %%zu: %zu\n", sizeof(int));
    return 0;
}

Amara scored 97
that line was 16 characters long
a %d holds 255, a %x holds ff, a %o holds 377
a size_t needs %zu: 4

Sixteen characters: fourteen visible, plus the newline, plus the second digit of 97. Count them yourself, because that is the point of the line.

The third line prints one value three times in three bases. Module 3 lesson 1 wrote those bases as literals; here they are being read back out.

The fourth uses %zu, the specifier for the type sizeof gives you. Module 2 lesson 5 introduced it, and it is in this list because %d there is a mismatch that nothing will report.

When the specifier and the value disagree

A specifier tells printf how many bytes to take and how to read them. If it is wrong, printf still takes those bytes and still reads them that way.

The format checking that catches this lives behind -Wall, and the Playground compiles with gcc -O2 -std=c17 -lm and no -Wall. So on the Playground this class of mistake is completely silent, at compile time and at run time.

That is not a reason to avoid the Playground. It is a reason to know the four mismatches below by sight, because you will get no help finding them.

#include <stdio.h>

int main(void)
{
    int marks = 7;

    printf("|%d|\n", marks);
    printf("|%4d|\n", marks);
    printf("|%-4d|\n", marks);
    return 0;
}

|7|
|   7|
|7   |

#include <stdio.h>

int main(void)
{
    printf("%-10s%5s%10s\n", "ITEM", "QTY", "TAKA");
    printf("%-10s%5d%10.2f\n", "rice", 12, 45.00);
    printf("%-10s%5d%10.2f\n", "oil", 3, 120.50);
    printf("%-10s%5d%10.2f\n", "salt", 7, 2.50);
    printf("%-10s%5d%10.2f\n", "TOTAL", 22, 1083.50);
    return 0;
}

ITEM        QTY      TAKA
rice         12     45.00
oil           3    120.50
salt          7      2.50
TOTAL        22   1083.50

#include <stdio.h>

int main(void)
{
    unsigned int reg = 48879;

    printf("dec:%10u\n", reg);
    printf("hex:%10x\n", reg);
    printf("HEX:%10X\n", reg);
    printf("oct:%10o\n", reg);
    printf("padded hex: 0x%08X\n", reg);
    return 0;
}

dec:     48879
hex:      beef
HEX:      BEEF
oct:    137357
padded hex: 0x0000BEEF

double price = 12.5;
printf("%d\n", price);

printf("marks %d and %d\n", 90);

printf("VAT is 15% of the bill\n");

long long total = 5000000000;
printf("%d\n", total);
printf("%d\n", sizeof(int));

#include <stdio.h>

int main(void)
{
    printf("[%5.2f]\n", 3.14159);
    printf("[%5.2f]\n", 1234.5678);
    printf("[%.2f]\n", 3.14159);
    return 0;
}

#include <stdio.h>

int main(void)
{
    unsigned int n = 0;
    scanf("%u", &n);

    /* Four lines, four bases, one width. */

    return 0;
}

#include <stdio.h>

int main(void)
{
    /* One format string, used six times. Start from the example above. */

    return 0;
}

#include <stdio.h>

int main(void)
{
    double a = 0.0;
    double b = 0.0;
    double c = 0.0;
    scanf("%lf %lf %lf", &a, &b, &c);

    /* Three printf calls, one width and one precision each. */

    return 0;
}

#include <stdio.h>

int main(void)
{
    int written = printf("Progsity Learn, C track\n");

    /* One more printf, using written. */

    return 0;
}

Next you turn the whole thing around and read values in, where the same format language has one extra rule and one famous trap.