Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Streams and StreamIterators

Buffered

BufferedInput and BufferedOutput buffer the flow of data from a upstream input/output. A downstream neighbour can locate and use this buffer instead of creating another instance of their own.

(note that upstream is closer to the source, and downstream is further away)

Data

DataInput represents a simple way to read binary data from an arbitrary InputStream, such as a file:

auto input = new DataInput (new File("path"));
auto x = input.int32;
auto y = input.float64;
char[22] tmp;
auto len = input.array (tmp);
input.close;

DataOutput is is similar, bot for output to an arbitrary OutputStream, such as a file:

auto output = new DataOutput (new File("path", File.WriteCreate));
output.int32 (1024);
output.float64 (3.14159);
output.array ("hello world");
output.flush.close;

DataFile

DataFileInput and DataFileOutput compose a seekable File with a Data class. A seek causes the buffer to be cleared or flushed.

Digester

DigestInput injects a digest filter into an input stream, updating the digest as information flows through it.

DigestOutput inject a digest filter into an output stream, updating the digest as information flows through it. Here's an example where we calculate an MD5 digest as a side-effect of copying a file:

auto output = new DigestOutput(new File("output", File.WriteCreate), new Md5);
output.copy (new File("input"));

Stdout.formatln ("hex digest: {}", output.digest.hexDigest);

Endian

Streams for swapping endian-order. The stream is treated as a set of same-sized elements. Note that partial elements are not mutated. See EndianInput and EndianOutput

Format

Simple way to hook up a utf8 formatter to an arbitrary OutputStream, such as a file, socket, or other:

auto output = new FormatOutput!(char) (new File("path", File.WriteCreate));
output.formatln ("{} green bottles", 10);
output.close;

This is a wrapper around the Layout class, and is typed for either char, wchar or dchar output.

Greedy

GreedyOutput is a conduit filter that ensures its output is written in full.

GreedyInput is a conduit filter that ensures its input is read in full.

Lines

Simple way to hook up a line-tokenizer to an arbitrary InputStream, such as a file conduit:

auto input = new LineInput!(char) (new File("path"));
foreach (line; input)
            ...
input.close;

Map

MapInput!(T) provides load facilities for a properties stream. That is, a file or other medium containing lines of text with a name=value layout

MapOutput!(T) provides write facilities on a properties stream. That is, a file or other medium which will contain lines of text with a name=value layout

Snoop

SnoopInput, SnoopOutput represent streams for exposing call behaviour. By default, activity trace is sent to Cerr. This can be useful for logging/debugging the stream calls.

TextFile

TextFileInput and TextFileOutput combines a File with Text IO.

Typed

TypedInput!(T) and TypedOutput!(T) are streams to expose simple native types as discrete elements. I/O is buffered and should yield fair performance.

Utf

UtfInput!(T,S) and UtfOutput!(S,T) represent UTF conversion streams, supporting cross-translation of char, wchar and dchar variants. For supporting endian variations, configure an appropriate Endian upstream of this one (closer to the source)

Iterators

Tango has a set of classes to split streaming text into elements matching a specific pattern. These classes operate upon an InputStream, and are templated for char, wchar, and dchar data types. For example, there’s an iterator for producing lines of text based upon finding embedded end-of-line markers. See Delimiters, Lines, Patterns and Quotes.

Iterator results are usually aliased directly from the containing buffer, thus avoiding heap activity where an application doesn’t need it. Where the resultant element is to be retained by the application, it should be copied before continuing.

Iterator Exceptions

An overflow exception is thrown where the size of a single element is larger than the containing buffer. Either the containing buffer is too small, or the element is overly large (a typical IO buffer is eight or sixteen kilobytes in size). Increase the buffer size to accommodate huge elements.