streams 2.0.0

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. This library has been designed to be BetterC compatible, using manual memory management anywhere that's needed. Some features are only available in conjunction with the D runtime though, like exceptions and stream implementations for Phobos-specific components.

Similar to Phobos' ranges, streams are defined and type-checked using a primitives package that contains various compile-time functions like isInputRange and isOutputRange. Let's look at an example where we write some data to a socket using streams:

import streams;

void sayHello(Socket socket) {
    auto outputStream = SocketOutputStream(socket);
    auto dataOutput = dataOutputStreamFor(outputStream);
    dataOutput.writeToStream!(char[5])("Hello");
}

Features

• Compile-time functions for identifying streams of various kinds, useful for when you want to accept streams as parameters or use them in templates.
• Convenience functions for dealing with streams, like reading all elements to a buffer, or transfering the contents of one stream to another.
• Pre-defined stream implementations for common use cases:
  • ArrayInputStream and ArrayOutputStream for performing IO on in-memory arrays.
  • DataInputStream and DataOutputStream are wrappers over any ubyte stream, adding the ability to read and write scalar values (int, float, bool, char, etc.) and static arrays, by automatically serializing them.
  • FileInputStream and FileOutputStream are ubyte streams for reading and writing files using std.stdio : File.
  • SocketInputStream and SocketOutputStream are ubyte streams for reading and writing to sockets using std.socket : Socket.
• Functions to convert between streams and Phobos ranges.

Difference with Ranges

Phobos' concept of an Input Range 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.

This isn't to say that ranges aren't useful! They certainly are in many cases, but the argument is that a simpler stream interface is more useful in IO-heavy tasks or other cases where you simply want to read or write data to/from a buffer.

Furthermore, streams of this nature are a common feature in many other programming languages, and thus provides a bit of a "comfort zone" to help welcome programmers.

Range Compatibility

• To convert a range to a stream: auto stream = asStream(range); You can also use asInputStream and asOutputStream to be more explicit when dealing with things that behave as both an input and output range.
• To convert a stream to a range: auto range = asRange(stream); You can also use asInputRange and asOutputRange to be more explicit when dealing with streams that implement both input and output functions.

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.

For testing the library's BetterC compatibility, run dub test --config=betterC.

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

Tests and coverage are run automatically with GitHub Actions. See gen_coverage.d for a look at how coverage is computed in detail, but essentially:

1. We generate coverage .lst files using the standard compiler unittest coverage feature.
2. The .lst files are parsed, and lines with // cov-ignore comments are ignored.
3. We compute the % of lines covered, and if it's below some threshold, fail.