std.format - D Programming Language
Description: D Programming Language
Keywords: D programming language

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

This module implements the formatting functionality for strings and I/O. It's comparable to C99's vsprintf() and uses a similar format encoding scheme.
For an introductory look at std.format's capabilities and how to use this module see the dedicated DWiki article.
This module centers around two functions:

Function Name | Description
--- | ---
formattedRead | Reads values according to the format string from an InputRange.
formattedWrite | Formats its arguments according to the format string and puts them to an OutputRange.

Please see the documentation of function formattedWrite for a description of the format string.
Two functions have been added for convenience:

Function Name | Description
--- | ---
format | Returns a GC-allocated string with the formatting result.
sformat | Puts the formatting result into a preallocated array.

These two functions are publicly imported by std.string to be easily available.
The functions formatValue and unformatValue are used for the plumbing.
License:
Boost License 1.0.
Authors:
Walter Bright, Andrei Alexandrescu, and Kenji Hara

Source std/format.d

class `FormatException`: object.Exception;
  Signals a mismatch between a format and its corresponding argument.
  Examples:

      import std.exception : assertThrown;
      assertThrown!FormatException(format("%d", "foo"));

uint `formattedWrite`(alias fmt, Writer, A...)(auto ref Writer `w`, A `args`)
if (isSomeString!(typeof(fmt)));
uint `formattedWrite`(Writer, Char, A...)(auto ref Writer `w`, scope const Char[] `fmt`, A `args`);
  Interprets variadic argument list `args`, formats them according to `fmt`, and sends the resulting characters to `w`. The encoding of the output is the same as Char. The type Writer must satisfy std.range.primitives.isOutputRange!(Writer, Char).
  The variadic arguments are normally consumed in order. POSIX-style positional parameter syntax is also supported. Each argument is formatted into a sequence of chars according to the format specification, and the characters are passed to `w`. As many arguments as specified in the format string are consumed and formatted. If there are fewer arguments than format specifiers, a FormatException is thrown. If there are more remaining arguments than needed by the format specification, they are ignored but only if at least one argument was formatted.
  The format string supports the formatting of array and nested array elements via the grouping format specifiers %( and %). Each matching pair of %( and %) corresponds with a single array argument. The enclosed sub-format string is applied to individual array elements. The trailing portion of the sub-format string following the conversion specifier for the array element is interpreted as the array delimiter, and is therefore omitted following the last array element. The %| specifier may be used to explicitly indicate the start of the delimiter, so that the preceding portion of the string will be included following the last array element. (See below for explicit examples.)
  Parameters:

  Writer `w` | Output is sent to this writer. Typical output writers include std.array.Appender!string and std.stdio.LockingTextWriter.
  Char[] `fmt` | Format string.
  A `args` | Variadic argument list.

  Returns:
  Formatted number of arguments.
  Throws:
  Mismatched arguments and formats result in a FormatException being thrown.

  Format String Format strings consist of characters interspersed with format specifications. Characters are simply copied to the output (such as putc) after any necessary conversion to the corresponding UTF-8 sequence.

  The format string has the following grammar:

      FormatString:
          FormatStringItem*
      FormatStringItem:
          '%%'
          '%' Position Flags Width Separator Precision FormatChar
          '%(' FormatString '%)'
          '%-(' FormatString '%)'
          OtherCharacterExceptPercent
      Position:
          empty
          Integer '$'
      Flags:
          empty
          '-' Flags
          '+' Flags
          '#' Flags
          '0' Flags
          ' ' Flags
      Width:
          empty
          Integer
          '*'
      Separator:
          empty
          ','
          ',' '?'
          ',' '*' '?'
          ',' Integer '?'
          ',' '*'
          ',' Integer
      Precision:
          empty
          '.'
          '.' Integer
          '.*'
      Integer:
          Digit
          Digit Integer
      Digit:
          '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
      FormatChar:
          's'|'c'|'b'|'d'|'o'|'x'|'X'|'e'|'E'|'f'|'F'|'g'|'G'|'a'|'A'|'|'

  Flags affect formatting depending on the specifier as follows.
  Flag | Types affected | Semantics
  --- | --- | ---
  '-' | numeric, bool, null, char, string, enum, pointer | Left justify the result in the field. It overrides any 0 flag.
  '+' | numeric | Prefix positive numbers in a signed conversion with a +. It overrides any space flag.
  '#' | integral ('o') | Add to precision as necessary so that the first digit of the octal formatting is a '0', even if both the argument and the Precision are zero.
  '#' | integral ('x', 'X') | If non-zero, prefix result with 0x (0X).
  '#' | floating | Always insert the decimal point and print trailing zeros.
  '0' | numeric | Use leading zeros to pad rather than spaces (except for the floating point values nan and infinity). Ignore if there's a Precision.
  ' ' | numeric | Prefix positive numbers in a signed conversion with a space.

  Width
    Only used for numeric, bool, null, char, string, enum and pointer types. Specifies the minimum field width. If the width is a *, an additional argument of type int, preceding the actual argument, is taken as the width. If the width is negative, it is as if the - was given as a Flags character.
  Precision
    Gives the precision for numeric conversions. If the precision is a *, an additional argument of type int, preceding the actual argument, is taken as the precision. If it is negative, it is as if there was no Precision specifier.
  Separator
    Inserts the separator symbols ',' every X digits, from right to left, into numeric values to increase readability. The fractional part of floating point values inserts the separator from left to right. Entering an integer after the ',' allows to specify X. If a '*' is placed after the ',' then X is specified by an additional parameter to the format function. Adding a '?' after the ',' or X specifier allows to specify the separator character as an additional parameter.
  FormatChar
    's'
      The corresponding argument is formatted in a manner consistent with its type:
      bool
        The result is "true" or "false".
      integral types
        The %d format is used.
      floating point types
        The %g format is used.
      string types
        The result is the string converted to UTF-8. A Precision specifies the maximum number of characters to use in the result.
      structs
        If the struct defines a toString() method the result is the string returned from this function. Otherwise the result is StructName(field0, field1, ...) where fieldn is the nth element formatted with the default format.
      classes derived from Object
        The result is the string returned from the class instance's .toString() method. A Precision specifies the maximum number of characters to use in the result.
      unions
        If the union defines a toString() method the result is the string returned from this function. Otherwise the result is the name of the union, without its contents.
      non-string static and dynamic arrays
        The result is [s0, s1, ...] where sn is the nth element formatted with the default format.
      associative arrays
        The result is the equivalent of what the initializer would look like for the contents of the associative array, e.g.: ["red" : 10, "blue" : 20].
    'c'
      The corresponding argument must be a character type.
    'b','d','o','x','X'
      The corresponding argument must be an integral type and is formatted as an integer. If the argument is a signed type and the FormatChar is d it is converted to a signed string of characters, otherwise it is treated as unsigned. An argument of type bool is formatted as '1' or '0'. The base used is binary for b, octal for o, decimal for d, and hexadecimal for x or X. x formats using lower case letters, X uppercase. If there are fewer resulting digits than the Precision, leading zeros are used as necessary. If the Precision is 0 and the number is 0, no digits result.
    'e','E'
      A floating point number is formatted as one digit before the decimal point, Precision digits after, the FormatChar, ±, followed by at least a two digit exponent: d.dddddde±dd. If there is no Precision, six digits are generated after the decimal point. If the Precision is 0, no decimal point is generated.
    'f','F'
      A floating point number is formatted in decimal notation. The Precision specifies the number of digits generated after the decimal point. It defaults to six. At least one digit is generated before the decimal point. If the Precision is zero, no decimal point is generated.
    'g','G'
      A floating point number is formatted in either e or f format for g; E or F format for G. The f format is used if the exponent for an e format is greater than -5 and less than the Precision. The Precision specifies the number of significant digits, and defaults to six. Trailing zeros are elided after the decimal point, if the fractional part is zero then no decimal point is generated.
    'a','A'
      A floating point number is formatted in hexadecimal exponential notation 0xh.hhhhhhp±d. There is one hexadecimal digit before the decimal point, and as many after as specified by the Precision. If the Precision is zero, no decimal point is generated. If there is no Precision, as many hexadecimal digits as necessary to exactly represent the mantissa are generated. The exponent is written in as few digits as possible, but at least one, is in decimal, and represents a power of 2 as in h.hhhhhh*2±d. The exponent for zero is zero. The hexadecimal digits, x and p are in upper case if the FormatChar is upper case.
  Floating point NaN's are formatted as nan if the FormatChar is lower case, or NAN if upper. Floating point infinities are formatted as inf or infinity if the FormatChar is lower case, or INF or INFINITY if upper.
  The positional and non-positional styles can be mixed in the same format string. (POSIX leaves this behavior undefined.) The internal counter for non-positional parameters tracks the next parameter after the largest positional parameter already used.
  Example using array and nested array formatting:

      import std.stdio;

      void main()
      {
          writefln("My items are %(%s %).", [1,2,3]);
          writefln("My items are %(%s, %).", [1,2,3]);
      }

  The output is:

      My items are 1 2 3.
      My items are 1, 2, 3.

  The trailing end of the sub-format string following the specifier for each item is interpreted as the array delimiter, and is therefore omitted following the last array item. The %| delimiter specifier may be used to indicate where the delimiter begins, so that the portion of the format string prior to it will be retained in the last array element:

      import std.stdio;

      void main()
      {
          writefln("My items are %(-%s-%|, %).", [1,2,3]);
      }

  which gives the output:

      My items are -1-, -2-, -3-.

  These compound format specifiers may be nested in the case of a nested array argument:

      import std.stdio;
      void main() {
           auto mat = [[1, 2, 3],
                       [4, 5, 6],
                       [7, 8, 9]];

           writefln("%(%(%d %)\n%)", mat);
           writeln();

           writefln("[%(%(%d %)\n %)]", mat);
           writeln();

           writefln("[%([%(%d %)]%|\n %)]", mat);
           writeln();
      }

  The output is:

      1 2 3
      4 5 6
      7 8 9

      [1 2 3
       4 5 6
       7 8 9]

      [[1 2 3]
       [4 5 6]
       [7 8 9]]

  Inside a compound format specifier, strings and characters are escaped automatically. To avoid this behavior, add '-' flag to "%(".

      import std.stdio;

      void main()
      {
          writefln("My friends are %s.", ["John", "Nancy"]);
          writefln("My friends are %(%s, %).", ["John", "Nancy"]);
          writefln("My friends are %-(%s, %).", ["John", "Nancy"]);
      }

  which gives the output:

      My friends are ["John", "Nancy"].
      My friends are "John", "Nancy".
      My friends are John, Nancy.

  Examples:
  The format string can be checked at compile-time (see format for details):

      import std.array : appender;

      auto writer = appender!string();
      writer.formattedWrite!"%s is the ultimate %s."(42, "answer");
      writeln(writer[]); // "42 is the ultimate answer."

      // Clear the writer
      writer = appender!string();
      writer.formattedWrite!"Date: %2$s %1$s"("October", 5);
      writeln(writer[]); // "Date: 5 October"

  Examples:

      writeln(format("%,d", 1000)); // "1,000"
      writeln(format("%,f", 1234567.891011)); // "1,234,567.891011"
      writeln(format("%,?d", '?', 1000)); // "1?000"
      writeln(format("%,1d", 1000)); // "1,0,0,0"
      writeln(format("%,*d", 4, -12345)); // "-1,2345"
      writeln(format("%,*?d", 4, '_', -12345)); // "-1_2345"
      writeln(format("%,6?d", '_', -12345678)); // "-12_345678"
      assert(format("%12,3.3f", 1234.5678) == "   1,234.568", "'" ~
              format("%12,3.3f", 1234.5678) ~ "'");

uint `formattedRead`(alias fmt, R, S...)(auto ref R `r`, auto ref S `args`)
if (isSomeString!(typeof(fmt)));
uint `formattedRead`(R, Char, S...)(auto ref R `r`, const(Char)[] `fmt`, auto ref S `args`);
  Reads characters from input range `r`, converts them according to `fmt`, and writes them to `args`.
  Parameters:

  R `r` | The range to read from.
  const(Char)[] `fmt` | The format of the data to read.
  S `args` | The drain of the data read.

  Returns:
  On success, the function returns the number of variables filled. This count can match the expected number of readings or fewer, even zero, if a matching failure happens.
  Throws:
  A FormatException if S.length == 0 and `fmt` has format specifiers.
  Examples:
  The format string can be checked at compile-time (see format for details):

      string s = "hello!124:34.5";
      string a;
      int b;
      double c;
      s.formattedRead!"%s!%s:%s"(a, b, c);
      assert(a == "hello" && b == 124 && c == 34.5);

struct `FormatSpec`(Char) if (is(Unqual!Char == Char));
  A General handler for printf style format specifiers. Used for building more specific formatting functions.
  Examples:

      import std.array;
      auto a = appender!(string)();
      auto fmt = "Number: %6.4e\nString: %s";
      auto f = FormatSpec!char(fmt);

      writeln(f.writeUpToNextSpec(a)); // true

      writeln(a.data); // "Number: "
      writeln(f.trailing); // "\nString: %s"
      writeln(f.spec); // 'e'
      writeln(f.width); // 6
      writeln(f.precision); // 4

      writeln(f.writeUpToNextSpec(a)); // true

      writeln(a.data); // "Number: \nString: "
      writeln(f.trailing); // ""
      writeln(f.spec); // 's'

      writeln(f.writeUpToNextSpec(a)); // false
      writeln(a.data); // "Number: \nString: "

  int `width`;
    Minimum width, default 0.
  int `precision`;
    Precision. Its semantics depends on the argument type. For floating point numbers, precision dictates the number of decimals printed.
  int `separators`;
    Number of digits printed between separators.
  int `separatorCharPos`;
    Set to DYNAMIC when the separator character is supplied at runtime.
  dchar `separatorChar`;
    Character to insert between digits.
  enum int `DYNAMIC`;
    Special value for width and precision. `DYNAMIC` width or precision means that they were specified with '*' in the format string and are passed at runtime through the varargs.
  enum int `UNSPECIFIED`;
    Special value for precision, meaning the format specifier contained no explicit precision.
  char `spec`;
    The actual format specifier, 's' by default.
  ubyte `indexStart`;
    Index of the argument for positional parameters, from 1 to ubyte.max. (0 means not used).
  ubyte `indexEnd`;
    Index of the last argument for positional parameter range, from 1 to ubyte.max. (0 means not used).
  bool `flDash`;
    The format specifier contained a '-' (printf compatibility).
  bool `flZero`;
    The format specifier contained a '0' (printf compatibility).
  bool `flSpace`;
    The format specifier contained a ' ' (printf compatibility).
  bool `flPlus`;
    The format specifier contained a '+' (printf compatibility).
  bool `flHash`;
    The format specifier contained a '#' (printf compatibility).
  bool `flSeparator`;
    The format specifier contained a ','
  const(Char)[] `nested`;
    In case of a compound format specifier starting with "%(" and ending with "%)", _nested contains the string contained within the two separators.
  const(Char)[] `sep`;
    In case of a compound format specifier, _sep contains the string positioning after "%|". `sep` is null means no separator else `sep`.empty means 0 length separator.
  const(Char)[] `trailing`;
    _trailing contains the rest of the format string.
  pure @safe this(in Char[] `fmt`);
    Construct a new FormatSpec using the format string `fmt`, no processing is done until needed.
  scope bool `writeUpToNextSpec`(OutputRange)(ref OutputRange `writer`);
    Write the format string to an output range until the next format specifier is found and parse that format specifier.
    See FormatSpec for an example, how to use `writeUpToNextSpec`.
    Parameters:

    OutputRange `writer` | the output range

    Returns:
    True, when a format specifier is found.
    Throws:
    A FormatException when the found format specifier could not be parsed.
  const pure @safe string `toString`();
  const void `toString`(OutputRange)(ref OutputRange `writer`)
  if (isOutputRange!(OutputRange, char));
    Gives a string containing all of the member variables on their own line.
    Parameters:

    OutputRange `writer` | A char accepting output range

    Returns:
    A string when not using an output range; void otherwise.
FormatSpec!Char `singleSpec`(Char)(Char[] `fmt`);
  Helper function that returns a FormatSpec for a single specifier given in `fmt`.
  Parameters:

  Char[] `fmt` | A format specifier.

  Returns:
  A FormatSpec with the specifier parsed.
  Throws:
  A FormatException when more than one specifier is given or the specifier is malformed.
  Examples:

      import std.exception : assertThrown;
      auto spec = singleSpec("%2.3e");

      writeln(spec.trailing); // ""
      writeln(spec.spec); // 'e'
      writeln(spec.width); // 2
      writeln(spec.precision); // 3

      assertThrown!FormatException(singleSpec(""));
      assertThrown!FormatException(singleSpec("2.3e"));
      assertThrown!FormatException(singleSpec("%2.3eTest"));

void `formatValue`(Writer, T, Char)(auto ref Writer `w`, auto ref T `val`, ref scope const FormatSpec!Char `f`);
  Formats any value into Char accepting OutputRange, using the given FormatSpec.

  Aggregates struct, union, class, and interface are formatted by calling toString.

  toString should have one of the following signatures:

      void toString(Writer, Char)(ref Writer w, scope const ref FormatSpec!Char fmt)
      void toString(Writer)(ref Writer w)
      string toString();

  Where Writer is an output range which accepts characters. The template type does not have to be called Writer.
  The following overloads are also accepted for legacy reasons or for use in virtual functions. It's recommended that any new code forgo these overloads if possible for speed and attribute acceptance reasons.

      void toString(scope void delegate(const(char)[]) sink, const ref FormatSpec!char fmt);
      void toString(scope void delegate(const(char)[]) sink, string fmt);
      void toString(scope void delegate(const(char)[]) sink);

  For the class objects which have input range interface,
  - If the instance toString has overridden Object.toString, it is used.
  - Otherwise, the objects are formatted as input range.
  For the struct and union objects which does not have toString,
  - If they have range interface, formatted as input range.
  - Otherwise, they are formatted like Type(field1, filed2, ...).
  Otherwise, are formatted just as their type name.
  Parameters:

  Writer `w` | The output range to write to.
  T `val` | The value to write.
  FormatSpec!Char `f` | The std.format.FormatSpec defining how to write the value.

  Examples:
  The following code compares the use of `formatValue` and formattedWrite.

      import std.array : appender;

      auto writer1 = appender!string();
      writer1.formattedWrite("%08b", 42);

      auto writer2 = appender!string();
      auto f = singleSpec("%08b");
      writer2.formatValue(42, f);

      assert(writer1.data == writer2.data && writer1.data == "00101010");

  Examples:
  bools are formatted as "true" or "false" with %s and as 1 or 0 with integral-specific format specs.

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");
      formatValue(w, true, spec);

      writeln(w.data); // "true"

  Examples:
  null literal is formatted as "null".

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");
      formatValue(w, null, spec);

      writeln(w.data); // "null"

  Examples:
  Integrals are formatted like core.stdc.stdio.printf.

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%d");
      formatValue(w, 1337, spec);

      writeln(w.data); // "1337"

  Examples:
  Floating-point values are formatted like core.stdc.stdio.printf

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%.1f");
      formatValue(w, 1337.7, spec);

      writeln(w.data); // "1337.7"

  Examples:
  Individual characters (char, wchar, or dchar`) are formatted as Unicode characters with %s and as integers with integral-specific format specs.

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%c");
      formatValue(w, 'a', spec);

      writeln(w.data); // "a"

  Examples:
  Strings are formatted like core.stdc.stdio.printf

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");
      formatValue(w, "hello", spec);

      writeln(w.data); // "hello"

  Examples:
  Static-size arrays are formatted as dynamic arrays.

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");
      char[2] two = ['a', 'b'];
      formatValue(w, two, spec);

      writeln(w.data); // "ab"

  Examples:
  Dynamic arrays are formatted as input ranges.
  Specializations:
  - void[] is formatted like ubyte[].
  - Const array is converted to input range by removing its qualifier.

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");
      auto two = [1, 2];
      formatValue(w, two, spec);

      writeln(w.data); // "[1, 2]"

  Examples:
  Associative arrays are formatted by using ':' and ", " as separators, and enclosed by '[' and ']'.

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");
      auto aa = ["H":"W"];
      formatValue(w, aa, spec);

      writeln(w.data); // "[\"H\":\"W\"]"

  Examples:
  enums are formatted like their base value

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");

      enum A { first, second, third }

      formatValue(w, A.second, spec);

      writeln(w.data); // "second"

  Examples:
  Formatting a struct by defining a method toString, which takes an output range.
  It's recommended that any toString using output ranges use std.range.primitives.put rather than use the put method of the range directly.

      import std.array : appender;
      import std.range.primitives;

      static struct Point
      {
          int x, y;

          void toString(W)(ref W writer, scope const ref FormatSpec!char f)
          if (isOutputRange!(W, char))
          {
              // std.range.primitives.put
              put(writer, "(");
              formatValue(writer, x, f);
              put(writer, ",");
              formatValue(writer, y, f);
              put(writer, ")");
          }
      }

      auto w = appender!string();
      auto spec = singleSpec("%s");
      auto p = Point(16, 11);

      formatValue(w, p, spec);
      writeln(w.data); // "(16,11)"

  Examples:
  Another example of formatting a struct with a defined toString, this time using the scope delegate method.
  This method is now discouraged for non-virtual functions. If possible, please use the output range method instead.

      static struct Point
      {
          int x, y;

          void toString(scope void delegate(scope const(char)[]) @safe sink,
                        scope const FormatSpec!char fmt) const
          {
              sink("(");
              sink.formatValue(x, fmt);
              sink(",");
              sink.formatValue(y, fmt);
              sink(")");
          }
      }

      auto p = Point(16,11);
      writeln(format("%03d", p)); // "(016,011)"
      writeln(format("%02x", p)); // "(10,0b)"

  Examples:
  Pointers are formatted as hex integers.

      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");

      auto q = cast(void*) 0xFFEECCAA;
      formatValue(w, q, spec);

      writeln(w.data); // "FFEECCAA"

  Examples:
  SIMD vectors are formatted as arrays.

      import core.simd;
      import std.array : appender;
      auto w = appender!string();
      auto spec = singleSpec("%s");

      static if (is(float4))
      {
          version (X86) {}
          else
          {
              float4 f4;
              f4.array[0] = 1;
              f4.array[1] = 2;
              f4.array[2] = 3;
              f4.array[3] = 4;

              formatValue(w, f4, spec);
              writeln(w.data); // "[1, 2, 3, 4]"
          }
      }

  Examples:
  Delegates are formatted by ReturnType delegate(Parameters) FunctionAttributes
  Known Bug: Function attributes are not always correct. See Bugzilla 18269 for more details.

      import std.conv : to;

      int i;

      int foo(short k) @nogc
      {
          return i + k;
      }

      @system int delegate(short) @nogc bar() nothrow pure
      {
          int* p = new int(1);
          i = *p;
          return &foo;
      }

      writeln(to!string(&bar)); // "int delegate(short) @nogc delegate() pure nothrow @system"
      writeln(() @trusted
      { return bar()(3);
      }()); // 4

T `unformatValue`(T, Range, Char)(ref Range `input`, ref scope const FormatSpec!Char `spec`);
  Reads a value from the given input range according to spec and returns it as type T.
  Parameters:

  T | the type to return
  Range `input` | the input range to read from
  FormatSpec!Char `spec` | the FormatSpec to use when reading from `input`

  Returns:
  A value from `input` of type T
  Throws:
  A FormatException if `spec` cannot read a type T
  See Also:
  std.conv.parse and std.conv.to
  Examples:
  Booleans

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

      str = "1";
      spec = singleSpec("%d");
      assert(unformatValue!bool(str, spec));

  Examples:
  Null values

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

  Examples:
  Integrals

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

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

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

  Examples:
  Floating point numbers

      import std.math : isClose;

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

  Examples:
  Character input ranges

      auto str = "aaa";
      auto spec = singleSpec("%s");
      writeln(str.unformatValue!char(spec)); // 'a'

      // Using a numerical format spec reads a Unicode value from a string
      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 and static arrays

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

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

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

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

  Examples:
  Associative arrays

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

typeof(fmt) `format`(alias fmt, Args...)(Args `args`)
if (isSomeString!(typeof(fmt)));
immutable(Char)[] `format`(Char, Args...)(in Char[] `fmt`, Args `args`)
if (isSomeChar!Char);
  Format arguments into a string.
  If the format string is fixed, passing it as a template parameter checks the type correctness of the parameters at compile-time. This also can result in better performance.
  Parameters:

  Char[] `fmt` | Format string. For detailed specification, see formattedWrite.
  Args `args` | Variadic list of arguments to format into returned string.

  Throws:
  if the number of arguments doesn't match the number of format parameters and vice-versa.
  Examples:
  Type checking can be done when fmt is known at compile-time:

      auto s = format!"%s is %s"("Pi", 3.14);
      writeln(s); // "Pi is 3.14"

      static assert(!__traits(compiles, {s = format!"%l"();}));     // missing arg
      static assert(!__traits(compiles, {s = format!""(404);}));    // surplus arg
      static assert(!__traits(compiles, {s = format!"%d"(4.03);})); // incompatible arg

char[] `sformat`(alias fmt, Args...)(char[] `buf`, Args `args`)
if (isSomeString!(typeof(fmt)));
char[] `sformat`(Char, Args...)(return scope char[] `buf`, scope const(Char)[] `fmt`, Args `args`);
  Format arguments into buffer buf which must be large enough to hold the result.
  Returns:
  The slice of `buf` containing the formatted string.
  Throws:
  A RangeError if `buf` isn't large enough to hold the formatted string.
  A FormatException if the length of `args` is different than the number of format specifiers in `fmt`.
  Examples:
  The format string can be checked at compile-time (see format for details):

      char[10] buf;

      writeln(buf[].sformat!"foo%s"('C')); // "fooC"
      writeln(sformat(buf[], "%s foo", "bar")); // "bar foo"

Copyright © 1999-2021 by the D Language Foundation | Page generated by Ddoc on Thu Mar 11 10:56:38 2021