streams 0.0.1

Streams

A collection of useful stream primitives and implementations. Designed to be a candidate for inclusion in Phobos. The concept of a stream is of a component that implements a int read(T[] buffer) or int write(T[] buffer) method for some element type T.

Similar to Phobos' ranges, streams are defined and type-checked using a primitives package that contains various compile-time functions like isInputRange and isOutputRange. Take the following example, where we define a simple input stream implementation for reading from a file, and use it in a function that accepts any byte input stream to collect the results in an array:

struct FileInputStream {
    File f;

    int read(ubyte[] buffer) {
        ubyte[] slice = this.file.rawRead(buffer);
        return cast(int) slice.length;
    }
}

ubyte[] readToArray(S)(S stream) if (isInputStream!(S, ubyte)) {
    import std.array;
    ubyte[] buffer = new ubyte[8192];
    auto app = appender!(ubyte[]);
    int bytes;
    while ((bytes = stream.read(buffer)) > 0) {
        app ~= buffer[0 .. bytes];
    }
    return buffer;
}

unittest {
    import streams;
    assert(isInputStream!(FileInputStream, ubyte));
}

Stream primitives are generally compatible with BetterC, although there may be incompatibilities in various implementations where dynamic arrays or exceptions are used. You may certainly write streams that are safe, no-gc compatible, pure, and so on.

Difference with Ranges

Phobos' concept of an InputRange relies on implicit buffering of results, because of the contract it defines with front() needing to return the same result in consecutive calls without calling popFront(). This doesn't map as easily to many low-level resources, and also introduces additional cognitive complexity to programmers who don't need that functionality.

For compatibility, this library provides the functions asInputRange and asOutputRange to wrap an input stream as a Phobos input range and an output stream as a Phobos output range, respectively. Note that due to the inherently un-buffered nature of streams, these range implementations may not be as performant as existing range implementations for certain resources.

Development

Simply clone this repository, and ensure you have a recent version of D with any compiler, and run dub test to test the library.

Documentation can be generated with ./gen_docs.d, which internally uses Adrdox to generate documentation at generated-docs/.