Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
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
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.
  See Also:
  std.conv.parse and std.conv.to
  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 Sat Sep 10 10:04:23 2022