std.format

class FormatException: object.Exception;

Signals a mismatch between a format and its corresponding argument.

uint formattedWrite(Writer, Char, A...)(Writer w, in Char[] fmt, A args);

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).

The variadic arguments are normally consumed in order. POSIX-style positional parameter syntax is also supported. Each argument is formatted into a sequence of chars according to the format specification, and the characters are passed to w. As many arguments as specified in the format string are consumed and formatted. If there are fewer arguments than format specifiers, a FormatException is thrown. If there are more remaining arguments than needed by the format specification, they are ignored but only if at least one argument was formatted.

The format string supports the formatting of array and nested array elements via the grouping format specifiers %( and %). Each matching pair of %( and %) corresponds with a single array argument. The enclosed sub-format string is applied to individual array elements. The trailing portion of the sub-format string following the conversion specifier for the array element is interpreted as the array delimiter, and is therefore omitted following the last array element. The %| specifier may be used to explicitly indicate the start of the delimiter, so that the preceding portion of the string will be included following the last array element. (See below for explicit examples.)

Parameters:

Writer w	Output is sent to this writer. Typical output writers include std.array.Appender!string and std.stdio.LockingTextWriter.
Char[] fmt	Format string.
A args	Variadic argument list.

Returns:

Formatted number of arguments.

Throws:

Mismatched arguments and formats result in a FormatException being thrown.

Format String: Format strings consist of characters interspersed with format specifications. Characters are simply copied to the output (such as putc) after any necessary conversion to the corresponding UTF-8 sequence.

The format string has the following grammar:

FormatString:
    FormatStringItem*
FormatStringItem:
    '%%'
    '%' Position Flags Width Precision FormatChar
    '%(' FormatString '%)'
    OtherCharacterExceptPercent
Position:
    empty
    Integer '$'
Flags:
    empty
    '-' Flags
    '+' Flags
    '#' Flags
    '0' Flags
    ' ' Flags
Width:
    empty
    Integer
    '*'
Precision:
    empty
    '.'
    '.' Integer
    '.*'
Integer:
    Digit
    Digit Integer
Digit:
    '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
FormatChar:
    's'|'c'|'b'|'d'|'o'|'x'|'X'|'e'|'E'|'f'|'F'|'g'|'G'|'a'|'A'

Flags affect formatting depending on the specifier as follows.

Flag	Types affected	Semantics
'-'	numeric	Left justify the result in the field. It overrides any 0 flag.
'+'	numeric	Prefix positive numbers in a signed conversion with a +. It overrides any space flag.
'#'	integral ('o')	Add to precision as necessary so that the first digit of the octal formatting is a '0', even if both the argument and the Precision are zero.
'#'	integral ('x', 'X')	If non-zero, prefix result with 0x (0X).
'#'	floating	Always insert the decimal point and print trailing zeros.
'0'	numeric	Use leading zeros to pad rather than spaces (except for the floating point values nan and infinity). Ignore if there's a Precision.
' '	numeric	Prefix positive numbers in a signed conversion with a space.

Width

Specifies the minimum field width. If the width is a *, an additional argument of type int, preceding the actual argument, is taken as the width. If the width is negative, it is as if the - was given as a Flags character.

Precision

Gives the precision for numeric conversions. If the precision is a *, an additional argument of type int, preceding the actual argument, is taken as the precision. If it is negative, it is as if there was no Precision specifier.

FormatChar

's'

The corresponding argument is formatted in a manner consistent with its type:

bool

The result is 'true' or 'false'.

integral types

The %d format is used.

floating point types

The %g format is used.

string types

The result is the string converted to UTF-8. A Precision specifies the maximum number of characters to use in the result.

structs

If the struct defines a toString() method the result is the string returned from this function. Otherwise the result is StructName(field₀, field₁, ...) where field_n is the nth element formatted with the default format.

classes derived from Object

The result is the string returned from the class instance's .toString() method. A Precision specifies the maximum number of characters to use in the result.

unions

If the union defines a toString() method the result is the string returned from this function. Otherwise the result is the name of the union, without its contents.

non-string static and dynamic arrays

The result is [s₀, s₁, ...] where s_n is the nth element formatted with the default format.

associative arrays

The result is the equivalent of what the initializer would look like for the contents of the associative array, e.g.: ["red" : 10, "blue" : 20].

'c'

The corresponding argument must be a character type.

'b','d','o','x','X'

The corresponding argument must be an integral type and is formatted as an integer. If the argument is a signed type and the FormatChar is d it is converted to a signed string of characters, otherwise it is treated as unsigned. An argument of type bool is formatted as '1' or '0'. The base used is binary for b, octal for o, decimal for d, and hexadecimal for x or X. x formats using lower case letters, X uppercase. If there are fewer resulting digits than the Precision, leading zeros are used as necessary. If the Precision is 0 and the number is 0, no digits result.

'e','E'

A floating point number is formatted as one digit before the decimal point, Precision digits after, the FormatChar, ±, followed by at least a two digit exponent: d.dddddde±dd. If there is no Precision, six digits are generated after the decimal point. If the Precision is 0, no decimal point is generated.

'f','F'

A floating point number is formatted in decimal notation. The Precision specifies the number of digits generated after the decimal point. It defaults to six. At least one digit is generated before the decimal point. If the Precision is zero, no decimal point is generated.

'g','G'

A floating point number is formatted in either e or f format for g; E or F format for G. The f format is used if the exponent for an e format is greater than -5 and less than the Precision. The Precision specifies the number of significant digits, and defaults to six. Trailing zeros are elided after the decimal point, if the fractional part is zero then no decimal point is generated.

'a','A'

A floating point number is formatted in hexadecimal exponential notation 0xh.hhhhhhp±d. There is one hexadecimal digit before the decimal point, and as many after as specified by the Precision. If the Precision is zero, no decimal point is generated. If there is no Precision, as many hexadecimal digits as necessary to exactly represent the mantissa are generated. The exponent is written in as few digits as possible, but at least one, is in decimal, and represents a power of 2 as in h.hhhhhh*2^±d. The exponent for zero is zero. The hexadecimal digits, x and p are in upper case if the FormatChar is upper case.

Floating point NaN's are formatted as nan if the FormatChar is lower case, or NAN if upper. Floating point infinities are formatted as inf or infinity if the FormatChar is lower case, or INF or INFINITY if upper.

Examples:

import std.array;
import std.format;

void main()
{
    auto writer = appender!string();
    formattedWrite(writer, "%s is the ultimate %s.", 42, "answer");
    assert(writer.data == "42 is the ultimate answer.");
    // Clear the writer
    writer = appender!string();
    formattedWrite(writer, "Date: %2$s %1$s", "October", 5);
    assert(writer.data == "Date: 5 October");
}

The positional and non-positional styles can be mixed in the same format string. (POSIX leaves this behavior undefined.) The internal counter for non-positional parameters tracks the next parameter after the largest positional parameter already used.

Example using array and nested array formatting:

import std.stdio;

void main()
{
    writefln("My items are %(%s %).", [1,2,3]);
    writefln("My items are %(%s, %).", [1,2,3]);
}

The output is:

My items are 1 2 3.
My items are 1, 2, 3.

The trailing end of the sub-format string following the specifier for each item is interpreted as the array delimiter, and is therefore omitted following the last array item. The %| delimiter specifier may be used to indicate where the delimiter begins, so that the portion of the format string prior to it will be retained in the last array element:

import std.stdio;

void main()
{
    writefln("My items are %(-%s-%|, %).", [1,2,3]);
}

which gives the output:

My items are -1-, -2-, -3-.

These compound format specifiers may be nested in the case of a nested array argument:

import std.stdio;
void main() {
     auto mat = [[1, 2, 3],
                 [4, 5, 6],
                 [7, 8, 9]];

     writefln("%(%(%d %)\n%)", mat);
     writeln();

     writefln("[%(%(%d %)\n %)]", mat);
     writeln();

     writefln("[%([%(%d %)]%|\n %)]", mat);
     writeln();
}

The output is:

1 2 3
4 5 6
7 8 9


[1 2 3
 4 5 6
 7 8 9]


[[1 2 3]
 [4 5 6]
 [7 8 9]]

Inside a compound format specifier, strings and characters are escaped automatically. To avoid this behavior, add '-' flag to "%(".

import std.stdio;

void main()
{
    writefln("My friends are %s.", ["John", "Nancy"]);
    writefln("My friends are %(%s, %).", ["John", "Nancy"]);
    writefln("My friends are %-(%s, %).", ["John", "Nancy"]);
}

which gives the output:

My friends are ["John", "Nancy"].
My friends are "John", "Nancy".
My friends are John, Nancy.

uint formattedRead(R, Char, S...)(ref R r, const(Char)[] fmt, S args);

Reads characters from input range r, converts them according to fmt, and writes them to args.

Parameters:

R r	The range to read from.
const(Char)[] fmt	The format of the data to read.
S args	The drain of the data read.

Returns:

On success, the function returns the number of variables filled. This count can match the expected number of readings or fewer, even zero, if a matching failure happens.

Examples:

string s = "hello!124:34.5";
string a;
int b;
double c;
formattedRead(s, "%s!%s:%s", &a, &b, &c);
assert(a == "hello" && b == 124 && c == 34.5);

struct FormatSpec(Char) if (is(Unqual!Char == Char));

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

Examples:

import std.array;
auto a = appender!(string)();
auto fmt = "Number: %2.4e\nString: %s";
auto f = FormatSpec!char(fmt);

f.writeUpToNextSpec(a);

assert(a.data == "Number: ");
assert(f.trailing == "\nString: %s");
assert(f.spec == 'e');
assert(f.width == 2);
assert(f.precision == 4);

f.writeUpToNextSpec(a);

assert(a.data == "Number: \nString: ");
assert(f.trailing == "");
assert(f.spec == 's');

int width;

Minimum width, default 0.

int precision;

Precision. Its semantics depends on the argument type. For floating point numbers, precision dictates the number of decimals printed.

enum int DYNAMIC;

Special value for width and precision. DYNAMIC width or precision means that they were specified with '*' in the format string and are passed at runtime through the varargs.

enum int UNSPECIFIED;

Special value for precision, meaning the format specifier contained no explicit precision.

char spec;

The actual format specifier, 's' by default.

ubyte indexStart;

Index of the argument for positional parameters, from 1 to ubyte.max. (0 means not used).

ubyte indexEnd;

Index of the last argument for positional parameter range, from 1 to ubyte.max. (0 means not used).

bool flDash;

The format specifier contained a '-' (printf compatibility).

bool flZero;

The format specifier contained a '0' (printf compatibility).

bool flSpace;

The format specifier contained a ' ' (printf compatibility).

bool flPlus;

The format specifier contained a '+' (printf compatibility).

bool flHash;

The format specifier contained a '#' (printf compatibility).

const(Char)[] nested;

In case of a compound format specifier starting with "%(" and ending with "%)", nested contains the string contained within the two separators.

const(Char)[] sep;

In case of a compound format specifier, sep contains the string positioning after "%|".

const(Char)[] trailing;

trailing contains the rest of the format string.

pure @safe this(in Char[] fmt);

Construct a new FormatSpec using the format string fmt, no processing is done until needed.

FormatSpec!Char singleSpec(Char)(Char[] fmt);

Helper function that returns a FormatSpec for a single specifier given in fmt

Parameters:

Char[] fmt

A format specifier

Returns:

A FormatSpec with the specifier parsed.

Enforces giving only one specifier to the function.

Examples:

auto spec = singleSpec("%2.3e");

assert(spec.trailing == "");
assert(spec.spec == 'e');
assert(spec.width == 2);
assert(spec.precision == 3);

assertThrown(singleSpec(""));
assertThrown(singleSpec("2.3e"));
assertThrown(singleSpec("%2.3eTest"));

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(BooleanTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

bools are formatted as "true" or "false" with %s and as "1" or "0" with integral-specific format specs.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
formatValue(w, true, spec);

assert(w.data == "true");

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(Unqual!T == typeof(null)) && !is(T == enum) && !hasToString!(T, Char));

null literal is formatted as "null".

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
formatValue(w, null, spec);

assert(w.data == "null");

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(IntegralTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

Integrals are formatted like printf does.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%d");
formatValue(w, 1337, spec);

assert(w.data == "1337");

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(FloatingPointTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

Floating-point values are formatted like printf does.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%.1f");
formatValue(w, 1337.7, spec);

assert(w.data == "1337.7");

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(CharTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

Individual characters (char, wchar, or dchar) are formatted as Unicode characters with %s and as integers with integral-specific format specs.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%c");
formatValue(w, 'a', spec);

assert(w.data == "a");

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(StringTypeOf!T) && !is(StaticArrayTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

Strings are formatted like printf does.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
formatValue(w, "hello", spec);

assert(w.data == "hello");

void formatValue(Writer, T, Char)(Writer w, auto ref T obj, ref FormatSpec!Char f) if (is(StaticArrayTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

Static-size arrays are formatted as dynamic arrays.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
char[2] two = ['a', 'b'];
formatValue(w, two, spec);

assert(w.data == "ab");

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(DynamicArrayTypeOf!T) && !is(StringTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

Dynamic arrays are formatted as input ranges.

Specializations:

• void[] is formatted like ubyte[].
• Const array is converted to input range by removing its qualifier.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
auto two = [1, 2];
formatValue(w, two, spec);

assert(w.data == "[1, 2]");

void formatValue(Writer, T, Char)(Writer w, T obj, ref FormatSpec!Char f) if (is(AssocArrayTypeOf!T) && !is(T == enum) && !hasToString!(T, Char));

Associative arrays are formatted by using ':' and ", " as separators, and enclosed by '[' and ']'.

Parameters:

Writer w	The OutputRange to write to.
T obj	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
auto aa = ["H":"W"];
formatElement(w, aa, spec);

assert(w.data == "[\"H\":\"W\"]", w.data);

void formatValue(Writer, T, Char)(Writer w, T val, ref FormatSpec!Char f) if (is(T == class) && !is(T == enum));
void formatValue(Writer, T, Char)(Writer w, T val, ref FormatSpec!Char f) if (is(T == interface) && (hasToString!(T, Char) || !is(BuiltinTypeOf!T)) && !is(T == enum));
void formatValue(Writer, T, Char)(Writer w, auto ref T val, ref FormatSpec!Char f) if ((is(T == struct) || is(T == union)) && (hasToString!(T, Char) || !is(BuiltinTypeOf!T)) && !is(T == enum));

Aggregates (struct, union, class, and interface) are basically formatted by calling toString. toString should have one of the following signatures:

const void toString(scope void delegate(const(char)[]) sink, FormatSpec fmt);
const void toString(scope void delegate(const(char)[]) sink, string fmt);
const void toString(scope void delegate(const(char)[]) sink);
const string toString();

For the class objects which have input range interface,

• If the instance toString has overridden Object.toString, it is used.
• Otherwise, the objects are formatted as input range.

For the struct and union objects which does not have toString,

• If they have range interface, formatted as input range.
• Otherwise, they are formatted like Type(field1, filed2, ...).

Otherwise, are formatted just as their type name.

Examples:

formatValue allows to reuse existing format specifiers:

import std.format;

struct Point
{
    int x, y;

    void toString(scope void delegate(const(char)[]) sink,
                  FormatSpec!char fmt) const
    {
        sink("(");
        sink.formatValue(x, fmt);
        sink(",");
        sink.formatValue(y, fmt);
        sink(")");
    }
}

auto p = Point(16,11);
assert(format("%03d", p) == "(016,011)");
assert(format("%02x", p) == "(10,0b)");

Examples:

The following code compares the use of formatValue and formattedWrite.

import std.format;
import std.array : appender;

auto writer1 = appender!string();
writer1.formattedWrite("%08b", 42);

auto writer2 = appender!string();
auto f = singleSpec("%08b");
writer2.formatValue(42, f);

assert(writer1.data == writer2.data && writer1.data == "00101010");

void formatValue(Writer, T, Char)(Writer w, T val, ref FormatSpec!Char f) if (is(T == enum));

enum is formatted like its base value.

Parameters:

Writer w	The OutputRange to write to.
T val	The value to write.
FormatSpec!Char f	The FormatSpec defining how to write the value.

Examples:

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");

enum A { first, second, third }

formatElement(w, A.second, spec);

assert(w.data == "second");

void formatValue(Writer, T, Char)(Writer w, T val, ref FormatSpec!Char f) if (isPointer!T && !is(T == enum) && !hasToString!(T, Char));

Pointers are formatted as hex integers.

void formatValue(Writer, T, Char)(Writer w, scope T, ref FormatSpec!Char f) if (isDelegate!T);

Delegates are formatted by 'ReturnType delegate(Parameters) FunctionAttributes'

Examples:

import std.conv : to;

int i;

int foo(short k) @nogc
{
    return i + k;
}

int delegate(short) @nogc bar() nothrow
{
    return &foo;
}

assert(to!string(&bar) == "int delegate(short) @nogc delegate() nothrow");

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isInputRange!Range && is(Unqual!T == bool));

Reads a boolean value and returns it.

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isInputRange!Range && is(T == typeof(null)));

Reads null literal and returns it.

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isInputRange!Range && isIntegral!T && !is(T == enum));

Reads an integral value and returns it.

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isFloatingPoint!T && !is(T == enum));

Reads a floating-point value and returns it.

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isInputRange!Range && isSomeChar!T && !is(T == enum));

Reads one character and returns it.

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isInputRange!Range && is(StringTypeOf!T) && !isAggregateType!T && !is(T == enum));

Reads a string and returns it.

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isInputRange!Range && isArray!T && !is(StringTypeOf!T) && !isAggregateType!T && !is(T == enum));

Reads an array (except for string types) and returns it.

T unformatValue(T, Range, Char)(ref Range input, ref FormatSpec!Char spec) if (isInputRange!Range && isAssociativeArray!T && !is(T == enum));

Reads an associative array and returns it.

string format(Char, Args...)(in Char[] fmt, Args args);

Format arguments into a string.

Parameters:

Char[] fmt	Format string. For detailed specification, see std.format.formattedWrite.
Args args	Variadic list of arguments to format into returned string.

char[] sformat(Char, Args...)(char[] buf, in Char[] fmt, Args args);

Format arguments into buffer buf which must be large enough to hold the result. Throws RangeError if it is not.

Returns:

The slice of buf containing the formatted string.

sformat's current implementation has been replaced with xsformat's implementation in November 2012. This is seamless for most code, but it makes it so that the only argument that can be a format string is the first one, so any code which used multiple format strings has broken. Please change your calls to sformat accordingly.

e.g.:

sformat(buf, "key = %s", key, ", value = %s", value)

needs to be rewritten as:

sformat(buf, "key = %s, value = %s", key, value)