File.byChunk

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.

  1. auto byChunk(size_t chunkSize)
    struct File
    byChunk
    (
    size_t chunkSize
    )
  2. auto byChunk(ubyte[] buffer)

Return Value

Type: auto

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.

Examples

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.

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, byChunk works with any algorithm compatible with input ranges.

// 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.

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

Meta