Core.Printf Module (F#)

Article
02/04/2013

Extensible printf-style formatting for numbers and other datatypes.

Namespace/Module Path: Microsoft.FSharp.Core

Assembly: FSharp.Core (in FSharp.Core.dll)

module Printf

Remarks

Format specifications are strings with % markers indicating format placeholders. Format placeholders consist of: %[flags][width][.precision][type] where the type is interpreted as in the following table:

Type	Description
%b	Formats a bool, formatted as true or false.
%s	Formats a string, formatted as its contents, without interpreting any escape characters.
%d, %i	Formats any basic integer type formatted as a decimal integer, signed if the basic integer type is signed.
%u	Formats any basic integer type formatted as an unsigned decimal integer.
%x	Formats any basic integer type formatted as an unsigned hexadecimal integer, using lowercase letters a through f.
%X	Formats any basic integer type formatted as an unsigned hexadecimal integer, using uppercase letters A through F.
%o	Formats any basic integer type formatted as an unsigned octal integer.
%e, %E, %f, %F, %g, %G	Formats any basic floating point type (float, float32) formatted using a C-style floating point format specifications.
%e, %E	Formats a signed value having the form [-]d.dddde[sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or -.
%f	Formats a signed value having the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.
%g, %G	Formats a signed value printed in f or e format, whichever is more compact for the given value and precision.
%M	Formats a Decimal value.
%O	Formats any value, printed by boxing the object and using its ToString method.
%A	Formats any public value, printed with the default layout settings. The form %+A can be used to print the value of non-public data. Class and structure types display the same as with %O, regardless of whether you use %+A or %A.
%a	A general format specifier, requires two arguments. The first argument is a function which accepts two arguments: first, a context parameter of the appropriate type for the given formatting function (for example, a TextWriter), and second, a value to print and which either outputs or returns appropriate text. The second argument is the particular value to print.
%t	A general format specifier, requires one argument: a function which accepts a context parameter of the appropriate type for the given formatting function (a TextWriter)and which either outputs or returns appropriate text. Basic integer types are byte, sbyte, int16, uint16, int32, uint32, int64, uint64, nativeint, and unativeint. Basic floating point types are float and float32.

The optional width is an integer indicating the minimal width of the result. For instance, %6d prints an integer, prefixing it with spaces to fill at least 6 characters. If width is *, then an extra integer argument is taken to specify the corresponding width.

Valid flags are described in the following table.

0	Specifies to add zeros instead of spaces to make up the required width.
-	Specifies to left-justify the result within the width specified.
+	Specifies to add a + character if the number is positive (to match a - sign for negative numbers). When used with %A, specifies to print non-public values.
' ' (space)	Specifies to add an extra space if the number is positive (to match a - sign for negative numbers).
#	Invalid.

Type Abbreviations

Type	Description
type BuilderFormat<'T,'Result>	Represents a statically-analyzed format associated with writing to a StringBuilder. The first type parameter indicates the arguments of the format operation and the last the overall return type.
type BuilderFormat<'T>	Represents a statically-analyzed format associated with writing to a StringBuilder. The type parameter indicates the arguments and return type of the format operation.
type StringFormat<'T,'Result>	Represents a statically-analyzed format when formatting builds a string. The first type parameter indicates the arguments of the format operation and the last the overall return type.
type StringFormat<'T>	Represents a statically-analyzed format when formatting builds a string. The type parameter indicates the arguments and return type of the format operation.
type TextWriterFormat<'T,'Result>	Represents a statically-analyzed format associated with writing to a TextWriter. The first type parameter indicates the arguments of the format operation and the last the overall return type.
type TextWriterFormat<'T>	Represents a statically-analyzed format associated with writing to a TextWriter. The type parameter indicates the arguments and return type of the format operation.

Values

Value	Description
bprintf : StringBuilder -> BuilderFormat<'T> -> 'T	Prints to a StringBuilder.
eprintf : TextWriterFormat<'T> -> 'T	Prints formatted output to stderr.
eprintfn : TextWriterFormat<'T> -> 'T	Prints formatted output to stderr, adding a newline.
failwithf : StringFormat<'T,'Result> -> 'T	Prints to a string buffer and raises an exception with the given result. Helper printers must return strings.
fprintf : TextWriter -> TextWriterFormat<'T> -> 'T	Prints to a text writer.
fprintfn : TextWriter -> TextWriterFormat<'T> -> 'T	Prints to a text writer, adding a newline.
kbprintf : (unit -> 'Result) -> StringBuilder -> BuilderFormat<'T,'Result> -> 'T	Like bprintf, but calls the specified function to generate the result. See kprintf.
kfprintf : (unit -> 'Result) -> TextWriter -> TextWriterFormat<'T,'Result> -> 'T	Like fprintf, but calls the specified function to generate the result. See kprintf.
kprintf : (string -> 'Result) -> StringFormat<'T,'Result> -> 'T	Like printf, but calls the specified function to generate the result. For example, these let the printing force a flush after all output has been entered onto the channel, but not before.
ksprintf : (string -> 'Result) -> StringFormat<'T,'Result> -> 'T	Like sprintf, but calls the specified function to generate the result. See kprintf.
printf : TextWriterFormat<'T> -> 'T	Prints formatted output to stdout.
printfn : TextWriterFormat<'T> -> 'T	Prints formatted output to stdout, adding a newline.
sprintf : StringFormat<'T> -> 'T	Prints to a string by using an internal string buffer and returns the result as a string. Helper printers must return strings.

Platforms

Windows 7, Windows Vista SP2, Windows XP SP3, Windows XP x64 SP2, Windows Server 2008 R2, Windows Server 2008 SP2, Windows Server 2003 SP2

Version Information

F# Runtime

Supported in: 2.0, 4.0

Silverlight

Supported in: 2, 3

Change History

Date	History	Reason
April 2011	Added information about %+A.	Customer feedback.

April 2011

Added information about %+A.

Customer feedback.