View source code
Display the source code in std/format.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

Module std.format

This module implements the formatting functionality for strings and I/O. It's comparable to C99's vsprintf() and uses a similar format encoding scheme.

For an introductory look at std.format's capabilities and how to use this module see the dedicated DWiki article.

This module centers around two functions:

Function Name Description
formattedRead Reads values according to the format string from an InputRange.
formattedWrite Formats its arguments according to the format string and puts them to an OutputRange.

Please see the documentation of function formattedWrite for a description of the format string.

Two functions have been added for convenience:

Function Name Description
format Returns a GC-allocated string with the formatting result.
sformat Puts the formatting result into a preallocated array.

These two functions are publicly imported by std.string to be easily available.

The functions formatValue and unformatValue are used for the plumbing.

Functions

Name Description
format Format arguments into a string.
formattedRead Reads characters from input range r, converts them according to fmt, and writes them to args.
formattedWrite Interprets variadic argument list args, formats them according to fmt, and sends the resulting characters to w. The encoding of the output is the same as Char. The type Writer must satisfy std.range.primitives.isOutputRange!(Writer, Char).
formatValue bools are formatted as "true" or "false" with %s and as "1" or "0" with integral-specific format specs.
formatValue null literal is formatted as "null".
formatValue Integrals are formatted like printf does.
formatValue Floating-point values are formatted like printf does.
formatValue Individual characters (char, wchar, or dchar) are formatted as Unicode characters with %s and as integers with integral-specific format specs.
formatValue Strings are formatted like printf does.
formatValue Static-size arrays are formatted as dynamic arrays.
formatValue Dynamic arrays are formatted as input ranges.
formatValue Associative arrays are formatted by using ':' and ", " as separators, and enclosed by '[' and ']'.
formatValue Aggregates (struct, union, class, and interface) are basically formatted by calling toString. toString should have one of the following signatures:
formatValue enum is formatted like its base value.
formatValue Pointers are formatted as hex integers.
formatValue Delegates are formatted by 'ReturnType delegate(Parameters) FunctionAttributes'
sformat Format arguments into buffer buf which must be large enough to hold the result.
singleSpec Helper function that returns a FormatSpec for a single specifier given in fmt.
unformatValue Reads a value from the given input range according to spec and returns it as type T.

Classes

Name Description
FormatException Signals a mismatch between a format and its corresponding argument.

Structs

Name Description
FormatSpec A General handler for printf style format specifiers. Used for building more specific formatting functions.

Authors

Walter Bright, Andrei Alexandrescu, and Kenji Hara

License

Boost License 1.0.

Comments