std.stream

Source:
std/stream.d

License:
Boost License 1.0.

class StreamException: object.Exception;

ストリームに関する例外の基底クラス

this(string msg);: 指定のエラーメッセージで StreamException オブジェクトを構築

class ReadException: std.stream.StreamException;

ストリームからデータを読めなかった場合の例外

this(string msg);: 指定のエラーメッセージで ReadException オブジェクトを構築

class WriteException: std.stream.StreamException;

ストリームにデータを書けなかった場合の例外

this(string msg);: 指定のエラーメッセージで WriteException オブジェクトを構築

class SeekException: std.stream.StreamException;

ストリーム位置を動かせなかった場合の例外

this(string msg);: 指定のエラーメッセージで SeekException オブジェクトを構築

interface InputStream;

InputStream は読み込み可能ストリームのためのインターフェイスです。

abstract void readExact(void* buffer, size_t size);

ぴったり size バイトを buffer へ読み込みます

正確に読み込めなければ ReadException を投げます。

abstract size_t read(ubyte[] buffer);

与えられた buffer 配列を埋めるのに十分なだけデータブロックを読み込みます。

Returns:
実際に読み込まれたバイト数を返します。埋められなかったバイトは変更されません。

abstract void read(out byte x); abstract void read(out ubyte x); abstract void read(out short x); abstract void read(out ushort x); abstract void read(out int x); abstract void read(out uint x); abstract void read(out long x); abstract void read(out ulong x); abstract void read(out float x); abstract void read(out double x); abstract void read(out real x); abstract void read(out ifloat x); abstract void read(out idouble x); abstract void read(out ireal x); abstract void read(out cfloat x); abstract void read(out cdouble x); abstract void read(out creal x); abstract void read(out char x); abstract void read(out wchar x); abstract void read(out dchar x); abstract void read(out char[] s); abstract void read(out wchar[] s);

基本型や、サイズ指定つき文字列を読み込みます。

読み込みに失敗すると ReadException 例外を投げます。 byte, ubyte, char, 以外についてはフォーマットは実装依存で、 write の逆の動作をすること以外は期待してはいけません。

abstract char[] readLine(); abstract char[] readLine(char[] result); abstract wchar[] readLineW(); abstract wchar[] readLineW(wchar[] result);

CRとLF,EOL の何らかの組み合わせで終わる一行を読み込みます。

行末文字は返値には含まれません。wchar版も同様です。引数にバッファが指定された場合、バッファサイズが足りていれば、指定のバッファにデータが書き込まれ、足りない場合は ~ で追記されます。返値は結果のスライスです。

abstract int opApply(scope int delegate(ref char[] line) dg); abstract int opApply(scope int delegate(ref ulong n, ref char[] line) dg); abstract int opApply(scope int delegate(ref wchar[] line) dg); abstract int opApply(scope int delegate(ref ulong n, ref wchar[] line) dg);

foreach文をオーバーライドして、ストリームを一行一行、または行番号付きで一行一行読み込みます。

渡される文字列は、delegeteの呼び出し後にも再利用できます。行番号は1から始まります。 foreachからのbreakは、ストリーム位置を次に読み込まれる行の行頭に保ちます。例えば、一行づつファイルをエコーするには：

 Stream file = new BufferedFile("sample.txt");
 foreach(ulong n, string line; file) {
   stdout.writefln("line %d: %s",n,line);
 }
 file.close();

abstract char[] readString(size_t length);

与えられた長さの文字列を読み込みます。

問題が発生すると ReadException を投げます

abstract wchar[] readStringW(size_t length);

与えられた長さの文字列を読み込みます。問題が発生すると ReadException を投げます

ファイルフォーマットは実装依存で、 write の逆の動作をすること以外は期待してはいけません。

abstract char getc(); abstract wchar getcw();

ストリームの次の文字を読み込んで返します。

このメソッドだけが、ungetc を適切に扱います。 getcw のフォーマットは実装依存です。 EOFに達した場合、getcはchar.initを、getcwはwchar.initを返します。

abstract char ungetc(char c); abstract wchar ungetcw(wchar c);

一文字をストリームに戻します。

first-in last-out で getc と getcw へ戻されます。

abstract int vreadf(TypeInfo[] arguments, void* args); abstract int readf(...);

C の scanf や std.format と似たフォーマットで、入力から文字列をスキャンします。

string 型の引数は、書式指定文字列として解釈されます。そのほかの引数は全て、ポインタ型でなければなりません。書式指定文字列が存在しない場合、ポインタの型ごとに定められているデフォルトの書式が使用されます。 string* 型の引数の場合、配列が文字で埋められ（必要ならサイズの拡張が行われ）、最終結果のスライスが引数へと再代入されます。たとえば、以下のreadfを使った文は全て等価です：

 int x;
 double y;
 string s;
 file.readf(&x, " hello ", &y, &s);
 file.readf("%d hello %f %s", &x, &y, &s);
 file.readf("%d hello %f", &x, &y, "%s", &s);

abstract size_t available();

現在すぐに読みとれるバイト数を返します。

abstract bool eof();

現在のファイル位置がファイル終端であるかどうかを返します。

stdioのような、実際に終端以降を読み取ろうとする作業は必要ありません。ただし、シーク不可能なストリームの場合は、実際に終端以降を読み取ろうとした後にのみtrueを返します。

abstract bool isOpen();

ストリームが現在開かれているなら true を返します。

interface OutputStream;

書き込み可能ストリームのためのインターフェイスです。

abstract void writeExact(const void* buffer, size_t size);: バッファ buffer からちょうど size バイト書き込みます。書き込みきれなければ WriteException を投げます。
abstract size_t write(const(ubyte)[] buffer);: buffer の中身を可能な限り書き出し、実際に書かれたバイト数を返します。
abstract void write(byte x); abstract void write(ubyte x); abstract void write(short x); abstract void write(ushort x); abstract void write(int x); abstract void write(uint x); abstract void write(long x); abstract void write(ulong x); abstract void write(float x); abstract void write(double x); abstract void write(real x); abstract void write(ifloat x); abstract void write(idouble x); abstract void write(ireal x); abstract void write(cfloat x); abstract void write(cdouble x); abstract void write(creal x); abstract void write(char x); abstract void write(wchar x); abstract void write(dchar x);: 基本型を書き込みます

byte, ubyte, char, 以外についてはフォーマットは実装依存で、 read と組み合わせてのみ使用すべきです。エラー時には WriteException が送出されます。
abstract void write(const(char)[] s); abstract void write(const(wchar)[] s);: 文字列とその長さを書き込みます。

フォーマットは実装依存で、 read と組み合わせてのみ使用すべきです。エラー時には WriteException が送出されます。
abstract void writeLine(const(char)[] s);: 一行テキストを出力し、さらにOS特有の行末文字を書き出します。

エラー時には WriteException が送出されます。
abstract void writeLineW(const(wchar)[] s);: 一行テキストを出力し、さらにOS特有の行末文字を書き出します。

フォーマットは実装依存です。エラー時には WriteException が送出されます。
abstract void writeString(const(char)[] s);: 文字列を出力します。

文字列全体を書き込めなければ WriteException が発生します。
abstract void writeStringW(const(wchar)[] s);: 文字列を出力します。

フォーマットは実装依存です。文字列全体を書き込めなければ WriteException が発生します。
abstract size_t vprintf(const(char)[] format, va_list args); abstract size_t printf(const(char)[] format,...);: printf風の構文で、フォーマットされた文字列をストリームへ書き出します。返値は書き込まれたバイト数です。
abstract OutputStream writef(...); abstract OutputStream writefln(...); abstract OutputStream writefx(TypeInfo[] arguments, void* argptr, int newline = false);: writef風の構文で、フォーマットされた文字列をストリームへ書き出します。

References:
std.format.

Returns:
OutputStream自身を返します。返値を使って、flushなどその他のコマンドへと繋げることができます。
abstract void flush();: もしあれば、バッファに溜まったデータを出力します。
abstract void close();: flushしてから、ストリームを閉じます。
abstract bool isOpen();: ストリームが現在開かれているならtrueを返します。

abstract class Stream: std.stream.InputStream, std.stream.OutputStream;

Stream は、ここから他のストリームクラスを派生させる、仮想基底クラスです。

Stream のバイトオーダはマシンのネイティブに従います。

読み込み: 読み込み用メソッドが使えるためには、readable ビットがセットされている必要があります。読み込みの際に問題が起きると ReadException が投げられます。 Streamは、InputStreamインターフェイスに加えて、 readBlockメソッドを実装します。

書き込み: 書き込み用メソッドが使えるためには、writable ビットがセットされている必要があります。書き込みの際に問題が起きると WriteException が投げられます。 Streamは、OutputStreamインターフェイスに加えて、以下のメソッドを実装します： writeBlock copyFrom copyFrom

シーク: シーク用メソッドが使えるためには、seekable ビットがセットされている必要があります。シークの際に問題が起きると SeekException が投げられます。以下のメソッドがあります： seek, seekSet, seekCur, seekEnd, position, size, toString, toHash

bool readable;: そのストリームが読み込み可能かどうかを示します
bool writeable;: そのストリームが書き込み可能かどうかを示します
bool seekable;: そのストリームがシーク可能かどうかを示します
protected bool isopen;: ストリームが開かれているかどうかを示します
protected bool readEOF;: 直前のread操作の後、このストリームがeofを指しているかどうかを示します。
protected bool prevCr;: seekableでないストリームについて、最後のreadLineやreadLineWが '\r' 文字で終わったことを示します。
abstract size_t readBlock(void* buffer, size_t size);: 最大で size バイトをバッファへ読み込み、実際に読み込まれたバイト数を返します。0 はEOFであることを示します。
abstract size_t writeBlock(const void* buffer, size_t size);: 最大でsizeバイトをバッファから書き込み、実際に書き込まれたバイト数を返します。
void copyFrom(Stream s);: s から全てのデータをこのストリームへコピーします。このメソッドは失敗すると ReadException か WriteException を投げます。 s のストリーム中での位置は、変化しないように復元されます。
void copyFrom(Stream s, ulong count);: s から指定されたバイト数のデータをこのストリームへコピーします。このメソッドは失敗すると ReadException か WriteException を投げます。バイト数指定のないcopyFromと違って、こちらはsの位置の復元は行いません。
abstract ulong seek(long offset, SeekPos whence);: ストリームの現在位置を変更します。whence は SeekPos.Set （offsetはストリーム先頭からのインデックス）か、 SeekPos.Current （offsetは現在位置からの変位）か、 SeekPos.End （ストリーム終端からの変位。 0または負の値のみに意味がある）、のいずれかです。返値は新しいファイル位置です。
ulong seekSet(long offset); ulong seekCur(long offset); ulong seekEnd(long offset);: 対応するseek関数呼び出しへの別名です。
void position(ulong pos);: 現在位置を設定します。seek(pos, SeekPos.Set) と同等です。
ulong position();: ファイル内での現在位置を取得します。seek(0, SeekPos.Current) と同等です。
ulong size();: ストリームのサイズをバイト単位で得ます。ストリームが seekableでなければなりません。そうでない場合 SeekException を投げます。
string toString();: ストリーム全体を読み込んで文字列として返します。ストリームが seekable でない場合、現在のファイル位置からEOFまでの内容が読み込まれ、返されます。
size_t toHash();: 全バイトからCRC-32で計算した、ストリーム全体のハッシュ値を返します。

class FilterStream: std.stream.Stream;

別のストリームをラップして新たな機能を付け加えるタイプのストリームの、基底クラスです。

デフォルトのメソッド実装は、read/write/seek 呼び出しをソースストリームへと転送します。FilterStream はソースストリームの位置を任意に変更し、 FilterStream 本体とソースストリームの状態を同期させないかもしれません。 FilterStream の flush や close 時でも同様です。 FilterStream をかぶせて使っている間は、ベースとなるソースストリームの状態については、何も仮定しないことを推奨します。 FilterStream の派生クラスは、どのようにソースストリームを変更し、ソースとフィルタの間にどのような不変条件があるのかを文書化すべきです。

bool nestClose;: このストリームが閉じたときに、ソースストリームを同時に閉じるかどうかを示すプロパティです。デフォルトはtrue です。
this(Stream source);: 指定のソースから FilterStream を構築します
final Stream source();: 現在のソースストリームを取得
void source(Stream s);: ソースストリームを設定

新しいソースストリームを設定する前に、現在のストリームは close されます。新しいソースを接続すると、FilterStreamは際オープンされ、状態もリセットされます。
void resetSource();: ソースストリームの状態が変わったので、このFilterStreamの readable, writeable, seekable, isopen, buffering フラグを修正する必要があることを通知します。

class BufferedStream: std.stream.FilterStream;

元ストリームをラップしてバッファリングを行う派生クラスです。

最後のバッファの内容が確実に書き込まれることを保証するため、このクラスのストリームは最後に必ずclose()が必要です。ソースストリームの位置は、ブロックサイズ毎に変更されます。このため、BufferedStream に対する読み書きはソースの位置を同じ量変化させないことがあります。

this(Stream source, size_t bufferSize = DefaultBufferSize);: 指定のバッファサイズ bufferSize でバッファつきストリームを作成します。

class StreamFileException: std.stream.StreamException;

ファイルエラーを表す例外

this(string msg);: 指定のエラーメッセージで StreamFileException を構築

class OpenException: std.stream.StreamFileException;

ファイルオープン中のエラーを表す例外

this(string msg);: 指定のエラーメッセージで OpenFileException を構築

class File: std.stream.Stream;

バッファ無しでファイルシステムのストリームを扱う派生クラスです。

this(string filename, FileMode mode = (FileMode).In);: 1:ファイルを開かず、 2:読み取り専用でファイルを開いて、 3:モードを明示指定してファイルを開いて、ストリームを作成します。 mode は FileMode.In（ファイルを読み込めることを示す）と FileMode.Out（ファイルへ書き込めることを示す）の組み合わせです。存在しないファイルを読みとりオープンするとエラーになります。存在しないファイルを書き込みオープンすると、新しいファイルが作られます。 FileMode.OutNew は書き込み用にファイルを開き、長さ0に設定します。 FileMode.Append は書き込み用にファイルを開き、ファイル終端へ位置を移動します。
void open(string filename, FileMode mode = (FileMode).In);: コンストラクタと同様に、ファイルを開きます。エラー時には OpenException を投げます。
void create(string filename); void create(string filename, FileMode mode);: 書き込み用にファイルを作成します。
void close();: 開いたファイルを閉じます。開かれていない場合は何も起きません。
size_t available();: シーク可能ストリームでは、現在位置とサイズの差を返します。それ以外では、0 を返します。

class BufferedFile: std.stream.BufferedStream;

ファイルシステムのストリームをバッファ付きで扱う派生クラスです。

FileをBufferedStreamでラップする処理をまとめたものです。最後のバッファの内容が確実に書き込まれることを保証するため、このクラスのストリームは最後に必ずclose()が必要です。

this();: 読み込み用にファイルを開く
this(string filename, FileMode mode = (FileMode).In, size_t bufferSize = DefaultBufferSize);: ファイルを指定されたmodeとバッファサイズで開く
this(File file, size_t bufferSize = DefaultBufferSize);: ファイルを指定されたバッファサイズで読み込み用に開く
this(HANDLE hFile, FileMode mode, size_t buffersize);: 既存のハンドルを開く。使い方に注意すること！
void open(string filename, FileMode mode = (FileMode).In);: 指定のmodeでファイルを開く
void create(string filename, FileMode mode = (FileMode).OutNew);: 指定のmodeでファイルを作成

enum BOM;

UTF のバイト順マーク用シグネチャ

UTF8: UTF-8
UTF16LE: UTF-16 Little Endian
UTF16BE: UTF-16 Big Endian
UTF32LE: UTF-32 Little Endian
UTF32BE: UTF-32 Big Endian

class EndianStream: std.stream.FilterStream;

このサブクラスは、big-endian か littile-endian のストリームをラップしてバイト順を交換します。

UTF Byte-Order-Mark (BOM) シグネチャは、自動で読み書きされます。 EndianStream は他の FilterStream のソースとしては使用しないでください。 FilterStream はバイト単位のread/writeでソースのデータを処理しますが、 EndianStream はその場合にはバイト順反転を全く行いません。 EndianStream は (getc 関数以外による) バイナリデータの読み書きを、１対１対応を保ったままで行います。つまり、getc関数以外のみが使われている限りは、ソースストリームの状態と位置を EndianStream と同期した状態に保ちます。

Endian endian;: ソースストリームのエンディアン
this(Stream source, Endian end = module system.endian);: ソースストーリム source を、エンディアン end を指定してラップしたストリームを作ります。デフォルトのエンディアンは、ネイティブのバイト順になります。エンディアン型は、 std.system モジュールで定義されています。
int readBOM(int ungetCharSize = 1);: BOMがなければ-1を返し、あればそのBOMを返します。

BOMがない場合や、BOMを越えて読み込まれたバイトがある場合は、 ungetc か ungetcw のバッファへと書き戻されます。 BOMが無いときに ungetc の代わりに ungetcw を使う場合は、 ungetCharSize == 2 を渡してください。
final void fixBO(const(void)* buffer, size_t size);: バッファのバイト順を、ネイティブのバイト順に合うよう修正します。 size は必ず偶数でなければなりません。
final void fixBlockBO(void* buffer, uint size, size_t repeat);: バッファのバイト順を、ネイティブのバイト順に合うよう修正する操作を指定された回数繰り返します。 size は必ず偶数でなければなりません。
void writeBOM(BOM b);: BOM b をソースストリームに書き込みます。

class TArrayStream(Buffer): Stream;

配列的なバッファをストリームのインターフェイスでラップする、パラメタ付派生クラスです。

Buffer型は、length プロパティと ubyte 型のスライス読みとりをサポートする必要があります。TArrayStream型を直接インスタンス化する場合、リンクエラーを避けるためにreleaseモードでコンパイルしてください。

this(Buffer buf);: バッファ buf 上にストリームを作成します。コピーはしません。
ubyte[] data();: 現在のメモリデータ全体を取得します。

class MemoryStream: std.stream.TArrayStream!(ubyte[]).TArrayStream;

バイト配列から読み書きを行う派生クラスです。

this();: 出力バッファを作成し、読み、書き、シーク用に準備します
this(ubyte[] buf); this(byte[] buf); this(char[] buf);: 出力バッファを作成し、読み、書き、シーク用に準備して、特定の入力データをロードします。
void reserve(size_t count);: ストリームが確実に count バイト保持できるようにバッファを用意します。

class MmFileStream: std.stream.TArrayStream!(MmFile).TArrayStream;

この派生クラスは、メモリマップによるファイル操作をストリームAPIでラップしたものです。 std.mmfile module を参照ください。

this(MmFile file);: file をストリームでラップします。

class SliceStream: std.stream.FilterStream;

この派生クラスは、他のストリームの一部を指定して切り出し切り出し境界からの相対位置で位置指定をできるようにします。

例えばtar書庫のような大きなファイルを複数の小さいファイルとみなす、などの処理に利用できます。元ストリームがシーク可能な場合、SliceStream の読み書きは元ストリームの位置を変更しません。

this(Stream s, ulong low);: 使うソースストリームと、スライスの下限を指定します。

上限はsourceストリームの終端に依存しますので、終端を越えて書き込むと通常通りストリームは拡張します。
this(Stream s, ulong low, ulong high);: 上限も同時に指定します。

指定範囲より先への読み/書きはクリップされます。