std.stream

classStreamException:object.Exception;

A base class for stream exceptions.

this(stringmsg);

Construct a StreamException with given error message.

classReadException:std.stream.StreamException;

Thrown when unable to read data from Stream.

this(stringmsg);

Construct a ReadException with given error message.

classWriteException:std.stream.StreamException;

Thrown when unable to write data to Stream.

this(stringmsg);

Construct a WriteException with given error message.

classSeekException:std.stream.StreamException;

Thrown when unable to move Stream pointer.

this(stringmsg);

Construct a SeekException with given error message.

interfaceInputStream;

InputStream is the interface for readable streams.

abstract voidreadExact(void*buffer, size_tsize);

Read exactlysize bytes into thebuffer.

Throws a ReadException if it is not correct.

abstract size_tread(ubyte[]buffer);

Read a block of data big enough to fill the given arraybuffer.

Returns:
the actual number of bytesread. Unfilled bytes are not modified.

abstract voidread(out bytex);
abstract voidread(out ubytex);
abstract voidread(out shortx);
abstract voidread(out ushortx);
abstract voidread(out intx);
abstract voidread(out uintx);
abstract voidread(out longx);
abstract voidread(out ulongx);
abstract voidread(out floatx);
abstract voidread(out doublex);
abstract voidread(out realx);
abstract voidread(out ifloatx);
abstract voidread(out idoublex);
abstract voidread(out irealx);
abstract voidread(out cfloatx);
abstract voidread(out cdoublex);
abstract voidread(out crealx);
abstract voidread(out charx);
abstract voidread(out wcharx);
abstract voidread(out dcharx);
abstract voidread(out char[]s);
abstract voidread(out wchar[]s);

Read a basic type or counted string.

Throw a ReadException if it could not beread. Outside of byte, ubyte, and char, the format is implementation-specific and should not be used except as opposite actions to write.

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

Read a line that is terminated with some combination of carriage return and line feed or end-of-file.

The terminators are not included. The wchar version is identical. The optional buffer parameter is filled (reallocating it if necessary) and a slice of the result is returned.

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

Overload foreach statements to read the stream line by line and call the supplied delegate with each line or with each line with line number.

The string passed in line may be reused between calls to the delegate. Line numbering starts at 1. Breaking out of the foreach will leave the stream position at the beginning of the next line to be read. For example, to echo a file line-by-line with line numbers run:

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

abstract char[]readString(size_tlength);

Read a string of the givenlength,

throwing ReadException if there was a problem.

abstract wchar[]readStringW(size_tlength);

Read a string of the givenlength, throwing ReadException if there was a problem.

The file format is implementation-specific and should not be used except as opposite actions towrite.

abstract chargetc();
abstract wchargetcw();

Read and return the next character in the stream.

This is the only method that will handle ungetc properly. getcw's format is implementation-specific. If EOF is reached thengetc returns char.init and getcw returns wchar.init.

abstract charungetc(charc);
abstract wcharungetcw(wcharc);

Push a character back onto the stream.

They will be returned in first-in last-out order from getc/getcw. Only has effect on further calls to getc() and getcw().

abstract intvreadf(TypeInfo[]arguments, va_listargs);
abstract intreadf(...);

Scan a string from the input using a similar form to C's scanf andstd.format.

An argument of type string is interpreted as a format string. All otherarguments must be pointer types. If a format string is not present a default will be supplied computed from the base type of the pointer type. An argument of type string* is filled (possibly with appending characters) and a slice of the result is assigned back into the argument. For example the following readf statements are equivalent:

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 @property size_tavailable();

Retrieve the number of bytesavailable for immediate reading.

abstract @property booleof();

Return whether the current file position is the same as the end of the file.

This does not require actually reading past the end, as with stdio. For non-seekable streams this might only returntrue after attempting to read past the end.

abstract @property boolisOpen();

Returntrue if the stream is currently open.

interfaceOutputStream;

Interface for writable streams.

abstract voidwriteExact(const void*buffer, size_tsize);

Write exactlysize bytes frombuffer, or throw a WriteException if that could not be done.

abstract size_twrite(const(ubyte)[]buffer);

Write as much of thebuffer as possible, returning the number of bytes written.

abstract voidwrite(bytex);
abstract voidwrite(ubytex);
abstract voidwrite(shortx);
abstract voidwrite(ushortx);
abstract voidwrite(intx);
abstract voidwrite(uintx);
abstract voidwrite(longx);
abstract voidwrite(ulongx);
abstract voidwrite(floatx);
abstract voidwrite(doublex);
abstract voidwrite(realx);
abstract voidwrite(ifloatx);
abstract voidwrite(idoublex);
abstract voidwrite(irealx);
abstract voidwrite(cfloatx);
abstract voidwrite(cdoublex);
abstract voidwrite(crealx);
abstract voidwrite(charx);
abstract voidwrite(wcharx);
abstract voidwrite(dcharx);

Write a basic type.

Outside of byte, ubyte, and char, the format is implementation-specific and should only be used in conjunction with read. Throw WriteException on error.

abstract voidwrite(const(char)[]s);
abstract voidwrite(const(wchar)[]s);

Writes a string, together with its length.

The format is implementation-specific and should only be used in conjunction with read. Throw WriteException on error.

abstract voidwriteLine(const(char)[]s);

Write a line of text, appending the line with an operating-system-specific line ending.

Throws WriteException on error.

abstract voidwriteLineW(const(wchar)[]s);

Write a line of text, appending the line with an operating-system-specific line ending.

The format is implementation-specific. Throws WriteException on error.

abstract voidwriteString(const(char)[]s);

Write a string of text.

Throws WriteException if it could not be fully written.

abstract voidwriteStringW(const(wchar)[]s);

Write a string of text.

The format is implementation-specific. Throws WriteException if it could not be fully written.

abstract size_tvprintf(const(char)[]format, va_listargs);
abstract size_tprintf(const(char)[]format, ...);

Print a formatted string into the stream using printf-style syntax, returning the number of bytes written.

abstract OutputStreamwritef(...);
abstract OutputStreamwritefln(...);
abstract OutputStreamwritefx(TypeInfo[]arguments, va_listargptr, intnewline = false);

Print a formatted string into the stream usingwritef-style syntax.

References:
std.format.

Returns:
self to chain with other stream commands like flush.

abstract voidflush();

Flush pending output if appropriate.

abstract voidclose();

Close the stream, flushing output if appropriate.

abstract @property boolisOpen();

Returntrue if the stream is currently open.

abstract classStream:std.stream.InputStream,std.stream.OutputStream;

Stream is the base abstract class from which the other stream classes derive.

Stream's byte order is the format native to the computer.

Reading:
These methods require that the readable flag be set. Problems with reading result in a ReadException being thrown.Stream implements the InputStream interface in addition to the readBlock method.

Writing:
These methods require that the writeable flag be set. Problems with writing result in a WriteException being thrown.Stream implements the OutputStream interface in addition to the following methods: writeBlock copyFrom copyFrom

Seeking:
These methods require that the seekable flag be set. Problems with seeking result in a SeekException being thrown. seek, seekSet, seekCur, seekEnd, position, size, toString, toHash

boolreadable;

Indicates whether this stream can be read from.

boolwriteable;

Indicates whether this stream can be written to.

boolseekable;

Indicates whether this stream can be seeked within.

protected boolisopen;

Indicates whether this stream is open.

protected boolreadEOF;

Indicates whether this stream is at eof after the last read attempt.

protected boolprevCr;

For a non-seekable stream indicates that the last readLine or readLineW ended on a '\r' character.

abstract size_treadBlock(void*buffer, size_tsize);

Read up tosize bytes into thebuffer and return the number of bytes actually read. A return value of 0 indicates end-of-file.

abstract size_twriteBlock(const void*buffer, size_tsize);

Write up tosize bytes frombuffer in the stream, returning the actual number of bytes that were written.

voidcopyFrom(Streams);

Copies all data froms into this stream. This may throw ReadException or WriteException on failure. This restores the file position ofs so that it is unchanged.

voidcopyFrom(Streams, ulongcount);

Copy a specified number of bytes from the given stream into this one. This may throw ReadException or WriteException on failure. Unlike the previous form, this doesn't restore the file position ofs.

abstract ulongseek(longoffset, SeekPoswhence);

Change the current position of the stream.whence is either SeekPos.Set, in which case theoffset is an absolute index from the beginning of the stream, SeekPos.Current, in which case theoffset is a delta from the current position, or SeekPos.End, in which case theoffset is a delta from the end of the stream (negative or zero offsets only make sense in that case). This returns the new file position.

ulongseekSet(longoffset);
ulongseekCur(longoffset);
ulongseekEnd(longoffset);

Aliases for their normal seek counterparts.

@property voidposition(ulongpos);

Sets fileposition. Equivalent to calling seek(pos, SeekPos.Set).

@property ulongposition();

Returns current fileposition. Equivalent to seek(0, SeekPos.Current).

@property ulongsize();

Retrieve thesize of the stream in bytes. The stream must be seekable or a SeekException is thrown.

stringtoString();

Read the entire stream and return it as a string. If the stream is not seekable the contents from the current position to eof is read and returned.

@trusted size_ttoHash();

Get a hash of the stream by reading each byte and using it in a CRC-32 checksum.

classFilterStream:std.stream.Stream;

A base class for streams that wrap a source stream with additional functionality.

The method implementations forward read/write/seek calls to the source stream. AFilterStream can change the position of the source stream arbitrarily and may not keep the source stream state in sync with theFilterStream, even upon flushing and closing theFilterStream. It is recommended to not make any assumptions about the state of the source position and read/write state after aFilterStream has acted upon it. Specifc subclasses ofFilterStream should document how they modify the source stream and if any invariants holdtrue between the source and filter.

boolnestClose;

Property indicating when this stream closes to close the source stream as

well.

Defaults totrue.

this(Streamsource);

Construct a FilterStream for the givensource.

final Streamsource();

Get the currentsource stream.

voidsource(Streams);

Set the currentsource stream.

Setting thesource stream closes this stream before attaching the newsource. Attaching an open stream reopens this stream and resets the stream state.

voidresetSource();

Indicates the source stream changed state and that this stream should reset any readable, writeable, seekable, isopen and buffering flags.

classBufferedStream:std.stream.FilterStream;

This subclass is for buffering a source stream.

A buffered stream must be closed explicitly to ensure the final buffer content is written to the source stream. The source stream position is changed according to the block size so reading or writing to theBufferedStream may not change the source stream position by the same amount.

this(Streamsource, size_tbufferSize = DefaultBufferSize);

Create a buffered stream for the streamsource with the buffer sizebufferSize.

classStreamFileException:std.stream.StreamException;

An exception for File errors.

this(stringmsg);

Construct a StreamFileException with given error message.

classOpenException:std.stream.StreamFileException;

An exception for errors during File.open.

this(stringmsg);

Construct an OpenFileException with given error message.

enumFileMode: int;

Specifies theFile access mode used when opening the file.

In

Opens the file for reading.

Out

Opens the file for writing.

OutNew

Opens the file for writing, creates a new file if it doesn't exist.

Append

Opens the file for writing, appending new data to the end of the file.

classFile:std.stream.Stream;

This subclass is for unbuffered file system streams.

this(stringfilename, FileModemode = FileMode.In);

Create the stream with no open file, an open file in readmode, or an open file with explicit filemode.mode, if given, is a combination of FileMode.In (indicating a file that can be read) and FileMode.Out (indicating a file that can be written). Opening a file for reading that doesn't exist will error. Opening a file for writing that doesn't exist will create the file. The FileMode.OutNewmode will open the file for writing and reset the length to zero. The FileMode.Appendmode will open the file for writing and move the file position to the end of the file.

voidopen(stringfilename, FileModemode = FileMode.In);

Open a file for the stream, in an identical manner to the constructors. If an error occurs an OpenException is thrown.

voidcreate(stringfilename);
voidcreate(stringfilename, FileModemode);

Create a file for writing.

voidclose();

Close the current file if it is open; otherwise it does nothing.

@property size_tavailable();

For a seekable file returns the difference of the size and position and otherwise returns 0.

classBufferedFile:std.stream.BufferedStream;

This subclass is for buffered file system streams.

It is a convenience class for wrapping a File in a BufferedStream. A buffered stream must be closed explicitly to ensure the final buffer content is written to the file.

this();

opens file for reading

this(stringfilename, FileModemode = FileMode.In, size_tbufferSize = DefaultBufferSize);

opens file in requestedmode and buffer size

this(Filefile, size_tbufferSize = DefaultBufferSize);

opensfile for reading with requested buffer size

this(HANDLEhFile, FileModemode, size_tbuffersize = DefaultBufferSize);

opens existing handle; use with care!

voidopen(stringfilename, FileModemode = FileMode.In);

opens file in requestedmode

voidcreate(stringfilename, FileModemode = FileMode.OutNew);

creates file in requestedmode

enumBOM: int;

UTF byte-order-mark signatures

UTF8

UTF-8

UTF16LE

UTF-16 Little Endian

UTF16BE

UTF-16 Big Endian

UTF32LE

UTF-32 Little Endian

UTF32BE

UTF-32 Big Endian

classEndianStream:std.stream.FilterStream;

This subclass wraps a stream with big-endian or little-endian byte order swapping.

UTF Byte-Order-Mark (BOM) signatures can be read and deduced or written. Note that anEndianStream should not be used as the source of another FilterStream since a FilterStream call the source with byte-oriented read/write requests and theEndianStream will not perform any byte swapping. TheEndianStream reads and writes binary data (non-getc functions) in a one-to-one manner with the source stream so the source stream's position and state will be kept in sync with theEndianStream if only non-getc functions are called.

Endianendian;

Endianness property of the source stream.

this(Streamsource, Endianend = std.system.endian);

Create the endian stream for thesource streamsource with endiannessend. The default endianness is the native byte order. The Endian type is defined in the std.system module.

intreadBOM(intungetCharSize = 1);

Return -1 if no BOM and otherwise read the BOM and return it.

If there is no BOM or if bytes beyond the BOM are read then the bytes read are pushed back onto the ungetc buffer or ungetcw buffer. PassungetCharSize == 2 to use ungetcw instead of ungetc when no BOM is present.

final voidfixBO(const(void)*buffer, size_tsize);

Correct the byte order ofbuffer to match native endianness.size must be even.

final voidfixBlockBO(void*buffer, uintsize, size_trepeat);

Correct the byte order of the givenbuffer in blocks of the givensize and repeated the given number of times.size must be even.

voidwriteBOM(BOMb);

Write the specified BOMb to the source stream.

classTArrayStream(Buffer): Stream;

Parameterized subclass that wraps an array-like buffer with a stream interface.

The type Buffer must support the length property, opIndex and opSlice. Compile in release mode when directly instantiating aTArrayStream to avoid link errors.

this(Bufferbuf);

Create the stream for the the bufferbuf. Non-copying.

@property ubyte[]data();

Get the current memorydata in total.

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

This subclass reads and constructs an array of bytes in memory.

this();

Create the output buffer and setup for reading, writing, and seeking.

this(ubyte[]buf);
this(byte[]buf);
this(char[]buf);

Create the output buffer and setup for reading, writing, and seeking. Load it with specific input data.

voidreserve(size_tcount);

Ensure the stream can writecount extra bytes from cursor position without an allocation.

classMmFileStream:std.stream.TArrayStream!(MmFile).TArrayStream;

This subclass wraps a memory-mapped file with the stream API. See std.mmfile module.

this(MmFilefile);

Create stream wrapper forfile.

classSliceStream:std.stream.FilterStream;

This subclass slices off a portion of another stream, making seeking relative to the boundaries of the slice.

It could be used to section a large file into a set of smaller files, such as with tar archives. Reading and writing aSliceStream does not modify the position of the source stream if it is seekable.

this(Streams, ulonglow);

Indicate both the source stream to use for reading from and thelow part of the slice.

The high part of the slice is dependent upon the end of the source stream, so that if you write beyond the end it resizes the stream normally.

this(Streams, ulonglow, ulonghigh);

Indicate thehigh index as well.

Attempting to read or write past thehigh index results in the end being clipped off.