Streams and StreamIterators

Streams

BufferedStream

Buffers the flow of data from a upstream input. 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)

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

DataFileStream

DataFileInput, DataFileOutput composes a seekable file with buffer. A seek causes the buffer to be cleared or flushed.

DataStream

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

auto input = new DataInput (new FileInput("path"));
auto x = input.readInt;
auto y = input.readDouble;
input.read (new char[10]);
input.close;

DataOutput
A simple way to write binary data to an arbitrary OutputStream, such as a file:

auto output = new DataOutput (new FileOutput("path"));
output.writeInt (1024);
output.writeDouble (3.14159);
output.write ("hello world");
output.flush.close;

DigestStream

DigestInput
Inject 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 FileOutput("output"), new Md5);
output.copy (new FileInput("input"));

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

EndianessStream

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

EndianInput and EndianOutput

FileStream

Trivial wrapper around a FileConduit

FileInput and FileOutput

FormatStream

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

auto output = new FormatOutput (new FileOutput("path"));
output.formatln ("{} green bottles", 10);
output.close;

This is a trivial wrapper around the Print class, and is limited to emitting utf8 output. Use the Print class directly in order to generate utf16/32 output instead.

Note that this class is a true instance of OutputStream, by way of inheritance via the Print superclass.

GreedyStream

GreedyOutput
A conduit filter that ensures its output is written in full

GreedyInput
A conduit filter that ensures its input is read in full

LineStream

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

auto input = new LineInput (new FileInput("path"));
foreach (line; input)
            ...
input.close;

Note that this is just a simple wrapper around LineIterator, and supports utf8 lines only. Use LineIterator directly for utf16/32 support, or use the other tango.text.stream classes directly for other tokenizing needs.

Note that this class is a true instance of InputStream, by way of inheritance via the Iterator superclass.

MapStream

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

SnoopStream

SnoopInput, SnoopOutput Streams to expose call behaviour. By default, activity trace is sent to Cerr.

This is usefull for logging/debugging the stream calls.

TextFileStream

TextFileInput and TextFileOutput
Composes a file with line-oriented input

TypedStream

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

UtfStream

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

Streaming 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. Iterator classes are clients of Buffer, and can therefore be mixed with reader and/or writer clients also.

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.