printf Revisited

Dr. Dobb's Journal January, 2005

Picking up where IOStreams leaves off

By Walter Bright

I love C's printf. It's one of the original reasons why I switched from Pascal to C 20-plus years ago. It's quick and easy to bang out. It never complains, it's always faithful, it just does its job. It's just so darned useful and convenient.

But I have to admit it, printf has well-known faults:

• It's not typesafe. There's no checking to see if the format specifications and the argument types line up, or even if the arguments exist. Getting this wrong results in bizarre output and/or crashes.
• It doesn't work well at all for generic programming. For example, you must know the underlying type of a typedefed argument to put in the right format for it, which defeats much of the purpose of using a typedef. This is especially a problem with templated code.
• The format string mixes together both the type of the argument(s) and how to print them.
• Poor character set handling. printf and wprintf cannot be interleaved on the same stream. This tends to wind up forcing you to choose between char and wchar throughout the app. Various wretched approaches like <tchar.h> attempt to mitigate this.
• Nonportable universal character (UTF) support. wprintf tries to deal with this, but fails because wchar_t is implementation defined.
• printf's cousins (like sprintf) suffer from buffer overflows unless you are very, very careful. snprintf suffers from the guess-what-size-is-needed-in-advance kludge.
• It's not able to deal with user-defined types.
• There are too many confusing format characters, made worse in C99. There are so many that I have to refer to the manual on them, even though I've implemented a C99 printf for the Digital Mars C runtime library.

The most noticeable attempt to fix these faults was C++'s IOStreams, which itself has undergone two major overhauls, and credibly solves some of printf's problems. But in the process, we lost what was so cool about printf. What was short and sweet turned long and clumsy. For instance, "Hello world" looks fine:

printf("Hello world!\n");
std::cout << "Hello world!\n";

but when there are more arguments, it starts looking dodgy:

printf("Elapsed time for %s is %d %s\n", foo, etime, units);
std::cout << "Elapsed time for " << foo << " is "
<< etime << " " << units << std::endl;

But IOStreams really gets beaten with the ugly stick when you try to use something other than the default formatting:

printf("%d|%-8d|%d\n", 123, 456, 789);
std::ios_base::fmtflags flags_save = std::cout.flags();
std::cout << 123 << '|' << std::left
<< std::setw(8) << 456
<< "|" << 789 << std::endl;
std::cout.flags(flags_save);

Even worse, formatting with IOStreams introduces problems with exception safety and thread safety with respect to stream state, since the std::left relies on a sticky global state.

And finally, IOStreams inherits all of C's problems with UTF characters.

The D programming language (http://www.digitalmars.com/d/index.html) attempts to retain the great things about C and C++ while fixing the faults. Therefore, printf needs to be fixed to resolve the acknowledged problems while retaining its handy utility. Few other issues with D generated more debate, heat, ideas, and volume on the D newsgroup (news.digitalmars.com).

The obvious root of printf's problems is the lack of type information corresponding to the variadic function arguments. In D, variadic functions are passed a hidden argument that is an array of the types of all the variadic arguments. This gives a free hand in designing a replacement—writef—and having these functions corresponding roughly to printf, fprintf, and sprintf:

void writef(...); // write arguments to
// stdout
void fwritef(fp, ...); // write arguments to fp
char[] format(...); // create a string and
// write the arguments to it

What happened to the format string as the first argument? It isn't necessarily needed. The argument scanner in writef's implementation scans each argument in order. If it is a char[], it is interpreted as a format string; otherwise, it is printed in the default manner appropriate to its type:

writef(); // prints no characters
writef("hello", " world\n"); // prints 'hello
// world\n'
writef(123, 8.60, '@'); // prints '1238.6@'

If an argument is an instance of a class derived from Object, the class's toString() method is called to get the corresponding string to print:

class Man
{
char[] toString() { return "I am a Man, not an ape"; }
}
void foo(A a)
{
writef(a); // prints 'I am a Man, not an ape'
}

writef's format strings are greatly simplified because they no longer have to do double duty as type specifications. Any string not under the control of a previous format is interpreted as being a format string. It is parsed and interpreted, and subsequent arguments are consumed and formatted in an analogous manner to printf. %s takes the next argument and prints it in its default format. %d takes the next argument, which must be an integral type, and prints it in decimal. (Whether it is signed is determined by its type, not its format.) If the next argument is not an integral type, an exception is thrown.

Similarly, %b, %o, %x, and %x format integral types in binary, octal, lowercase hex, and uppercase hex, respectively. The %e, %E, %f, %F, %g, %G, %a, and %A take the next argument, which must be a floating-point type, and prints it in the corresponding floating format (they work the same as C99's floating-point formats).

And that's it for basic formats. No need for l, ll, L, or hh modifiers, or for %u and the like:

writef("%x %s", 123, 456L, 789);
// prints '7b 456789'
writef("%o ", 56, "%b", 22);
// prints '70 10110'
writef("%d %d %d", -1, -1, cast(uint)-1);
// prints -1 -1 4294967295

To the basic formats, writef adds in the flags, field width, and precision specifications wholesale from C99.

writef("%d|%-8d|%d", 123, 456, 789);
// prints '123|456|789'

So how does writef stack up against the complaints about printf? Well, writef:

• Is completely typesafe. Any unresolvable conflicts, such as trying to print a string in scientific notation, result in a runtime exception being thrown.
• Works for generic programming, because the format specifier no longer specifies the type. The type of the arguments are known to the formatter, so the programmer need not care what the underlying type of a typedef or template argument is.
• The format string only says how to print them, it does not contain type information.
• Can accept strings and characters in char[], wchar[], or dchar[] types corresponding to UTF-8, UTF-16, and UTF-32 character encodings. They can be mixed and matched even within one writef. There's no need to decide if the application is going to be char or wchar_t; each individual string can be whatever is most suitable to its data. writef can seamlessly combine them. Since UTF strings are an international standard, code using them is portable. The output of writef is converted to the character encoding used by the output stream.
• D arrays include length information, so attempts to overflow a buffer result in an exception being thrown rather than a crash or security breach.
• User-defined types are converted to strings via the user-defined toString() method.
• A small number of formats, coupled with intuitive defaults, means you'll be consulting the documentation a lot less frequently.

Recall the complaint that C++ IOStreams was neither exception safe nor thread safe with respect to the stream state. writef is exception safe because its formatting state is local on the stack, not globally set. It's thread safe when the implementation of writef synchronizes itself with stdout across the entire invocation of writef.

DDJ