Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Wiki
  - GitHub
  - Issues
  - Foundation
  - Donate
- Resources
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - 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.stdio

Standard I/O functions that extend core.stdc.`stdio`. core.stdc.`stdio` is publically imported when importing std.`stdio`.

Source: std/stdio.d

License:
Boost License 1.0.
Authors:
Walter Bright, Andrei Alexandrescu, Alex Rønne Petersen

alias `KeepTerminator` = std.typecons.Flag!"keepTerminator".Flag;
  If flag `KeepTerminator` is set to `KeepTerminator`.yes, then the delimiter is included in the strings returned.
struct `File`;
  Encapsulates a FILE*. Generally D does not attempt to provide thin wrappers over equivalent functions in the C standard library, but manipulating FILE* values directly is unsafe and error-prone in many ways. The `File` type ensures safe manipulation, automatic file closing, and a lot of convenience.
  The underlying FILE* handle is maintained in a reference-counted manner, such that as soon as the last `File` variable bound to a given FILE* goes out of scope, the underlying FILE* is automatically closed.

  Example:

      // test.d
      void main(string[] args)
      {
          auto f = File("test.txt", "w"); // open for writing
          f.write("Hello");
          if (args.length > 1)
          {
              auto g = f; // now g and f write to the same file
                          // internal reference count is 2
              g.write(", ", args[1]);
              // g exits scope, reference count decreases to 1
          }
          f.writeln("!");
          // f exits scope, reference count falls to zero,
          // underlying $(D FILE*) is closed.
      }

      % rdmd test.d Jimmy
      % cat test.txt
      Hello, Jimmy!
      % _

  @safe this(string `name`, in char[] `stdioOpenmode` = "rb");
  this(R1, R2)(R1 `name`)
  if (isInputRange!R1 && isSomeChar!(ElementEncodingType!R1));
  this(R1, R2)(R1 `name`, R2 `mode`)
  if (isInputRange!R1 && isSomeChar!(ElementEncodingType!R1) && isInputRange!R2 && isSomeChar!(ElementEncodingType!R2));
    Constructor taking the `name` of the file to open and the open `mode`.
    Copying one File object to another results in the two File objects referring to the same underlying file.
    The destructor automatically closes the file as soon as no File object refers to it anymore.
    Parameters:

    string `name` | range or string representing the file name
    char[] `stdioOpenmode` | range or string represting the open `mode` (with the same semantics as in the C standard library fopen function)

    Throws:
    ErrnoException if the file could not be opened.
  @safe void `opAssign`(File `rhs`);
    Assigns a file to another. The target of the assignment gets detached from whatever file it was attached to, and attaches itself to the new file.
  @safe void `open`(string `name`, in char[] `stdioOpenmode` = "rb");
    First calls detach (throwing on failure), and then attempts to open file `name` with mode `stdioOpenmode`. The mode has the same semantics as in the C standard library fopen function.
    Throws:
    ErrnoException in case of error.
  @trusted void `reopen`(string `name`, in char[] `stdioOpenmode` = "rb");
    Reuses the File object to either open a different file, or change the file mode. If `name` is null, the mode of the currently open file is changed; otherwise, a new file is opened, reusing the C FILE*. The function has the same semantics as in the C standard library freopen function.

    Note: Calling `reopen` with a null `name` is not implemented in all C runtimes.

    Throws:
    ErrnoException in case of error.
  @safe void `popen`(string `command`, in char[] `stdioOpenmode` = "r");
    First calls detach (throwing on failure), and then runs a `command` by calling the C standard library function popen.
    Throws:
    ErrnoException in case of error.
  @safe void `fdopen`(int `fd`, in char[] `stdioOpenmode` = "rb");
    First calls detach (throwing on failure), and then attempts to associate the given file descriptor with the File. The mode must be compatible with the mode of the file descriptor.
    Throws:
    ErrnoException in case of error.
  void `windowsHandleOpen`(HANDLE `handle`, in char[] `stdioOpenmode`);
    First calls detach (throwing on failure), and then attempts to associate the given Windows HANDLE with the File. The mode must be compatible with the access attributes of the `handle`. Windows only.
    Throws:
    ErrnoException in case of error.
  const pure nothrow @property @safe bool `isOpen`();
    Returns `true` if the file is opened.
  const pure @property @trusted bool `eof`();
    Returns `true` if the file is at end (see feof).
    Throws:
    Exception if the file is not opened.
  const pure nothrow @property @safe string `name`();
    Returns the `name` of the last opened file, if any. If a File was created with tmpfile and wrapFile it has no `name`.
  const pure nothrow @property @trusted bool `error`();
    If the file is not opened, returns `true`. Otherwise, returns ferror for the file handle.
  @safe void `detach`();
    Detaches from the underlying file. If the sole owner, calls close.
    Throws:
    ErrnoException on failure if closing the file.
  @trusted void `close`();
    If the file was unopened, succeeds vacuously. Otherwise closes the file (by calling fclose), throwing on error. Even if an exception is thrown, afterwards the File object is empty. This is different from detach in that it always closes the file; consequently, all other File objects referring to the same handle will see a closed file henceforth.
    Throws:
    ErrnoException on error.
  pure nothrow @safe void `clearerr`();
    If the file is not opened, succeeds vacuously. Otherwise, returns clearerr for the file handle.
  @trusted void `flush`();
    Flushes the C FILE buffers.
    Calls fflush for the file handle.
    Throws:
    Exception if the file is not opened or if the call to fflush fails.
  @trusted void `sync`();
    Forces any data buffered by the OS to be written to disk. Call flush before calling this function to flush the C FILE buffers first.
    This function calls FlushFileBuffers on Windows and fsync on POSIX for the file handle.
    Throws:
    Exception if the file is not opened or if the OS call fails.
  T[] `rawRead`(T)(T[] `buffer`);
    Calls fread for the file handle. The number of items to read and the size of each item is inferred from the size and type of the input array, respectively.
    Returns:
    The slice of `buffer` containing the data that was actually read. This will be shorter than `buffer` if EOF was reached before the `buffer` could be filled.
    Throws:
    Exception if `buffer` is empty. ErrnoException if the file is not opened or the call to fread fails.
    `rawRead` always reads in binary mode on Windows.
    Examples:

        static import std.file;

        auto testFile = testFilename();
        std.file.write(testFile, "\r\n\n\r\n");
        scope(exit) std.file.remove(testFile);

        auto f = File(testFile, "r");
        auto buf = f.rawRead(new char[5]);
        f.close();
        assert(buf == "\r\n\n\r\n");

  void `rawWrite`(T)(in T[] `buffer`);
    Calls fwrite for the file handle. The number of items to write and the size of each item is inferred from the size and type of the input array, respectively. An error is thrown if the `buffer` could not be written in its entirety.
    `rawWrite` always writes in binary mode on Windows.
    Throws:
    ErrnoException if the file is not opened or if the call to fwrite fails.
    Examples:

        static import std.file;

        auto testFile = testFilename();
        auto f = File(testFile, "w");
        scope(exit) std.file.remove(testFile);

        f.rawWrite("\r\n\n\r\n");
        f.close();
        assert(std.file.read(testFile) == "\r\n\n\r\n");

  @trusted void `seek`(long `offset`, int `origin` = SEEK_SET);
    Calls fseek for the file handle.
    Throws:
    Exception if the file is not opened. ErrnoException if the call to fseek fails.
  const @property @trusted ulong `tell`();
    Calls ftell for the managed file handle.
    Throws:
    Exception if the file is not opened. ErrnoException if the call to ftell fails.
    Examples:

        static import std.file;
        import std.conv : text;

        auto testFile = testFilename();
        std.file.write(testFile, "abcdefghijklmnopqrstuvwqxyz");
        scope(exit) { std.file.remove(testFile); }

        auto f = File(testFile);
        auto a = new ubyte[4];
        f.rawRead(a);
        assert(f.tell == 4, text(f.tell));

  @safe void `rewind`();
    Calls rewind for the file handle.
    Throws:
    Exception if the file is not opened.
  @trusted void `setvbuf`(size_t `size`, int `mode` = _IOFBF);
    Calls setvbuf for the file handle.
    Throws:
    Exception if the file is not opened. ErrnoException if the call to `setvbuf` fails.
  @trusted void `setvbuf`(void[] `buf`, int `mode` = _IOFBF);
    Calls setvbuf for the file handle.
    Throws:
    Exception if the file is not opened. ErrnoException if the call to `setvbuf` fails.
  void `lock`(LockType `lockType` = LockType.readWrite, ulong `start` = 0, ulong `length` = 0);
    Locks the specified file segment. If the file segment is already locked by another process, waits until the existing `lock` is released. If both `start` and `length` are zero, the entire file is locked.
    Locks created using `lock` and tryLock have the following properties:
    - All locks are automatically released when the process terminates.
    - Locks are not inherited by child processes.
    - Closing a file will release all locks associated with the file. On POSIX, even locks acquired via a different File will be released as well.
    - Not all NFS implementations correctly implement file locking.
  bool `tryLock`(LockType `lockType` = LockType.readWrite, ulong `start` = 0, ulong `length` = 0);
    Attempts to lock the specified file segment. If both `start` and `length` are zero, the entire file is locked.
    Returns:
    `true` if the lock was successful, and `false` if the specified file segment was already locked.
  void `unlock`(ulong `start` = 0, ulong `length` = 0);
    Removes the lock over the specified file segment.
  void `write`(S...)(S `args`);
    Writes its arguments in text format to the file.
    Throws:
    Exception if the file is not opened. ErrnoException on an error writing to the file.
  void `writeln`(S...)(S `args`);
    Writes its arguments in text format to the file, followed by a newline.
    Throws:
    Exception if the file is not opened. ErrnoException on an error writing to the file.
  void `writef`(Char, A...)(in Char[] `fmt`, A `args`);
    Writes its arguments in text format to the file, according to the format in the first argument.
    Throws:
    Exception if the file is not opened. ErrnoException on an error writing to the file.
  void `writefln`(Char, A...)(in Char[] `fmt`, A `args`);
    Writes its arguments in text format to the file, according to the format in the first argument, followed by a newline.
    Throws:
    Exception if the file is not opened. ErrnoException on an error writing to the file.
  S `readln`(S = string)(dchar `terminator` = '\x0a')
  if (isSomeString!S);
    Read line from the file handle and return it as a specified type.
    This version manages its own read buffer, which means one memory allocation per call. If you are not retaining a reference to the read data, consider the File.`readln`(buf) version, which may offer better performance as it can reuse its read buffer.
    Parameters:

    S | Template parameter; the type of the allocated buffer, and the type returned. Defaults to string.
    dchar `terminator` | Line `terminator` (by default, '\n').

    Note: String terminators are not supported due to ambiguity with `readln`(buf) below.

    Returns:
    The line that was read, including the line `terminator` character.
    Throws:
    StdioException on I/O error, or UnicodeException on Unicode conversion error.

    Example:

        // Reads $(D stdin) and writes it to $(D stdout).
        import std.stdio;

        void main()
        {
            string line;
            while ((line = stdin.readln()) !is null)
                write(line);
        }

  size_t `readln`(C)(ref C[] `buf`, dchar `terminator` = '\x0a')
  if (isSomeChar!C && is(Unqual!C == C) && !is(C == enum));
  size_t `readln`(C, R)(ref C[] `buf`, R `terminator`)
  if (isSomeChar!C && is(Unqual!C == C) && !is(C == enum) && isBidirectionalRange!R && is(typeof(`terminator`.front == (dchar).init)));
    Read line from the file handle and write it to `buf`[], including terminating character.
    This can be faster than line = File.`readln`() because you can reuse the buffer for each call. Note that reusing the buffer means that you must copy the previous contents if you wish to retain them.
    Parameters:

    C[] `buf` | Buffer used to store the resulting line data. `buf` is resized as necessary.
    dchar `terminator` | Line `terminator` (by default, '\n'). Use std.ascii.newline for portability (unless the file was opened in text mode).

    Returns:
    0 for end of file, otherwise number of characters read
    Throws:
    StdioException on I/O error, or UnicodeException on Unicode conversion error.

    Example:

        // Read lines from $(D stdin) into a string
        // Ignore lines starting with '#'
        // Write the string to $(D stdout)

        void main()
        {
            string output;
            char[] buf;

            while (stdin.readln(buf))
            {
                if (buf[0] == '#')
                    continue;

                output ~= buf;
            }

            write(output);
        }

    This method can be more efficient than the one in the previous example because stdin.`readln`(`buf`) reuses (if possible) memory allocated for `buf`, whereas line = stdin.`readln`() makes a new memory allocation for every line.
    For even better performance you can help `readln` by passing in a large buffer to avoid memory reallocations. This can be done by reusing the largest buffer returned by `readln`:

    Example:

        // Read lines from $(D stdin) and count words

        void main()
        {
            char[] buf;
            size_t words = 0;

            while (!stdin.eof)
            {
                char[] line = buf;
                stdin.readln(line);
                if (line.length > buf.length)
                    buf = line;

                words += line.split.length;
            }

            writeln(words);
        }

    This is actually what byLine does internally, so its usage is recommended if you want to process a complete file.
  uint `readf`(Data...)(in char[] `format`, Data `data`);
    Read `data` from the file according to the specified format specifier using std.format.formattedRead.
    Examples:

        // @system due to readf
        static import std.file;

        auto deleteme = testFilename();
        std.file.write(deleteme, "hello\nworld\ntrue\nfalse\n");
        scope(exit) std.file.remove(deleteme);
        string s;
        auto f = File(deleteme);
        f.readf("%s\n", &s);
        assert(s == "hello", "["~s~"]");
        f.readf("%s\n", &s);
        assert(s == "world", "["~s~"]");

        // Issue 11698
        bool b1, b2;
        f.readf("%s\n%s\n", &b1, &b2);
        assert(b1 == true && b2 == false);

  static @safe File `tmpfile`();
    Returns a temporary file by calling tmpfile. Note that the created file has no name.
  static @safe File `wrapFile`(FILE* `f`);
    Unsafe function that wraps an existing FILE*. The resulting File never takes the initiative in closing the file. Note that the created file has no name
  pure @safe FILE* `getFP`();
    Returns the FILE* corresponding to this object.
  const @property @trusted int `fileno`();
    Returns the file number corresponding to this object.
  @property HANDLE `windowsHandle`();
    Returns the underlying operating system HANDLE (Windows only).
  auto `byLine`(Terminator = char, Char = char)(KeepTerminator `keepTerminator` = No.`keepTerminator`, Terminator `terminator` = '\x0a')
  if (isScalarType!Terminator);
  auto `byLine`(Terminator, Char = char)(KeepTerminator `keepTerminator`, Terminator `terminator`)
  if (is(Unqual!(ElementEncodingType!Terminator) == Char));
    Returns an input range set up to read from the file handle one line at a time.
    The element type for the range will be Char[]. Range primitives may throw StdioException on I/O error.

    Note: Each front will not persist after popFront is called, so the caller must copy its contents (e.g. by calling to!string) when retention is needed. If the caller needs to retain a copy of every line, use the byLineCopy function instead.

    Parameters:

    Char | Character type for each line, defaulting to char.
    KeepTerminator `keepTerminator` | Use Yes.`keepTerminator` to include the `terminator` at the end of each line.
    Terminator `terminator` | Line separator ('\n' by default). Use std.ascii.newline for portability (unless the file was opened in text mode).

    Example:

        import std.algorithm, std.stdio, std.string;
        // Count words in a file using ranges.
        void main()
        {
            auto file = File("file.txt"); // Open for reading
            const wordCount = file.byLine()            // Read lines
                                  .map!split           // Split into words
                                  .map!(a => a.length) // Count words per line
                                  .sum();              // Total word count
            writeln(wordCount);
        }

    Example:

        import std.range, std.stdio;
        // Read lines using foreach.
        void main()
        {
            auto file = File("file.txt"); // Open for reading
            auto range = file.byLine();
            // Print first three lines
            foreach (line; range.take(3))
                writeln(line);
            // Print remaining lines beginning with '#'
            foreach (line; range)
            {
                if (!line.empty && line[0] == '#')
                    writeln(line);
            }
        }

    Notice that neither example accesses the line data returned by front after the corresponding popFront call is made (because the contents may well have changed).
  auto `byLineCopy`(Terminator = char, Char = immutable(char))(KeepTerminator `keepTerminator` = No.`keepTerminator`, Terminator `terminator` = '\x0a')
  if (isScalarType!Terminator);
  auto `byLineCopy`(Terminator, Char = immutable(char))(KeepTerminator `keepTerminator`, Terminator `terminator`)
  if (is(Unqual!(ElementEncodingType!Terminator) == Unqual!Char));
    Returns an input range set up to read from the file handle one line at a time. Each line will be newly allocated. front will cache its value to allow repeated calls without unnecessary allocations.

    Note: Due to caching `byLineCopy` can be more memory-efficient than File.byLine.map!idup.

    The element type for the range will be Char[]. Range primitives may throw StdioException on I/O error.
    Parameters:

    Char | Character type for each line, defaulting to immutable char.
    KeepTerminator `keepTerminator` | Use Yes.`keepTerminator` to include the `terminator` at the end of each line.
    Terminator `terminator` | Line separator ('\n' by default). Use std.ascii.newline for portability (unless the file was opened in text mode).

    Example:

        import std.algorithm, std.array, std.stdio;
        // Print sorted lines of a file.
        void main()
        {
            auto sortedLines = File("file.txt")   // Open for reading
                               .byLineCopy()      // Read persistent lines
                               .array()           // into an array
                               .sort();           // then sort them
            foreach (line; sortedLines)
                writeln(line);
        }

    See Also:
    std.file.readText
  ByRecord!Fields `byRecord`(Fields...)(string `format`);
    Creates an input range set up to parse one line at a time from the file into a tuple.
    Range primitives may throw StdioException on I/O error.
    Parameters:

    string `format` | tuple record format

    Returns:
    The input range set up to parse one line at a time into a record tuple.
    See Also:
    It is similar to byLine and uses format under the hood.
    Examples:

        static import std.file;
        import std.typecons : tuple;

        // prepare test file
        auto testFile = testFilename();
        scope(failure) printf("Failed test at line %d\n", __LINE__);
        std.file.write(testFile, "1 2\n4 1\n5 100");
        scope(exit) std.file.remove(testFile);

        File f = File(testFile);
        scope(exit) f.close();

        auto expected = [tuple(1, 2), tuple(4, 1), tuple(5, 100)];
        uint i;
        foreach (e; f.byRecord!(int, int)("%s %s"))
        {
            assert(e == expected[i++]);
        }

  auto `byChunk`(size_t `chunkSize`);
  ByChunk `byChunk`(ubyte[] `buffer`);
    Returns an input range set up to read from the file handle a chunk at a time.
    The element type for the range will be ubyte[]. Range primitives may throw StdioException on I/O error.

    Example:

        void main()
        {
            // Read standard input 4KB at a time
            foreach (ubyte[] buffer; stdin.byChunk(4096))
            {
                ... use buffer ...
            }
        }

    The parameter may be a number (as shown in the example above) dictating the size of each chunk. Alternatively, `byChunk` accepts a user-provided `buffer` that it uses directly.

    Example:

        void main()
        {
            // Read standard input 4KB at a time
            foreach (ubyte[] buffer; stdin.byChunk(new ubyte[4096]))
            {
                ... use buffer ...
            }
        }

    In either case, the content of the `buffer` is reused across calls. That means front will not persist after popFront is called, so if retention is needed, the caller must copy its contents (e.g. by calling `buffer`.dup).
    In the example above, `buffer`.length is 4096 for all iterations, except for the last one, in which case `buffer`.length may be less than 4096 (but always greater than zero).
    With the mentioned limitations, byChunks works with any algorithm compatible with input ranges.

    Example:

        // Efficient file copy, 1MB at a time.
        import std.algorithm, std.stdio;
        void main()
        {
            stdin.byChunk(1024 * 1024).copy(stdout.lockingTextWriter());
        }

    std.algorithm.iteration.joiner can be used to join chunks together into a single range lazily.

    Example:

        import std.algorithm, std.stdio;
        void main()
        {
            //Range of ranges
            static assert(is(typeof(stdin.byChunk(4096).front) == ubyte[]));
            //Range of elements
            static assert(is(typeof(stdin.byChunk(4096).joiner.front) == ubyte));
        }

    Returns:
    A call to `byChunk` returns a range initialized with the File object and the appropriate `buffer`.
    Throws:
    If the user-provided size is zero or the user-provided `buffer` is empty, throws an Exception. In case of an I/O error throws StdioException.
  @safe auto `lockingTextWriter`();
    Returns an output range that locks the file and allows fast writing to it.
    See byChunk for an example.
  auto `lockingBinaryWriter`();
    Returns an output range that locks the file and allows fast writing to it.

    Example: Produce a grayscale image of the Mandelbrot set in binary Netpbm format to standard output.

        import std.algorithm, std.range, std.stdio;

        void main()
        {
            enum size = 500;
            writef("P5\n%d %d %d\n", size, size, ubyte.max);

            iota(-1, 3, 2.0/size).map!(y =>
                iota(-1.5, 0.5, 2.0/size).map!(x =>
                    cast(ubyte)(1+
                        recurrence!((a, n) => x + y*1i + a[n-1]^^2)(0+0i)
                        .take(ubyte.max)
                        .countUntil!(z => z.re^^2 + z.im^^2 > 4))
                )
            )
            .copy(stdout.lockingBinaryWriter);
        }

  @property @safe ulong `size`();
    Get the `size` of the file, ulong.max if file is not searchable, but still throws if an actual error occurs.
enum `LockType`: int;
  Used to specify the lock type for File.lock and File.tryLock.
  `read`
    Specifies a read (shared) lock. A read lock denies all processes
    write access to the specified region of the file, including the
    process that first locks the region. All processes can read the
    locked region. Multiple simultaneous read locks are allowed, as
    long as there are no exclusive locks.
  `readWrite`
    Specifies a read/write (exclusive) lock. A read/write lock denies all
    other processes both read and write access to the locked file region.
    If a segment has an exclusive lock, it may not have any shared locks
    or other exclusive locks.
enum auto `isFileHandle`(T);
  Indicates whether T is a file handle, i.e. the type is implicitly convertable to File or a pointer to a core.stdc.stdio.FILE.
  Returns:
  true if T is a file handle, false otherwise.
  Examples:

      static assert(isFileHandle!(FILE*));
      static assert(isFileHandle!(File));

void `write`(T...)(T `args`)
if (!is(T[0] : File));
  For each argument arg in `args`, format the argument (as per to!(string)(arg)) and `write` the resulting string to `args`[0]. A call without any arguments will fail to compile.
  Parameters:

  T `args` | the items to `write` to stdout

  Throws:
  In case of an I/O error, throws an StdioException.
void `writeln`(T...)(T `args`);
  Equivalent to write(`args`, '\n'). Calling `writeln` without arguments is valid and just prints a newline to the standard output.
  Parameters:

  T `args` | the items to write to stdout

  Throws:
  In case of an I/O error, throws an StdioException.
void `writef`(T...)(T `args`);
  Writes formatted data to standard output (without a trailing newline).
  Parameters:

  T `args` | The first argument `args`[0] should be the format string, specifying how to format the rest of the arguments. For a full description of the syntax of the format string and how it controls the formatting of the rest of the arguments, please refer to the documentation for std.format.formattedWrite.

  Note: In older versions of Phobos, it used to be possible to write:

      writef(stderr, "%s", "message");

  to print a message to stderr. This syntax is no longer supported, and has been superceded by:

      stderr.writef("%s", "message");

void `writefln`(T...)(T `args`);
  Equivalent to writef(`args`, '\n').
uint `readf`(A...)(in char[] `format`, A `args`);
  Read data from stdin according to the specified format specifier using std.format.formattedRead.
S `readln`(S = string)(dchar `terminator` = '\x0a')
if (isSomeString!S);
  Read line from stdin.
  This version manages its own read buffer, which means one memory allocation per call. If you are not retaining a reference to the read data, consider the `readln`(buf) version, which may offer better performance as it can reuse its read buffer.
  Returns:
  The line that was read, including the line `terminator` character.
  Parameters:

  S | Template parameter; the type of the allocated buffer, and the type returned. Defaults to string.
  dchar `terminator` | Line `terminator` (by default, '\n').

  Note: String terminators are not supported due to ambiguity with `readln`(buf) below.

  Throws:
  StdioException on I/O error, or UnicodeException on Unicode conversion error.

  Example: Reads stdin and writes it to stdout.

      import std.stdio;

      void main()
      {
          string line;
          while ((line = readln()) !is null)
              write(line);
      }

size_t `readln`(C)(ref C[] `buf`, dchar `terminator` = '\x0a')
if (isSomeChar!C && is(Unqual!C == C) && !is(C == enum));
size_t `readln`(C, R)(ref C[] `buf`, R `terminator`)
if (isSomeChar!C && is(Unqual!C == C) && !is(C == enum) && isBidirectionalRange!R && is(typeof(`terminator`.front == (dchar).init)));
  Read line from stdin and write it to `buf`[], including terminating character.
  This can be faster than line = `readln`() because you can reuse the buffer for each call. Note that reusing the buffer means that you must copy the previous contents if you wish to retain them.
  Returns:
  size_t 0 for end of file, otherwise number of characters read
  Parameters:

  C[] `buf` | Buffer used to store the resulting line data. `buf` is resized as necessary.
  dchar `terminator` | Line `terminator` (by default, '\n'). Use std.ascii.newline for portability (unless the file was opened in text mode).

  Throws:
  StdioException on I/O error, or UnicodeException on Unicode conversion error.

  Example: Reads stdin and writes it to stdout.

      import std.stdio;

      void main()
      {
          char[] buf;
          while (readln(buf))
              write(buf);
      }

nothrow @nogc @trusted FILE* `popen`(R1, R2)(R1 `name`, R2 `mode` = "r")
if ((isInputRange!R1 && isSomeChar!(ElementEncodingType!R1) || isSomeString!R1) && (isInputRange!R2 && isSomeChar!(ElementEncodingType!R2) || isSomeString!R2));
  Convenience function that forwards to core.sys.posix.stdio.`popen` with appropriately-constructed C-style strings.
struct `lines`;
  Iterates through the `lines` of a file by using foreach.

  Example:

      void main()
      {
        foreach (string line; lines(stdin))
        {
          ... use line ...
        }
      }

  The line terminator ('\n' by default) is part of the string read (it could be missing in the last line of the file). Several types are supported for line, and the behavior of `lines` changes accordingly:
  1. If line has type string, wstring, or dstring, a new string of the respective type is allocated every read.
  2. If line has type char[], wchar[], dchar[], the line's content will be reused (overwritten) across reads.
  3. If line has type immutable(ubyte)[], the behavior is similar to case (1), except that no UTF checking is attempted upon input.
  4. If line has type ubyte[], the behavior is similar to case (2), except that no UTF checking is attempted upon input.
  In all cases, a two-symbols versions is also accepted, in which case the first symbol (of integral type, e.g. ulong or uint) tracks the zero-based number of the current line.

  Example:

        foreach (ulong i, string line; lines(stdin))
        {
          ... use line ...
        }

  In case of an I/O error, an StdioException is thrown.
  See Also:
  byLine
  this(File `f`, dchar `terminator` = '\x0a');
    Constructor.
    Parameters:

    File `f` | File to read lines from.
    dchar `terminator` | Line separator ('\n' by default).

auto `chunks`(File `f`, size_t `size`);
  Iterates through a file a chunk at a time by using foreach.

  Example:

      void main()
      {
          foreach (ubyte[] buffer; chunks(stdin, 4096))
          {
              ... use buffer ...
          }
      }

  The content of buffer is reused across calls. In the example above, buffer.length is 4096 for all iterations, except for the last one, in which case buffer.length may be less than 4096 (but always greater than zero).
  In case of an I/O error, an StdioException is thrown.
void `toFile`(T)(T `data`, string `fileName`)
if (is(typeof(copy(`data`, stdout.lockingBinaryWriter))));
  Writes an array or range to a file. Shorthand for `data`.copy(File(`fileName`, "wb").lockingBinaryWriter). Similar to std.file.write, strings are written as-is, rather than encoded according to the File's orientation.
class `StdioException`: object.Exception;
  Thrown if I/O errors happen.
  uint `errno`;
    Operating system error code.
  @trusted this(string `message`, uint `e` = core.stdc.errno.errno);
    Initialize with a `message` and an error code.
  static void `opCall`(string `msg`);
  static void `opCall`();
    Convenience functions that throw an StdioException.
File `stdin`;
  The standard input stream.
  Bugs:
  Due to bug 15768, it is thread un-safe to reassign `stdin` to a different File instance than the default.
  Examples:

      // Read stdin, sort lines, write to stdout
      import std.array : array;
      import std.algorithm.sorting : sort;
      import std.algorithm.mutation : copy;
      import std.typecons : Yes;

      void main() {
          stdin                       // read from stdin
          .byLineCopy(Yes.keepTerminator) // copying each line
          .array()                    // convert to array of lines
          .sort()                     // sort the lines
          .copy(                      // copy output of .sort to an OutputRange
              stdout.lockingTextWriter()); // the OutputRange
      }

File `stdout`;
  The standard output stream.
  Bugs:
  Due to bug 15768, it is thread un-safe to reassign `stdout` to a different File instance than the default.
File `stderr`;
  The standard error stream.
  Bugs:
  Due to bug 15768, it is thread un-safe to reassign `stderr` to a different File instance than the default.
File `openNetwork`(string `host`, ushort `port`);
  Experimental network access via the File interface
  Opens a TCP connection to the given `host` and `port`, then returns a File struct with read and write access through the same interface as any other file (meaning writef and the byLine ranges work!).
  Authors:
  Adam D. Ruppe
  Bugs:
  Only works on Linux

Copyright Digital Mars 2007-. | Page generated by Ddoc on Thu Mar 9 17:49:41 2017