View source code
Display the source code in std/format/read.d from which this page was generated on github.
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 local clone.

Module 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

Example

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

Example

Null values

import std.format.spec : singleSpec;

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

Example

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 */ );

Example

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 */ );

Example

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)); // '✓'

Example

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']

Example

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]

Functions

NameDescription
formattedRead(r, fmt, args) Reads an input range according to a format string and stores the read values into its arguments.
unformatValue(input, spec) Reads a value from the given input range and converts it according to a format specifier.

Authors

Walter Bright, Andrei Alexandrescu, and Kenji Hara

License

Boost License 1.0.