std.io

Input and output: import std.io { println }. The module holds one error type (IoError with its IoErrorKind); the interfaces Reader, Writer and Seek with their defaults; copy; two streams over memory (ByteReader, ByteBuffer); the buffers BufReader and BufWriter and the text streams TextReader and TextWriter; the console's output — print, println, eprint, eprintln, flush — and its streams stdin(), stdout(), stderr(); and the I/O pool that std.fs's calls run on. A reader's and a writer's call may throw Cancelled where it waits without bound.

Examples

import std.io { println, print, ByteBuffer, IoError };

fn main(): void throws IoError {
    print("one, ");
    println("two");
    let buffer = ByteBuffer.new();
    try buffer.write("written to memory".bytes());
    println(buffer.length());
}

one, two
17

Types

Stdin class — The standard input (stdin()): a Reader, and its text a line at a time.

StdinLinesIter struct — The standard input's lines (stdin().lines()).

ConsoleReader class — The console's input as bytes, unbuffered (lyr/console.h): what stdin() reads through its buffer.

ConsoleWriter class — One of the console's output streams as a Writer (stdout(), stderr()).

IoErrorKind enum — Classifies what went wrong in an input or an output — a file's, a socket's, a process's, memory's alike.

IoError struct — The error every input and output throws: its kind, the path it concerns, what more is known, and what caused it.

Reader interface — A source of bytes.

Writer interface — A sink of bytes.

SeekFrom enum — Selects where a position moves to: from the start, from the end, from where it stands.

Seek interface — A stream with a position: seek moves it and returns where it then stands, counted from the start.

ByteReader class — A Reader over bytes in memory: it reads them from the front, and seek moves it.

ByteBuffer class — A growing buffer of bytes in memory: a Writer that appends, a Reader that takes from the front what was written and not yet read.

BufReader class — A Reader with a buffer of its own: it reads its inner reader 8 KiB at a time, so that small reads do not each reach it.

BufWriter class — A Writer with a buffer of its own: what it is handed waits there until 8 KiB are together, a flush() or a close().

TextReader class — A reader of UTF-8 text: a BufReader and a decoder.

TextLinesIter struct — A TextReader's lines.

TextCharsIter struct — A TextReader's characters, their Error joined as the lines' is.

TextWriter class — A writer of text: its UTF-8, to the inner writer as it comes.

Functions

pub fn print<T :: [Display]>(v: T): void

Writes v's text on the standard output.

pub fn println<T :: [Display]>(v: T): void

Writes v's text and a newline on the standard output.

pub fn eprint<T :: [Display]>(v: T): void

Writes v's text on the standard error.

pub fn eprintln<T :: [Display]>(v: T): void

Writes v's text and a newline on the standard error.

pub fn flush(): void

Writes out what the console holds now: the standard output's, then the standard error's — for before a prompt waits for its answer, or where the program's next lines take long.

pub fn stdin(): Stdin

Returns the program's standard input: one for the program, made at the first call. Its reads go through a buffer of its own, so readLine, lines and read take turns on it without a byte lost — on the I/O pool where a scheduler runs.

pub fn stdout(): ConsoleWriter

Returns the standard output as a Writer: the buffer print writes into, so the two keep their order.

pub fn stderr(): ConsoleWriter

Returns the standard error as a Writer: the buffer eprint writes into.

pub fn copy<R :: [Reader], W :: [Writer]>(r: R, w: W): int throws [IoError, Cancelled]

Copies everything r holds into w, through a buffer of its own, and returns how many bytes it copied. The two are read and written as the values handed in — the handles and the streams here are classes, so that is the object itself; a reader that is a struct is read through a copy, and its position does not move for the caller.

Errors

Throws what r's read and w's write throw.

Extensions

extend<R :: [Reader]> R

pub mut fn readExact(into: Slice<uint8>): void throws [IoError, Cancelled]

Fills into whole, reading as often as it takes.

Errors

Throws UnexpectedEof where the source ends before, the bytes that came in the detail, and what the reader's read throws.

pub mut fn readToEnd(): uint8[] throws [IoError, Cancelled]

Reads everything to the end and returns it in one new array.

Errors

Throws what the reader's read throws.

pub mut fn readToString(): string throws [IoError, Cancelled]

Reads everything to the end and returns it as UTF-8 text.

Errors

Throws InvalidData for bytes that are no UTF-8, with the decoder's error as the cause, and what the reader's read throws.

extend<W :: [Writer]> W

pub mut fn writeAll(from: Slice<uint8>): void throws [IoError, Cancelled]

Writes all of from, writing as often as it takes.

Errors

Throws Other { code = 0 } where the writer takes no byte of a slice that has some (it would be asked forever), and what the writer's write throws.

pub mut fn writeString(s: StringView): void throws [IoError, Cancelled]

Writes all the bytes of s (its UTF-8).

Errors

Throws what writeAll throws.