io

入力ストリームと出力ストリームが実装されているモジュールです。

インタフェース

次のインタフェースが定義されています。

InStream

入力ストリームのインタフェースを提供します。

pub fn InStream(comptime ReadError: type) type {
    return interface {
        fn read(buf: []mut u8) ReadError![]mut u8;
    };
}

ReadErrorは任意のエラー型です。read(buf: []mut u8) ReadError![]mut u8を定義することで、インタフェースを実装できます。

OutStream

出力ストリームのインタフェースを提供します。

pub fn OutStream(comptime WriteError: type) type {
    return interface {
        fn write(buf: []u8) WriteError![]u8;
    };
}

WriteError は任意のエラー型です。write(buf: []u8) WriteError![]u8を定義することで、インタフェースを実装できます。

InOutStream

入力ストリームと、出力ストリームの両方を提供します。InOutStreamを実装する構造体は、InStreamとしてもOutStreamとしても振る舞うことができます。

pub fn InOutStream(comptime ReadError: type, comptime WriteError: type) type {
    return interface {
        fn read(buf: []mut u8) ReadError![]mut u8;
        fn write(buf: []u8) WriteError![]u8;
    };
}

SeekableStream

ストリームの位置を制御するインタフェースを提供します。

pub fn SeekableStream(comptime SeekError: type, comptime GetPosError: type) type {
    return interface {
        fn seekTo(pos: u64) SeekError!void;
        fn seekBy(pos: i64) SeekError!void;
        fn getPos() GetPosError!u64;
        fn getEndPos() GetPosError!u64;
    };
}

SeekError、GetPosError は任意のエラー型です。seekTo、seekBy、getPos、getEndPos メソッドを定義することで、インタフェースを実装できます。

その他

詳細は割愛しますが、他に上述のインタフェースを組み合わせた、以下のインタフェースが定義されています。

• SeekableInStream: InStream と SeekableStream の両方のインタフェースを提供します。
• SeekableOutStream: OutStream と SeekableStream の両方のインタフェースを提供します。
• SeekableInOutStream: InStream と OutStream と SeekableStream のインタフェースを提供します。

read

InStream(Error)を実装する構造体は、read(Error)構造体の関数を利用できます。

• fill(stream: InStream(Error), buf: []mut u8) Error![]mut u8: streamからbufの長さ分データを読み出しbufを埋めます。
• fillNoEos(stream: InStream(Error), buf: []mut u8) ![]mut u8: streamからbufの長さ分データを読み出しbufを埋めます。読み込みの途中でストリームの終端に到達した場合はerror.EndOfStreamが返ります。
• structure(stream: InStream(Error), comptime T: type) !T: streamからT型のデータを読み込みます。Tはメモリレイアウトが定義されているextern structかpacked structでなければなりません。
• byte(stream: InStream(Error)) !u8: streamから1バイト読み出します。
• byteSigned(stream: InStream(Error)) !i8: streamから符号付きで1バイト読み出します。
• int(stream: InStream(Error), comptime T: type, endian: builtin.Endian) !T: streamからT型の整数型を、endianのエンディアンで読み出します。
• allBuffer(stream: InStream(Error), buffer: *mut Buffer, max_size: usize) !void: streamからbufferに最大max_sizeのデータを読み出します。

その他、いくつかの関数が実装されています。

write

OutStream(Error)を実装する構造体は、write(Error)構造体の関数を利用できます。

• byte(stream: OutStream(Error), b: u8) Error!void: streamに1バイト (b) を出力します。
• byteNTimes(stream: OutStream(Error), b: u8, n: usize) Error!void: streamにbをn回出力します。
• int(stream: OutStream(Error), comptime T: type, value: T, endian: builtin.Endian) Error!void: streamにT型の値valueをendianのエンディアンで出力します。
• print(stream: OutStream(Error), comptime format: []u8, args: anytype) Error!void: streamにフォーマットされた文字列を出力します。

その他、いくつかの関数が実装されています。

io インタフェースを実装した構造体

io に定義されているインタフェースを実装した構造体がいくつか定義されています。ここでは、最もシンプルな MemInStream と MemOutStream について紹介します。

MemInStream

MemInStream は SeekableInStream インタフェースを実装した構造体です。 バッファからの入力ストリームとストリーム位置の制御を提供します。 MemInStream インスタンス生成時に buffer フィールドに指定したスライスの内容をストリームとして読み出すことができます。

MemInStream は次のメソッドを提供します。

• read(buf: []mut u8) ReadError![]mut u8: バッファの内容を buf に読み込みます。戻り値には読み込んだデータのスライスを返します。
• seekTo(pos: u64) SeekError!void: ストリームの位置を pos へ移動させます。
• seekBy(pos: i64) SeekError!void: ストリームの位置を現在位置から pos に指定した分移動させます。
• getPos() GetPosError!u64: ストリームの現在位置を返します。
• getEndPos() GetPosError!u64: ストリームの終端位置を返します。

MemInStream を使用するとバッファに対して次のコードのような操作ができます。

examples/ch09-std/io/src/memstream.zen:8:25

test "MemInStream - basic" {
    var istream = MemInStream{ .buffer = "abcdefg" };
    var buf: [8]u8 = undefined;
    ok((try istream.getPos()) == 0);
    ok((try istream.getEndPos()) == 7);

    equalSlices(u8, "a", try istream.read(buf[0..1]));
    ok((try istream.getPos()) == 1);

    equalSlices(u8, "bcdefg", try istream.read(&mut buf));
    ok((try istream.getPos()) == 7);

    try istream.seekTo(0);
    equalSlices(u8, "abcdefg", try istream.read(&mut buf));

    try istream.seekBy(-3);
    equalSlices(u8, "efg", try istream.read(&mut buf));
}

MemOutStream

MemOutStream は SeekableOutStream インタフェースを実装した構造体です。 バッファへの出力ストリームとストリーム位置の制御を提供します。 MemOutStream インスタンス生成時に buffer フィールドに指定したスライスに対してストリームとして書き込みをすることができます。

MemOutStream は次のメソッドを提供します。

• write(buf: []u8) WriteError![]u8: buf の内容をバッファへ書き込みます。
• seekTo(pos: u64) SeekError!void: ストリームの位置を pos へ移動させます。
• seekBy(pos: i64) SeekError!void: ストリームの位置を現在位置から pos に指定した分移動させます。
• getPos() GetPosError!u64: ストリームの現在位置を返します。
• getEndPos() GetPosError!u64: ストリームの終端位置を返します。
• written() []mut u8: バッファに書き込まれている内容を返します。

MemOutStream を使用するとバッファに対して次のコードのような操作ができます。

examples/ch09-std/io/src/memstream.zen:27:54

test "MemOutStream - basic" {
    var buf: [32]u8 = undefined;
    var ostream = MemOutStream{ .buffer = &mut buf };

    ok((try ostream.getPos()) == 0);
    ok((try ostream.getEndPos()) == 32);

    _ = try ostream.write("a");
    ok((try ostream.getPos()) == 1);
    equalSlices(u8, "a", ostream.written());

    _ = try ostream.write("bcdefg");
    ok((try ostream.getPos()) == 7);
    equalSlices(u8, "abcdefg", ostream.written());

    _ = try ostream.seekTo(3);
    ok((try ostream.getPos()) == 3);
    equalSlices(u8, "abc", ostream.written());

    _ = try ostream.write("4567");
    ok((try ostream.getPos()) == 7);

    _ = try ostream.seekBy(-7);
    ok((try ostream.getPos()) == 0);
    _ = try ostream.write("123");
    _ = try ostream.seekBy(4);
    equalSlices(u8, "1234567", ostream.written());
}