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

This is a submodule of std.format.
It provides two functions for reading formatted input: unformatValue and formattedRead. The former reads a single value. The latter reads several values at once and matches the characters found between format specifiers.
Parameters are ignored, except for the ones consisting of a single '*'. See formattedRead for more information.
A space outside of a format specifier has a special meaning: it matches any sequence of whitespace characters, not just a single space.
The following combinations of format characters and types are available:
s c d, u, b, o, x, X e, E, f, g, G r compound
bool yes  —  yes  —   —   — 
null yes  —   —   —   —   — 
integer yes  —  yes  —  yes  — 
floating point yes  —   —  yes yes  — 
character yes yes yes  —   —   — 
string yes  —   —   —   —  yes
array yes  —   —   —   —  yes
associative array yes  —   —   —   —  yes
Below are highlighted examples on how these combinations are used with unformatValue, however, they apply for formattedRead also
Authors:
Examples:
Booleans
import std.format.spec : singleSpec;

auto str = "false";
auto spec = singleSpec("%s");
writeln(str.unformatValue!bool(spec)); // false

str = "1";
spec = singleSpec("%d");
writeln(str.unformatValue!bool(spec)); // true
Examples:
Null values
import std.format.spec : singleSpec;

auto str = "null";
auto spec = singleSpec("%s");
writeln(str.unformatValue!(typeof(null))(spec)); // null
Examples:
Integrals
import std.format.spec : singleSpec;

// signed decimal values
auto str = "123";
auto spec = singleSpec("%s");
writeln(str.unformatValue!int(spec)); // 123

// hexadecimal values
str = "ABC";
spec = singleSpec("%X");
writeln(str.unformatValue!int(spec)); // 2748

// octal values
str = "11610";
spec = singleSpec("%o");
writeln(str.unformatValue!int(spec)); // 5000

// raw read, depends on endianess
str = "\x75\x01";
spec = singleSpec("%r");
auto result = str.unformatValue!short(spec);
assert(result == 373 /* little endian */ || result == 29953 /* big endian */ );
Examples:
Floating point numbers
import std.format.spec : singleSpec;
import std.math.operations : isClose;

// natural notation
auto str = "123.456";
auto spec = singleSpec("%s");
assert(str.unformatValue!double(spec).isClose(123.456));

// scientific notation
str = "1e17";
spec = singleSpec("%e");
assert(str.unformatValue!double(spec).isClose(1e17));

// raw read, depends on endianess
str = "\x40\x00\x00\xBF";
spec = singleSpec("%r");
auto result = str.unformatValue!float(spec);
assert(isClose(result, -0.5) /* little endian */ || isClose(result, 2.0) /* big endian */ );
Examples:
Characters
import std.format.spec : singleSpec;

// only the first character is read
auto str = "abc";
auto spec = singleSpec("%s");
writeln(str.unformatValue!char(spec)); // 'a'

// using a numerical format character treats the read number as unicode code point
str = "65";
spec = singleSpec("%d");
writeln(str.unformatValue!char(spec)); // 'A'

str = "41";
spec = singleSpec("%x");
writeln(str.unformatValue!char(spec)); // 'A'

str = "10003";
spec = singleSpec("%d");
writeln(str.unformatValue!dchar(spec)); // '✓'
Examples:
Arrays
import std.format.spec : singleSpec;

// string value
string str = "aaa";
auto spec = singleSpec("%s");
writeln(str.unformatValue!(dchar[])(spec)); // "aaa"d

// fixed size array with characters
str = "aaa";
spec = singleSpec("%s");
dchar[3] ret = ['a', 'a', 'a'];
writeln(str.unformatValue!(dchar[3])(spec)); // ret

// dynamic array
str = "[1, 2, 3, 4]";
spec = singleSpec("%s");
writeln(str.unformatValue!(int[])(spec)); // [1, 2, 3, 4]

// fixed size array with integers
str = "[1, 2, 3, 4]";
spec = singleSpec("%s");
int[4] ret2 = [1, 2, 3, 4];
writeln(str.unformatValue!(int[4])(spec)); // ret2

// compound specifiers can be used for more control
str = "1,2,3";
spec = singleSpec("%(%s,%)");
writeln(str.unformatValue!(int[])(spec)); // [1, 2, 3]

str = "cool";
spec = singleSpec("%(%c%)");
writeln(str.unformatValue!(char[])(spec)); // ['c', 'o', 'o', 'l']
Examples:
Associative arrays
import std.format.spec : singleSpec;

// as single value
auto str = `["one": 1, "two": 2]`;
auto spec = singleSpec("%s");
writeln(str.unformatValue!(int[string])(spec)); // ["one":1, "two":2]

// with compound specifier for more control
str = "1/1, 2/4, 3/9";
spec = singleSpec("%(%d/%d%|, %)");
writeln(str.unformatValue!(int[int])(spec)); // [1:1, 2:4, 3:9]
uint formattedRead(Range, Char, Args...)(auto ref Range r, const(Char)[] fmt, auto ref Args args);

uint formattedRead(alias fmt, Range, Args...)(auto ref Range r, auto ref Args args)
if (isSomeString!(typeof(fmt)));
Reads an input range according to a format string and stores the read values into its arguments.
Format specifiers with format character 'd', 'u' and 'c' can take a '*' parameter for skipping values.
The second version of formattedRead takes the format string as template argument. In this case, it is checked for consistency at compile-time.
Parameters:
Range r an input range, where the formatted input is read from
const(Char)[] fmt a format string
Args args a variadic list of arguments where the read values are stored
Range the type of the input range r
Char the character type used for fmt
Args a variadic list of types of the arguments
Returns:
The number of variables filled. If the input range r ends early, this number will be less than the number of variables provided.
Throws:
A FormatException if reading did not succeed.

Note For backward compatibility the arguments args can be given as pointers to that variable, but it is not recommended to do so, because this option might be removed in the future.

Examples:
string object;
char cmp;
int value;

writeln(formattedRead("angle < 36", "%s %c %d", object, cmp, value)); // 3
writeln(object); // "angle"
writeln(cmp); // '<'
writeln(value); // 36

// reading may end early:
writeln(formattedRead("length >", "%s %c %d", object, cmp, value)); // 2
writeln(object); // "length"
writeln(cmp); // '>'
// value is not changed:
writeln(value); // 36
Examples:
The format string can be checked at compile-time:
string a;
int b;
double c;

writeln("hello!124:34.5".formattedRead!"%s!%s:%s"(a, b, c)); // 3
writeln(a); // "hello"
writeln(b); // 124
writeln(c); // 34.5
Examples:
Skipping values
string item;
double amount;

writeln("orange: (12%) 15.25".formattedRead("%s: (%*d%%) %f", item, amount)); // 2
writeln(item); // "orange"
writeln(amount); // 15.25

// can also be used with tuples
import std.typecons : Tuple;

Tuple!(int, float) t;
char[] line = "1 7643 2.125".dup;
formattedRead(line, "%s %*u %s", t);
assert(t[0] == 1 && t[1] == 2.125);
T unformatValue(T, Range, Char)(ref Range input, ref scope const FormatSpec!Char spec);
Reads a value from the given input range and converts it according to a format specifier.
Parameters:
Range input the input range, to read from
FormatSpec!Char spec a format string
T type to return
Range the type of the input range input
Char the character type used for spec
Returns:
A value from input of type T.
Throws:
A FormatException if reading did not succeed.
Examples:
import std.format.spec : singleSpec;

string s = "42";
auto spec = singleSpec("%s");
writeln(unformatValue!int(s, spec)); // 42