Standard Library
class OutStream<T>
The writing end of a stream: you push values of type T in, and a reader takes them out.
since 0.1.0-alpha.1linuxwindows
Overview
The << operator pushes a value and returns the stream, so several writes chain on one line.
A write to a stream that has been closed is dropped without an error. An OutStream and an
InStream built over the same buffer are the two ends of one queue.
Description
An OutStream<T> is a write view over a StreamBuffer<T>. It has one operation, the <<
operator: out << v pushes v onto the buffer and returns the stream itself, so several
writes chain left to right. Each << pushes exactly one item. Chaining three values pushes
three separate items, not one concatenated one.
Because only the type's operators decide what a view can do, an OutStream<T> parameter is a
clean way to say "this function may produce values but cannot read them":
Chained writes are separate items
void greet(OutStream<string> sink, string name) {
sink << "hello" << name << "!";
}
StreamBuffer<string> buf = StreamBuffer();
greet(OutStream(buf), "Ada");
console.writeln("queued: ${buf.count()}");
InStream<string> reader = InStream(buf);
while (reader.hasData()) {
console.writeln(reader.pull());
}
queued: 3
hello
Ada
!
Rules
out << vpushes one value and returnsout.- Pushing onto a stream whose buffer has been closed does nothing: the value is dropped and no error is raised. A producer that outlives its consumer can therefore keep writing safely.
- If a consumer has subscribed a callback, a push calls the callback directly instead of queueing the value.
IOStream<T>is both anInStream<T>and anOutStream<T>over one shared buffer, so it can be handed to code that only writes or only reads.
Examples
IOStream writes and reads the same queue, and a closed IOStream ignores further writes:
One buffer, both ends
IOStream<int> pipe = IOStream(StreamBuffer());
pipe << 1 << 2 << 3;
console.writeln(pipe.pull());
OutStream<int> writer = pipe;
writer << 4;
InStream<int> reader = pipe;
console.writeln(reader.pull());
console.writeln(reader.pull());
console.writeln(reader.pull());
pipe.close();
pipe << 5;
console.writeln("data after close: ${pipe.hasData()}");
1
2
3
4
data after close: false
Notes
console << text and TcpStream << text use the same operator shape but are not OutStream
values; they send a string to standard output and to a socket.
Examples
StreamBuffer<string> buf = StreamBuffer();
OutStream<string> out = OutStream(buf);
InStream<string> inp = InStream(buf);
out << "one" << "two";
console.writeln(inp.pull());
console.writeln(inp.pull());
one
two
Constructors
new
new(StreamBuffer<T> b)Create the writing end of the stream backed by the buffer b.
Parameters
- b
- The buffer the stream writes into.
Examples
StreamBuffer<int> buf = StreamBuffer();
OutStream<int> out = OutStream(buf);
out << 42;
console.writeln(InStream(buf).pull());
42
Operators
<<
<<(T v) -> OutStream<T>Push a value into the stream and return the stream, so writes can be chained.
The value is queued for the reader, or handed straight to a subscriber. If the stream has been closed the value is dropped.
Parameters
- v
- The value to write.
Returns
This stream.
Examples
StreamBuffer<int> buf = StreamBuffer();
OutStream<int> out = OutStream(buf);
InStream<int> inp = InStream(buf);
out << 1 << 2 << 3;
console.writeln(inp.pull() + inp.pull() + inp.pull());
inp.close();
out << 4;
console.writeln(inp.hasData());
6
false