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:
Below are highlighted examples on how these combinations are used
with unformatValue, however, they apply for formattedRead also
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 |
License:
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 Ranger
, const(Char)[]fmt
, auto ref Argsargs
);
uintformattedRead
(alias fmt, Range, Args...)(auto ref Ranger
, auto ref Argsargs
)
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 ranger
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 valuesstring 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 Rangeinput
, ref scope const FormatSpec!Charspec
); - 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 frominput
of type T.Throws:A FormatException if reading did not succeed.See Also:Examples:import std.format.spec : singleSpec; string s = "42"; auto spec = singleSpec("%s"); writeln(unformatValue!int(s, spec)); // 42
Copyright © 1999-2022 by the D Language Foundation | Page generated by
Ddoc on (no date time)