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 a local clone.

std.format.spec

This is a submodule of std.format.
It centers around a struct called FormatSpec, which takes a format string and provides tools for parsing this string. Additionally this module contains a function singleSpec which helps treating a single format specifier.
Authors:
struct FormatSpec(Char) if (is(Unqual!Char == Char));
A general handler for format strings.
This handler centers around the function writeUpToNextSpec, which parses the format string until the next format specifier is found. After the call, it provides information about this format specifier in its numerous variables.
Parameters:
Char the character type of the format string
Examples:
import std.array : appender;

auto a = appender!(string)();
auto fmt = "Number: %6.4e\nString: %s";
auto f = FormatSpec!char(fmt);

writeln(f.writeUpToNextSpec(a)); // true

writeln(a.data); // "Number: "
writeln(f.trailing); // "\nString: %s"
writeln(f.spec); // 'e'
writeln(f.width); // 6
writeln(f.precision); // 4

writeln(f.writeUpToNextSpec(a)); // true

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

writeln(f.writeUpToNextSpec(a)); // false

writeln(a.data); // "Number: \nString: "
int width;
Minimum width.
Default: 0.
int precision;
Precision. Its semantic depends on the format character.
See format string for more details. Default: UNSPECIFIED.
int separators;
Number of elements between separators.
Default: UNSPECIFIED.
bool dynamicSeparatorChar;
The separator charactar is supplied at runtime.
Default: false.
int separatorCharPos();

void separatorCharPos(int value);
Set to DYNAMIC when the separator character is supplied at runtime.
Default: UNSPECIFIED.
Warning: separatorCharPos is deprecated. It will be removed in 2.107.0. Please use dynamicSeparatorChar instead.
dchar separatorChar;
Character to use as separator.
Default: ','.
enum int DYNAMIC;
Special value for width, precision and separators.
It flags that these values will be passed at runtime through variadic arguments.
enum int UNSPECIFIED;
Special value for precision and separators.
It flags that these values have not been specified.
char spec;
The format character.
Default: 's'.
ubyte indexStart;
Index of the argument for positional parameters.
Counting starts with 1. Set to 0 if not used. Default: 0.
ubyte indexEnd;
Index of the last argument for positional parameter ranges.
Counting starts with 1. Set to 0 if not used. Default: 0.
bool flDash;
The format specifier contained a '-'.
bool flZero;
The format specifier contained a '0'.
bool flSpace;
The format specifier contained a space.
bool flPlus;
The format specifier contained a '+'.
bool flHash;
The format specifier contained a '#'.
bool flEqual;
The format specifier contained a '='.
bool flSeparator;
The format specifier contained a ','.
const(Char)[] nested;
The inner format string of a nested format specifier.
const(Char)[] sep;
The separator of a nested format specifier.
null means, there is no separator. empty, but not null, means zero length separator.
const(Char)[] trailing;
Contains the part of the format string, that has not yet been parsed.
enum immutable(Char)[] seqBefore;
Sequence "[" inserted before each range or range like structure.
enum immutable(Char)[] seqAfter;
Sequence "]" inserted after each range or range like structure.
enum immutable(Char)[] keySeparator;
Sequence ":" inserted between element key and element value of an associative array.
enum immutable(Char)[] seqSeparator;
Sequence ", " inserted between elements of a range, a range like structure or the elements of an associative array.
pure @safe this(in Char[] fmt);
Creates a new FormatSpec.
The string is lazily evaluated. That means, nothing is done, until writeUpToNextSpec is called.
Parameters:
Char[] fmt a format string
scope bool writeUpToNextSpec(OutputRange)(ref OutputRange writer);
Writes the format string to an output range until the next format specifier is found and parse that format specifier.
See the description of format strings for more details about the format specifier.
Parameters:
OutputRange writer an output range, where the format string is written to
OutputRange type of the output range
Returns:
True, if a format specifier is found and false, if the end of the format string has been reached.
Throws:
A FormatException when parsing the format specifier did not succeed.
const pure @safe string toString();
Provides a string representation.
Returns:
The string representation.
const void toString(OutputRange)(ref OutputRange writer)
if (isOutputRange!(OutputRange, char));
Writes a string representation to an output range.
Parameters:
OutputRange writer an output range, where the representation is written to
OutputRange type of the output range
FormatSpec!Char singleSpec(Char)(Char[] fmt);
Helper function that returns a FormatSpec for a single format specifier.
Parameters:
Char[] fmt a format string containing a single format specifier
Char character type of fmt
Returns:
A FormatSpec with the format specifier parsed.
Throws:
A FormatException when the format string contains no format specifier or more than a single format specifier or when the format specifier is malformed.
Examples:
import std.array : appender;
import std.format.write : formatValue;

auto spec = singleSpec("%10.3e");
auto writer = appender!string();
writer.formatValue(42.0, spec);

writeln(writer.data); // " 4.200e+01"