std.format.spec

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"