The D Programming Language

Standard I/O functions that extend std.c. stdio. std.c. 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

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.

Known Bugs
 File expects file names to be encoded in CP_ACP on Windows instead of UTF-8 (Bugzilla 7648) thus must not be used in Windows or cross-platform applications other than with an immediate ASCII string as a file name to prevent accidental changes to result in incorrect behavior. One can use std.file.read/std.file.write/ File">std.stream. File instead.
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!
% _

this(string name, in char[] stdioOpenmode = "rb");

Constructor taking the name of the file to open and the open mode (with the same semantics as in the C standard library fopen function).

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.

Throws
ErrnoException if the file could not be opened.

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.


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.

const pure nothrow @property bool  isOpen();

Returns true if the file is opened.


const pure @property bool  eof();

Returns true if the file is at end (see feof).

Throws
Exception if the file is not opened.

const pure nothrow @property 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 bool  error();

If the file is not opened, returns false. Otherwise, returns ferror for the file handle.


void  detach();

Detaches from the underlying file. If the sole owner, calls close.

Throws
ErrnoException on failure if closing the file.

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 void  clearerr();

If the file is not opened, succeeds vacuously. Otherwise, returns clearerr for the file handle.


void  flush();

Calls fflush for the file handle.

Throws
Exception if the file is not opened or if the call to $D(fflush) 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 $D(fread) fails.

 rawRead always reads in binary mode on Windows.

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 $D(fread) fails.

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 $D(fseek) fails.

const @property ulong  tell();

Calls ftell for the managed file handle.

Throws
Exception if the file is not opened. ErrnoException if the call to $D(ftell) fails.

void  rewind();

Calls rewind for the file handle.

Throws
Exception if the file is not opened.

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 $D( setvbuf) fails.

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 $D( setvbuf) fails.

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')
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')
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.

uint  readf(Data...)(in char[] format, Data data);

Read data from the file according to the specified format specifier using std.format.formattedRead.


static File  tmpfile();

Returns a temporary file by calling tmpfile. Note that the created file has no name .


static 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 FILE*  getFP();

Returns the FILE* corresponding to this object.


const int  fileno();

Returns the file number corresponding to this object.


auto  byLine(Terminator = char, Char = char)(KeepTerminator keepTerminator = KeepTerminator.no, 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) if retention is needed.
Parameters
Char Character type for each line, defaulting to char.
KeepTerminator keepTerminator Use KeepTerminator.yes to include the terminator at the end of each line.
Terminator terminator Line separator ('\n' by default).
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

                          .reduce!((a, b) => a + b); // 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  byChunk(size_t chunkSize);

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.

Note:
Each front will not persist after popFront is called, so the caller must copy its contents (e.g. by calling buffer.dup) if retention is needed.
Example:
void main()
{
  foreach (ubyte[] buffer; stdin.byChunk(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).
Example:
import std.algorithm, std.stdio;

void main()
{
    stdin.byChunk(1024).copy(stdout.lockingTextWriter());
}

Returns an output range that locks the file and allows fast writing to it.

See byChunk for an example.


@property ulong  size();

Get the  size of the file, ulong.max if file is not searchable, but still throws if an actual error occurs.


template  isFileHandle(T)

Indicates whether T is a file handle of some kind.


alias  isStreamingDevice = isFileHandle(T);

Scheduled for deprecation in January 2013. Please use isFileHandle instead.


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.

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.


void  writef(T...)(T args);

If the first argument args[0] is a FILE*, use the format specifier in args[1] to control the formatting of args[2..$], and write the resulting string to args[0]. If arg[0] is not a FILE*, the call is equivalent to  writef(stdout, args).

IMPORTANT:
New behavior starting with D 2.006: unlike previous versions,  writef (and also writefln) only scans its first string argument for format specifiers, but not subsequent string arguments. This decision was made because the old behavior made it unduly hard to simply print string variables that occasionally embedded percent signs.

Also new starting with 2.006 is support for positional parameters with POSIX syntax.
Example:
writef("Date: %2$s %1$s", "October", 5); // "Date: 5 October"



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 popFront parameter after the largest positional parameter already used.

New starting with 2.008: raw format specifiers. Using the "%r" specifier makes  writef simply write the binary representation of the argument. Use "%-r" to write numbers in little endian format, "%+r" to write numbers in big endian format, and "%r" to write numbers in platform-native format.

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')
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')
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);
}

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.

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.

class  StdioException: object.Exception;

Thrown if I/O errors happen.


uint  errno;

Operating system error code.


this(string message, uint e = .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.


File  stdout;

The standard output stream.


File  stderr;

The standard error stream.