layout: post
title: “Formatted text using printf”
description: “Tips and techniques for printing and logging”
nav: thinking-functionally
seriesId: “Expressions and syntax”

seriesOrder: 10

In this post, we’ll take a small detour and look at how to create formatted text. The printing and formatting functions are technically library functions,
but in practice they as used as if they were part of the core language.

F# supports two distinct styles of formatting text:

String.Format vs printf

The composite formatting technique is available in all .NET languages, and you are probably familiar with it from C#.

  1. Console.WriteLine("A string: {0}. An int: {1}. A float: {2}. A bool: {3}","hello",42,3.14,true)

The printf technique, on the other hand, is based on the C-style format strings:

  1. printfn "A string: %s. An int: %i. A float: %f. A bool: %b" "hello" 42 3.14 true

As you have seen, the printf technique is very common in F#, while String.Format, Console.Write and so on, are rarely used.

Why is printf preferred and considered idiomatic for F#? The reasons are:

  • It is statically type checked.
  • It is a well-behaved F# function and so supports partial application, etc.
  • It supports native F# types.

printf is statically type checked

Unlike String.Format, printf is statically type checked, both for the types of the parameters, and the number.

For example, here are two snippets using printf that will fail to compile:

  1. // wrong parameter type
  2. printfn "A string: %s" 42
  3. // wrong number of parameters
  4. printfn "A string: %s" "Hello" 42

The equivalent code using composite formatting will compile fine but either work incorrectly but silently, or give a runtime error:

  1. // wrong parameter type
  2. Console.WriteLine("A string: {0}", 42) //works!
  3. // wrong number of parameters
  4. Console.WriteLine("A string: {0}","Hello",42) //works!
  5. Console.WriteLine("A string: {0}. An int: {1}","Hello") //FormatException

printf supports partial application

The .NET formatting functions require all parameters to be passed in at the same time.

But printf is a standard, well-behaved F# function, and so supports partial application.

Here are some examples:

  1. // partial application - explicit parameters
  2. let printStringAndInt s i = printfn "A string: %s. An int: %i" s i
  3. let printHelloAndInt i = printStringAndInt "Hello" i
  4. do printHelloAndInt 42
  5. // partial application - point free style
  6. let printInt = printfn "An int: %i"
  7. do printInt 42

And of course, printf can be used for function parameters anywhere a standard function can be used.

  1. let doSomething printerFn x y =
  2. let result = x + y
  3. printerFn "result is" result
  4. let callback = printfn "%s %i"
  5. do doSomething callback 3 4

This also includes the higher order functions for lists, etc:

  1. [1..5] |> List.map (sprintf "i=%i")

printf supports native F# types

For non-primitive types, the .NET formatting functions only support using ToString(), but printf supports native F# types using the %A specifier:

  1. // tuple printing
  2. let t = (1,2)
  3. Console.WriteLine("A tuple: {0}", t)
  4. printfn "A tuple: %A" t
  5. // record printing
  6. type Person = {First:string; Last:string}
  7. let johnDoe = {First="John"; Last="Doe"}
  8. Console.WriteLine("A record: {0}", johnDoe )
  9. printfn "A record: %A" johnDoe
  10. // union types printing
  11. type Temperature = F of int | C of int
  12. let freezing = F 32
  13. Console.WriteLine("A union: {0}", freezing )
  14. printfn "A union: %A" freezing

As you can see, tuple types have a nice ToString() but other user defined types don’t,
so if you want to use them with the .NET formatting functions, you will have to override the ToString() method explicitly.

printf gotchas

There are a couple of “gotchas” to be aware of when using printf.

First, if there are too few parameters, rather than too many, the compiler will not complain immediately, but might give cryptic errors later.

  1. // too few parameters
  2. printfn "A string: %s An int: %i" "Hello"

The reason, of course, is that this is not an error at all; printf is just being partially applied!
See the discussion of partial application if you are not clear of why this happens.

Another issue is that the “format strings” are not actually strings.

In the .NET formatting model, the formatting strings are normal strings, so you can pass them around, store them in resource files, and so on.
Which means that the following code works fine:

  1. let netFormatString = "A string: {0}"
  2. Console.WriteLine(netFormatString, "hello")

On the other hand, the “format strings” that are the first argument to printf are not really strings at all, but something called a TextWriterFormat.
Which means that the following code does not work:

  1. let fsharpFormatString = "A string: %s"
  2. printfn fsharpFormatString "Hello"

The compiler does some magic behind the scenes to convert the string constant "A string: %s" into the appropriate TextWriterFormat.
The TextWriterFormat is the key component that “knows” the type of the format string, such as string->unit or string->int->unit, which in turn allows
printf to be typesafe.

If you want to emulate the compiler, you can create your own TextWriterFormat value from a string using the Printf.TextWriterFormat type in the Microsoft.FSharp.Core.Printf module.

If the format string is “inline”, the compiler can deduce the type for you during binding:

  1. let format:Printf.TextWriterFormat<_> = "A string: %s"
  2. printfn format "Hello"

But if the format string is truly dynamic (e.g. stored in a resource or created on the fly), the compiler cannot deduce the type for you,
and you must explicitly provide it with the constructor.

In the example below, my first format string has a single string parameter and returns a unit, so I have to specify string->unit as the format type.
And in the second case, I have to specify string->int->unit as the format type.

  1. let formatAString = "A string: %s"
  2. let formatAStringAndInt = "A string: %s. An int: %i"
  3. //convert to TextWriterFormat
  4. let twFormat1 = Printf.TextWriterFormat<string->unit>(formatAString)
  5. printfn twFormat1 "Hello"
  6. let twFormat2 = Printf.TextWriterFormat<string->int->unit>(formatAStringAndInt)
  7. printfn twFormat2 "Hello" 42

I won’t go into detail on exactly how printf andTextWriterFormat` work together right now — just be aware that is not just a matter of simple format strings being passed around.

Finally, it’s worth noting that printf and family are not thread-safe, while Console.Write and family are.

How to specify a format

The “%” format specifications are quite similar to those used in C, but with some special customizations for F#.

As with C, the characters immediately following the % have a specific meaning, as shown below.

  1. %[flags][width][.precision]specifier

We’ll discuss each of these attributes in more detail below.

Formatting for dummies

The most commonly used format specifiers are:

  • %s for strings
  • %b for bools
  • %i for ints
  • %f for floats
  • %A for pretty-printing tuples, records and union types
  • %O for other objects, using ToString()

These six will probably meet most of your basic needs.

Escaping %

The % character on its own will cause an error. To escape it, just double it up:

  1. printfn "unescaped: %" // error
  2. printfn "escape: %%"

Controlling width and alignment

When formatting fixed width columns and tables, you need to have control of the alignment and width.

You can do that with the “width” and “flags” options.

  • %5s, %5i. A number sets the width of the value
  • %*s, %*i. A star sets the width of the value dynamically (from an extra parameter just before the param to format)
  • %-s, %-i. A hyphen left justifies the value.

Here are some examples of these in use:

  1. let rows = [ (1,"a"); (-22,"bb"); (333,"ccc"); (-4444,"dddd") ]
  2. // no alignment
  3. for (i,s) in rows do
  4. printfn "|%i|%s|" i s
  5. // with alignment
  6. for (i,s) in rows do
  7. printfn "|%5i|%5s|" i s
  8. // with left alignment for column 2
  9. for (i,s) in rows do
  10. printfn "|%5i|%-5s|" i s
  11. // with dynamic column width=20 for column 1
  12. for (i,s) in rows do
  13. printfn "|%*i|%-5s|" 20 i s
  14. // with dynamic column width for column 1 and column 2
  15. for (i,s) in rows do
  16. printfn "|%*i|%-*s|" 20 i 10 s

Formatting integers

There are some special options for basic integer types:

  • %i or %d for signed ints
  • %u for unsigned ints
  • %x and %X for lowercase and uppercase hex
  • %o for octal

Here are some examples:

  1. printfn "signed8: %i unsigned8: %u" -1y -1y
  2. printfn "signed16: %i unsigned16: %u" -1s -1s
  3. printfn "signed32: %i unsigned32: %u" -1 -1
  4. printfn "signed64: %i unsigned64: %u" -1L -1L
  5. printfn "uppercase hex: %X lowercase hex: %x octal: %o" 255 255 255
  6. printfn "byte: %i " 'A'B

The specifiers do not enforce any type safety within the integer types. As you can see from the examples above, you can pass a signed int to an unsigned specifier without problems.
What is different is how it is formatted. The unsigned specifiers treat the int as unsigned no matter how it is actually typed.

Note that BigInteger is not a basic integer type, so you must format it with %A or %O.

  1. printfn "bigInt: %i " 123456789I // Error
  2. printfn "bigInt: %A " 123456789I // OK

You can control the formatting of signs and zero padding using the flags:

  • %0i pads with zeros
  • %+i shows a plus sign
  • % i shows a blank in place of a plus sign

Here are some examples:

  1. let rows = [ (1,"a"); (-22,"bb"); (333,"ccc"); (-4444,"dddd") ]
  2. // with alignment
  3. for (i,s) in rows do
  4. printfn "|%5i|%5s|" i s
  5. // with plus signs
  6. for (i,s) in rows do
  7. printfn "|%+5i|%5s|" i s
  8. // with zero pad
  9. for (i,s) in rows do
  10. printfn "|%0+5i|%5s|" i s
  11. // with left align
  12. for (i,s) in rows do
  13. printfn "|%-5i|%5s|" i s
  14. // with left align and plus
  15. for (i,s) in rows do
  16. printfn "|%+-5i|%5s|" i s
  17. // with left align and space instead of plus
  18. for (i,s) in rows do
  19. printfn "|% -5i|%5s|" i s

Formatting floats and decimals

For floating point types, there are also some special options:

  • %f for standard format
  • %e or %E for exponential format
  • %g or %G for the more compact of f and e.
  • %M for decimals

Here are some examples:

  1. let pi = 3.14
  2. printfn "float: %f exponent: %e compact: %g" pi pi pi
  3. let petabyte = pown 2.0 50
  4. printfn "float: %f exponent: %e compact: %g" petabyte petabyte petabyte

The decimal type can be used with the floating point specifiers, but you might lose some precision.
The %M specifier can be used to ensure that no precision is lost. You can see the difference with this example:

  1. let largeM = 123456789.123456789M // a decimal
  2. printfn "float: %f decimal: %M" largeM largeM

You can control the precision of floats using a precision specification, such as %.2f and %.4f.
For the %f and %e specifiers, the precision affects the number of digits after the decimal point, while for %g it is the number of digits in total.
Here’s an example:

  1. printfn "2 digits precision: %.2f. 4 digits precision: %.4f." 123.456789 123.456789
  2. // output => 2 digits precision: 123.46. 4 digits precision: 123.4568.
  3. printfn "2 digits precision: %.2e. 4 digits precision: %.4e." 123.456789 123.456789
  4. // output => 2 digits precision: 1.23e+002. 4 digits precision: 1.2346e+002.
  5. printfn "2 digits precision: %.2g. 4 digits precision: %.4g." 123.456789 123.456789
  6. // output => 2 digits precision: 1.2e+02. 4 digits precision: 123.5.

The alignment and width flags work for floats and decimals as well.

  1. printfn "|%f|" pi // normal
  2. printfn "|%10f|" pi // width
  3. printfn "|%010f|" pi // zero-pad
  4. printfn "|%-10f|" pi // left aligned
  5. printfn "|%0-10f|" pi // left zero-pad

Custom formatting functions

There are two special format specifiers that allow to you pass in a function rather than just a simple value.

  • %t expects a function that outputs some text with no input
  • %a expects a function that outputs some text from a given input

Here’s an example of using %t:

  1. open System.IO
  2. //define the function
  3. let printHello (tw:TextWriter) = tw.Write("hello")
  4. //test it
  5. printfn "custom function: %t" printHello

Obviously, since the callback function takes no parameters, it will probably be a closure that does reference some other value.
Here’s an example that prints random numbers:

  1. open System
  2. open System.IO
  3. //define the function using a closure
  4. let printRand =
  5. let rand = new Random()
  6. // return the actual printing function
  7. fun (tw:TextWriter) -> tw.Write(rand.Next(1,100))
  8. //test it
  9. for i in [1..5] do
  10. printfn "rand = %t" printRand

For the %a specifier, the callback function takes an extra parameter. That is, when using the %a specifier, you must pass in both a function and a value to format.

Here’s an example of custom formatting a tuple:

  1. open System
  2. open System.IO
  3. //define the callback function
  4. //note that the data parameter comes after the TextWriter
  5. let printLatLong (tw:TextWriter) (lat,long) =
  6. tw.Write("lat:{0} long:{1}", lat, long)
  7. // test it
  8. let latLongs = [ (1,2); (3,4); (5,6)]
  9. for latLong in latLongs do
  10. // function and value both passed in to printfn
  11. printfn "latLong = %a" printLatLong latLong

Date formatting

There are no special format specifiers for dates in F#.

If you want to format dates, you have a couple of options:

  • Use ToString to convert the date into a string, and then use the %s specifier
  • Use a custom callback function with the %a specifier as described above

Here are the two approaches in use:

  1. // function to format a date
  2. let yymmdd1 (date:DateTime) = date.ToString("yy.MM.dd")
  3. // function to format a date onto a TextWriter
  4. let yymmdd2 (tw:TextWriter) (date:DateTime) = tw.Write("{0:yy.MM.dd}", date)
  5. // test it
  6. for i in [1..5] do
  7. let date = DateTime.Now.AddDays(float i)
  8. // using %s
  9. printfn "using ToString = %s" (yymmdd1 date)
  10. // using %a
  11. printfn "using a callback = %a" yymmdd2 date

Which approach is better?

The ToString with %s is easier to test and use, but it will be less efficient than writing directly to a TextWriter.

The printf family of functions

There are a number of variants of printf functions. Here is a quick guide:

F# function C# equivalent Comment
printf and printfn Console.Write and Console.WriteLine Functions starting with “print” write to standard out.
eprintf and eprintfn Console.Error.Write and Console.Error.WriteLine Functions starting with “eprint” write to standard error.
fprintf and fprintfn TextWriter.Write and TextWriter.WriteLine Functions starting with “fprint” write to a TextWriter.
sprintf String.Format Functions starting with “sprint” return a string.
bprintf StringBuilder.AppendFormat Functions starting with “bprint” write to a StringBuilder.
kprintf, kfprintf, ksprintf and kbprintf No equivalent Functions that accept a continuation. See next section for a discussion.

All of these except bprintf and the kXXX family are automatically available (via Microsoft.FSharp.Core.ExtraTopLevelOperators).
But if you need to access them using a module, they are in the Printf module.

The usage of these should be obvious (except for the kXXX family, of which more below).

A particularly useful technique is to use partial application to “bake in” a TextWriter or StringBuilder.

Here is an example using a StringBuilder:

  1. let printToSb s i =
  2. let sb = new System.Text.StringBuilder()
  3. // use partial application to fix the StringBuilder
  4. let myPrint format = Printf.bprintf sb format
  5. do myPrint "A string: %s. " s
  6. do myPrint "An int: %i" i
  7. //get the result
  8. sb.ToString()
  9. // test
  10. printToSb "hello" 42

And here is an example using a TextWriter:

  1. open System
  2. open System.IO
  3. let printToFile filename s i =
  4. let myDocsPath = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments)
  5. let fullPath = Path.Combine(myDocsPath, filename)
  6. use sw = new StreamWriter(path=fullPath)
  7. // use partial application to fix the TextWriter
  8. let myPrint format = fprintf sw format
  9. do myPrint "A string: %s. " s
  10. do myPrint "An int: %i" i
  11. //get the result
  12. sw.Close()
  13. // test
  14. printToFile "myfile.txt" "hello" 42

More on partially applying printf

Note that in both cases above, we had to pass a format parameter when creating the partial application.

That is, we had to do:

  1. let myPrint format = fprintf sw format

rather than the point-free version:

  1. let myPrint = fprintf sw

This stops the compiler complaining about an incorrect type. The reason why is non-obvious. We briefly mentioned the TextWriterFormat above as the first parameter to printf. It turns out that printf is not actually a particular function, like String.Format,
but rather a generic function that has to be parameterized with a TextWriterFormat (or the similar StringFormat) in order to become “real”.

So, to be safe, it is best to always pair a printf with a format parameter, rather than being overly aggressive with the partial application.

The kprintf functions

The four kXXX functions are similar to their cousins, except that they take an extra parameter — a continuation. That is, a function to be called immediately after the formatting has been done.

Here’s a simple snippet:

  1. let doAfter s =
  2. printfn "Done"
  3. // return the result
  4. s
  5. let result = Printf.ksprintf doAfter "%s" "Hello"

Why would you want this? A number of reasons:

  • You can pass the result to another function that does something useful, such as a logging framework
  • You can do things such as flushing the TextWriter
  • You can raise an event

Let’s look at a sample that uses a external logging framework plus custom events.

First, let’s create a simple logging class along the lines of log4net or System.Diagnostics.Trace.
In practice, this would be replaced by a real third-party library.

  1. open System
  2. open System.IO
  3. // a logging library such as log4net
  4. // or System.Diagnostics.Trace
  5. type Logger(name) =
  6. let currentTime (tw:TextWriter) =
  7. tw.Write("{0:s}",DateTime.Now)
  8. let logEvent level msg =
  9. printfn "%t %s [%s] %s" currentTime level name msg
  10. member this.LogInfo msg =
  11. logEvent "INFO" msg
  12. member this.LogError msg =
  13. logEvent "ERROR" msg
  14. static member CreateLogger name =
  15. new Logger(name)

Next in my application code, I do the following:

  • Create an instance of the logging framework. I’ve hard-coded the factory method here, but you could also use an IoC container.
  • Create helper functions called logInfo and logError that call the logging framework, and in the case of logError, show a popup message as well.
  1. // my application code
  2. module MyApplication =
  3. let logger = Logger.CreateLogger("MyApp")
  4. // create a logInfo using the Logger class
  5. let logInfo format =
  6. let doAfter s =
  7. logger.LogInfo(s)
  8. Printf.ksprintf doAfter format
  9. // create a logError using the Logger class
  10. let logError format =
  11. let doAfter s =
  12. logger.LogError(s)
  13. System.Windows.Forms.MessageBox.Show(s) |> ignore
  14. Printf.ksprintf doAfter format
  15. // function to exercise the logging
  16. let test() =
  17. do logInfo "Message #%i" 1
  18. do logInfo "Message #%i" 2
  19. do logError "Oops! an error occurred in my app"

Finally, when we run the test function, we should get the message written to the console, and also see the popup message:

  1. MyApplication.test()

You could also create an object-oriented version of the helper methods by creating a “FormattingLogger” wrapper class around the logging library, as shown below.

  1. type FormattingLogger(name) =
  2. let logger = Logger.CreateLogger(name)
  3. // create a logInfo using the Logger class
  4. member this.logInfo format =
  5. let doAfter s =
  6. logger.LogInfo(s)
  7. Printf.ksprintf doAfter format
  8. // create a logError using the Logger class
  9. member this.logError format =
  10. let doAfter s =
  11. logger.LogError(s)
  12. System.Windows.Forms.MessageBox.Show(s) |> ignore
  13. Printf.ksprintf doAfter format
  14. static member createLogger name =
  15. new FormattingLogger(name)
  16. // my application code
  17. module MyApplication2 =
  18. let logger = FormattingLogger.createLogger("MyApp2")
  19. let test() =
  20. do logger.logInfo "Message #%i" 1
  21. do logger.logInfo "Message #%i" 2
  22. do logger.logError "Oops! an error occurred in app 2"
  23. // test
  24. MyApplication2.test()

The object-oriented approach, although more familiar, is not automatically better! The pros and cons of OO methods vs. pure functions are discussed here.