std.format

FormatString:
    FormatStringItem FormatString
FormatStringItem:
    Character
    FormatSpecifier
FormatSpecifier:
    '%' Parameters FormatIndicator


FormatIndicator:
    FormatCharacter
    CompoundIndicator
FormatCharacter:
    see remark below
CompoundIndicator:
    '(' FormatString '%)'
    '(' FormatString '%|' Delimiter '%)'
Delimiter
    empty
    Character Delimiter


Parameters:
    Position Flags Width Precision Separator
Position:
    empty
    Integer '$'
    Integer ':' Integer '$'
    Integer ':' '$'
Flags:
    empty
    Flag Flags
Flag:
    '-'|'+'|' '|'0'|'#'|'='
Width:
    OptionalPositionalInteger
Precision:
    empty
    '.' OptionalPositionalInteger
Separator:
    empty
    ',' OptionalInteger
    ',' OptionalInteger '?'
OptionalInteger:
    empty
    Integer
    '*'
OptionalPositionalInteger:
    OptionalInteger
    '*' Integer '$'


Character
    '%%'
    AnyCharacterExceptPercent
Integer:
    NonZeroDigit Digits
Digits:
    empty
    Digit Digits
NonZeroDigit:
    '1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
Digit:
    '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'

// Easiest way is to use `%s` everywhere:
// "I got 30 eggs for 5.27 euros."
writeln(format("I got %s %s for %s euros.", 30, "eggs", 5.27));

// Other format characters provide more control:
// "I got 11110 65676773 for 5.270000 euros."
writeln(format("I got %b %(%X%) for %f euros.", 30, "eggs", 5.27));

/*
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:
 */
    writeln(format("My items are %(%s %).", [1, 2, 3])); // "My items are 1 2 3."
    writeln(format("My items are %(%s, %).", [1, 2, 3])); // "My items are 1, 2, 3."

/*
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:
 */
    writeln(format("My items are %(-%s-%|, %).", [1, 2, 3])); // "My items are -1-, -2-, -3-."

/*
These compound format specifiers may be nested in the case of a
nested array argument:
 */
    auto mat = [[1, 2, 3],
                [4, 5, 6],
                [7, 8, 9]];

    assert(format("%(%(%d %) - %)", mat), "1 2 3 - 4 5 6 - 7 8 9");
    assert(format("[%(%(%d %) - %)]", mat), "[1 2 3 - 4 5 6 - 7 8 9]");
    assert(format("[%([%(%d %)]%| - %)]", mat), "[1 2 3] - [4 5 6] - [7 8 9]");

/*
Strings and characters are escaped automatically inside compound
format specifiers. To avoid this behavior, use "%-(" instead of "%(":
 */
    // `My friends are ["John", "Nancy"].`
    writeln(format("My friends are %s.", ["John", "Nancy"]));
    // `My friends are "John", "Nancy".`
    writeln(format("My friends are %(%s, %).", ["John", "Nancy"]));
    // `My friends are John, Nancy.`
    writeln(format("My friends are %-(%s, %).", ["John", "Nancy"]));

// Flags can be used to influence to outcome:
writeln(format("%g != %+#g", 3.14, 3.14)); // "3.14 != +3.14000"

// Width and precision help to arrange the formatted result:
writeln(format(">%10.2f<", 1234.56789)); // ">   1234.57<"

// Numbers can be grouped:
writeln(format("%,4d", int.max)); // "21,4748,3647"

// It's possible to specify the position of an argument:
writeln(format("%3$s %1$s", 3, 17, 5)); // "5 3"

// Width as argument
writeln(format(">%*s<", 10, "abc")); // ">       abc<"

// Precision as argument
writeln(format(">%.*f<", 5, 123.2)); // ">123.20000<"

// Grouping as argument
writeln(format("%,*d", 1, int.max)); // "2,1,4,7,4,8,3,6,4,7"

// Grouping separator as argument
writeln(format("%,3?d", '_', int.max)); // "2_147_483_647"

// All at once
writeln(format("%*.*,*?d", 20, 15, 6, '/', int.max)); // "   000/002147/483647"

class FormatException: object.Exception;

Signals an issue encountered while formatting.

Examples:

import std.exception : assertThrown;

assertThrown!FormatException(format("%d", "foo"));

pure nothrow @nogc @safe this();

Generic constructor.

pure nothrow @nogc @safe this(string msg, string fn = __FILE__, size_t ln = __LINE__, Throwable next = null);

Creates a new instance of FormatException.

Parameters:

string msg	message of the exception
string fn	file name of the file where the exception was created (optional)
size_t ln	line number of the file where the exception was created (optional)
Throwable next	for internal use, should always be null (optional)

immutable(Char)[] format(Char, Args...)(in Char[] fmt, Args args)
if (isSomeChar!Char);

typeof(fmt) format(alias fmt, Args...)(Args args)
if (isSomeString!(typeof(fmt)));

Converts its arguments according to a format string into a string.

The second version of format takes the format string as template argument. In this case, it is checked for consistency at compile-time and produces slightly faster code, because the length of the output buffer can be estimated in advance.

Parameters:

Char[] fmt	a format string
Args args	a variadic list of arguments to be formatted
Char	character type of fmt
Args	a variadic list of types of the arguments

Returns:

The formatted string.

Throws:

A FormatException if formatting did not succeed.

See Also:

sformat for a variant, that tries to avoid garbage collection.

Examples:

writeln(format("Here are %d %s.", 3, "apples")); // "Here are 3 apples."

writeln("Increase: %7.2f %%".format(17.4285)); // "Increase:   17.43 %"

Examples:

The format string can be checked at compile-time:

auto s = format!"%s is %s"("Pi", 3.14);
writeln(s); // "Pi is 3.14"

// This line doesn't compile, because 3.14 cannot be formatted with %d:
// s = format!"%s is %d"("Pi", 3.14);

char[] sformat(Char, Args...)(return scope char[] buf, scope const(Char)[] fmt, Args args);

char[] sformat(alias fmt, Args...)(char[] buf, Args args)
if (isSomeString!(typeof(fmt)));

Converts its arguments according to a format string into a buffer. The buffer has to be large enough to hold the formatted string.

The second version of sformat takes the format string as a template argument. In this case, it is checked for consistency at compile-time.

Parameters:

char[] buf	the buffer where the formatted string should go
const(Char)[] fmt	a format string
Args args	a variadic list of arguments to be formatted
Char	character type of fmt
Args	a variadic list of types of the arguments

Returns:

A slice of buf containing the formatted string.

Throws:

A RangeError if buf isn't large enough to hold the formatted string and a FormatException if formatting did not succeed.

Note In theory this function should be @nogc. But with the current implementation there are some cases where allocations occur:

• An exception is thrown.
• A custom toString function of a compound type allocates.

Examples:

char[20] buf;
writeln(sformat(buf[], "Here are %d %s.", 3, "apples")); // "Here are 3 apples."

writeln(buf[].sformat("Increase: %7.2f %%", 17.4285)); // "Increase:   17.43 %"

Examples:

The format string can be checked at compile-time:

char[20] buf;

writeln(sformat!"Here are %d %s."(buf[], 3, "apples")); // "Here are 3 apples."

// This line doesn't compile, because 3.14 cannot be formatted with %d:
// writeln(sformat!"Here are %d %s."(buf[], 3.14, "apples"));