module watt.io.streams

Stream interfaces for input and output.

A stream is an interface that reads or writes to a destination, one character at a time.

Watt ships with implementations of OutputFileStream and InputFileStream appropriate for the current platform.

Use the plain OutputStream and InputStream definition where possible, and then the implementation is not important.

Example

fn outputAnImportantThing(os: OutputStream)
...
outputAnImportantThing(output);
outputAnImportantThing(new OutputFileStream("foo.txt"));

Code Map

//! Stream interfaces for input and output.
module watt.io.streams;

public import watt.io.streams.fd;
public import watt.io.streams.stdc;


//! An implementation of the InputStream for files.
alias InputFileStream = InputFDStream;
//! An implementation of the OutputStream for files.
alias OutputFileStream = OutputFDStream;

//! OutputStreams write data to a destination (file, console, etc) in
//! characters.
class OutputStream
{
public:
	this() { }
	//! Close the stream.
	fn close();
	//! Determine the stream state.
	fn isOpen() bool;
	//! Write a single character out to the sink.
	fn put(c: dchar);
	//! Write a series of characters to the sink.
	fn write(s: scope (const(scope (char)[])) { }
	//! Ensure that all pending writes (from the put and write functions) are
	//! completed.
	fn flush();
	//! Write a series of characters then a newline.
	fn writeln(s: const(char)[]) { }
	fn vwritef(formatString: const(char)[], typeids: TypeInfo[], vl: va_list) { }
	//! Write a formatted string.
	fn writef(formatString: const(char)[]) { }
	fn vwritefln(formatString: const(char)[], typeids: TypeInfo[], vl: va_list) { }
	//! Write a formatted string and then a newline.
	fn writefln(formatString: const(char)[]) { }
}

//! InputStreams read data in characters from a source (file, device,
//! etc).
class InputStream
{
public:
	this() { }
	//! Close this stream.
	fn close();
	//! Determine this stream's state.
	fn isOpen() bool;
	//! Read a single character from the source.
	fn get() dchar;
	//! Read as much data as possible into buffer.
	fn read(buffer: u8[]) u8[];
	//! Is the source out of data?
	fn eof() bool;
	//! Read input until a newline character is encountered.
	fn readln() string { }
}
alias InputFileStream

An implementation of the InputStream for files.

alias OutputFileStream

An implementation of the OutputStream for files.

class OutputStream

OutputStreams write data to a destination (file, console, etc) in characters.

fn close()

Close the stream.

This calls flush, so there is no need to do it before closing:

ofs.put('A');
ofs.flush();  // Unneeded!
ofs.close();
fn isOpen() bool

Determine the stream state.

If an OutputStream is 'open', it is connected to a valid destination, and is ready to write input.

Return

true if this stream is open.

fn put(c: dchar)

Write a single character out to the sink.

This interface does not guarantee that writes will happen immediately, but they will happen in order. Call flush if you need to ensure that pending output has been written.

fn write(s: scope (const(scope (char)[]))

Write a series of characters to the sink.

This is the same as calling put in a loop.

fn flush()

Ensure that all pending writes (from the put and write functions) are completed.

This call will block until all pending writes are completed.

fn writeln(s: const(char)[])

Write a series of characters then a newline.

This is the same as calling write, then put with '\n'.

fn writef(formatString: const(char)[])

Write a formatted string.

See format for format string details.

fn writefln(formatString: const(char)[])

Write a formatted string and then a newline.

See format for format string details.
This is the same as calling writef, then put.

class InputStream

InputStreams read data in characters from a source (file, device, etc).

fn close()

Close this stream.

A closed stream will read no more data.

fn isOpen() bool

Determine this stream's state.

An InputStream is open if it has a valid connection to the source.

Return

true if this stream is open.

fn get() dchar

Read a single character from the source.

Return

The character that was read.

fn read(buffer: u8[]) u8[]

Read as much data as possible into buffer.

This function does not allocate additional memory into buffer; if a zero length array is given to buffer, no data will be read.

Return

A slice into the input buffer. This slice could be shorter than the input buffer if an EOF was encountered before it could be filled.

fn eof() bool

Is the source out of data?

This may never be true, depending on the source.

Return

true if there is no more data to read.

fn readln() string

Read input until a newline character is encountered.

The newline is not included in the returned data, and the newline that terminated this function will not be read by further calls to get.

Return

The data that was read, not including the newline.