If you spot a problem with this page, click here to create a Bugzilla issue.

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

License:

Boost License 1.0.

Authors:

Walter Bright, Andrei Alexandrescu, and Kenji Hara

Source std/format/read.d

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.

Library Reference

std.format.read