Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - 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.spec

This is a submodule of std.format.
It centers around a struct called FormatSpec, which takes a format string and provides tools for parsing this string. Additionally this module contains a function singleSpec which helps treating a single format specifier.
License:
Boost License 1.0.
Authors:
Walter Bright, Andrei Alexandrescu, and Kenji Hara

Source std/format/spec.d

struct `FormatSpec`(Char) if (is(Unqual!Char == Char));
  A general handler for format strings.
  This handler centers around the function writeUpToNextSpec, which parses the format string until the next format specifier is found. After the call, it provides information about this format specifier in its numerous variables.
  Parameters:

  Char | the character type of the format string

  Examples:

      import std.array : appender;

      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 semantic depends on the format character.
    See format string for more details. Default: UNSPECIFIED.
  int `separators`;
    Number of elements between separators.
    Default: UNSPECIFIED.
  bool `dynamicSeparatorChar`;
    The separator charactar is supplied at runtime.
    Default: false.
  int `separatorCharPos`();
  void `separatorCharPos`(int `value`);
    Set to DYNAMIC when the separator character is supplied at runtime.
    Default: UNSPECIFIED.
    Warning: `separatorCharPos` is deprecated. It will be removed in 2.107.0. Please use dynamicSeparatorChar instead.
  dchar `separatorChar`;
    Character to use as separator.
    Default: ','.
  enum int `DYNAMIC`;
    Special value for width, precision and separators.
    It flags that these values will be passed at runtime through variadic arguments.
  enum int `UNSPECIFIED`;
    Special value for precision and separators.
    It flags that these values have not been specified.
  char `spec`;
    The format character.
    Default: 's'.
  ubyte `indexStart`;
    Index of the argument for positional parameters.
    Counting starts with 1. Set to 0 if not used. Default: 0.
  ubyte `indexEnd`;
    Index of the last argument for positional parameter ranges.
    Counting starts with 1. Set to 0 if not used. Default: 0.
  bool `flDash`;
    The format specifier contained a '-'.
  bool `flZero`;
    The format specifier contained a '0'.
  bool `flSpace`;
    The format specifier contained a space.
  bool `flPlus`;
    The format specifier contained a '+'.
  bool `flHash`;
    The format specifier contained a '#'.
  bool `flEqual`;
    The format specifier contained a '='.
  bool `flSeparator`;
    The format specifier contained a ','.
  const(Char)[] `nested`;
    The inner format string of a nested format specifier.
  const(Char)[] `sep`;
    The separator of a nested format specifier.
    null means, there is no separator. empty, but not null, means zero length separator.
  const(Char)[] `trailing`;
    Contains the part of the format string, that has not yet been parsed.
  enum immutable(Char)[] `seqBefore`;
    Sequence "[" inserted before each range or range like structure.
  enum immutable(Char)[] `seqAfter`;
    Sequence "]" inserted after each range or range like structure.
  enum immutable(Char)[] `keySeparator`;
    Sequence ":" inserted between element key and element value of an associative array.
  enum immutable(Char)[] `seqSeparator`;
    Sequence ", " inserted between elements of a range, a range like structure or the elements of an associative array.
  pure @safe this(in Char[] `fmt`);
    Creates a new FormatSpec.
    The string is lazily evaluated. That means, nothing is done, until writeUpToNextSpec is called.
    Parameters:

    Char[] `fmt` | a format string

  scope bool `writeUpToNextSpec`(OutputRange)(ref OutputRange `writer`);
    Writes the format string to an output range until the next format specifier is found and parse that format specifier.
    See the description of format strings for more details about the format specifier.
    Parameters:

    OutputRange `writer` | an output range, where the format string is written to
    OutputRange | type of the output range

    Returns:
    True, if a format specifier is found and false, if the end of the format string has been reached.
    Throws:
    A FormatException when parsing the format specifier did not succeed.
  const pure @safe string `toString`();
    Provides a string representation.
    Returns:
    The string representation.
  const void `toString`(OutputRange)(ref OutputRange `writer`)
  if (isOutputRange!(OutputRange, char));
    Writes a string representation to an output range.
    Parameters:

    OutputRange `writer` | an output range, where the representation is written to
    OutputRange | type of the output range

FormatSpec!Char `singleSpec`(Char)(Char[] `fmt`);
  Helper function that returns a FormatSpec for a single format specifier.
  Parameters:

  Char[] `fmt` | a format string containing a single format specifier
  Char | character type of `fmt`

  Returns:
  A FormatSpec with the format specifier parsed.
  Throws:
  A FormatException when the format string contains no format specifier or more than a single format specifier or when the format specifier is malformed.
  Examples:

      import std.array : appender;
      import std.format.write : formatValue;

      auto spec = singleSpec("%10.3e");
      auto writer = appender!string();
      writer.formatValue(42.0, spec);

      writeln(writer.data); // " 4.200e+01"

Copyright © 1999-2023 by the D Language Foundation | Page generated by Ddoc on Fri Sep 1 19:45:57 2023