std.stream
Jump to: BOM · BufferedFile · BufferedStream · EndianStream · File · FileMode · FilterStream · InputStream · MemoryStream · MmFileStream · OpenException · OutputStream · ReadException · SeekException · SliceStream · Stream · StreamException · StreamFileException · TArrayStream · WriteException
Source: std/stream.d
- class StreamException: object.Exception;
Jump to: this
- A base class for stream exceptions.
- class ReadException: std.stream.StreamException;
Jump to: this
- Thrown when unable to read data from Stream.
- class WriteException: std.stream.StreamException;
Jump to: this
- Thrown when unable to write data to Stream.
- class SeekException: std.stream.StreamException;
Jump to: this
- Thrown when unable to move Stream pointer.
- interface InputStream;
Jump to: available · eof · getc · getcw · isOpen · opApply · read · readExact · readf · readLine · readLineW · readString · readStringW · ungetc · ungetcw · vreadf
-
- abstract void readExact(void* buffer, size_t size);
- Read exactly size bytes into the buffer.Throws a ReadException if it is not correct.
- abstract size_t read(ubyte[] buffer);
Jump to: 2
- Read a block of data big enough to fill the given array buffer.
- 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); - Read a basic type or counted string.
- 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 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); - 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_t length);
- Read a string of the given length,throwing ReadException if there was a problem.
- abstract wchar[] readStringW(size_t length);
- Read a string of the given length, throwing ReadException if there was a problem.The file format is implementation-specific and should not be used except as opposite actions to write.
- abstract char getc();
abstract wchar getcw(); - Read and return the next character in the stream.
- abstract char ungetc(char c);
abstract wchar ungetcw(wchar c); - 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 int vreadf(TypeInfo[] arguments, va_list args);
abstract int readf(...); - Scan a string from the input using a similar form to C's scanf and std.format.An argument of type string is interpreted as a format string. All other arguments 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_t available();
- abstract @property bool eof();
- 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 return true after attempting to read past the end.
- abstract @property bool isOpen();
- Return true if the stream is currently open.
- interface OutputStream;
Jump to: close · flush · isOpen · printf · vprintf · write · writeExact · writef · writefln · writefx · writeLine · writeLineW · writeString · writeStringW
- Interface for writable streams.
- abstract void writeExact(const void* buffer, size_t size);
- Write exactly size bytes from buffer, or throw a WriteException if that could not be done.
- abstract size_t write(const(ubyte)[] buffer);
- Write as much of the buffer as possible, returning the number of bytes written.
- 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); - 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 void write(const(char)[] s);
abstract void write(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 void writeLine(const(char)[] s);
- Write a line of text, appending the line with an operating-system-specific line ending.Throws WriteException on error.
- abstract void writeLineW(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 void writeString(const(char)[] s);
- Write a string of text.Throws WriteException if it could not be fully written.
- abstract void writeStringW(const(wchar)[] s);
- Write a string of text.The format is implementation-specific. Throws WriteException if it could not be fully written.
- abstract size_t vprintf(const(char)[] format, va_list args);
abstract size_t printf(const(char)[] format, ...); - abstract OutputStream writef(...);
abstract OutputStream writefln(...);
abstract OutputStream writefx(TypeInfo[] arguments, va_list argptr, int newline = false); -
References: std.format.
Returns:self to chain with other stream commands like flush. - abstract void flush();
- Flush pending output if appropriate.
- abstract void close();
- Close the stream, flushing output if appropriate.
- abstract @property bool isOpen();
- Return true if the stream is currently open.
- abstract class Stream: std.stream.InputStream, std.stream.OutputStream;
Jump to: copyFrom · isopen · position · prevCr · readable · readBlock · readEOF · seek · seekable · seekCur · seekEnd · seekSet · size · toHash · toString · writeable · writeBlock
-
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
- bool readable;
- Indicates whether this stream can be read from.
- bool writeable;
- Indicates whether this stream can be written to.
- bool seekable;
- Indicates whether this stream can be seeked within.
- protected bool isopen;
- Indicates whether this stream is open.
- protected bool readEOF;
- Indicates whether this stream is at eof after the last read attempt.
- protected bool prevCr;
- For a non-seekable stream indicates that the last readLine or readLineW ended on a '\r' character.
- abstract size_t readBlock(void* buffer, size_t size);
- Read up to size bytes into the buffer and return the number of bytes actually read. A return value of 0 indicates end-of-file.
- abstract size_t writeBlock(const void* buffer, size_t size);
- Write up to size bytes from buffer in the stream, returning the actual number of bytes that were written.
- void copyFrom(Stream s);
Jump to: 2
- Copies all data from s into this stream. This may throw ReadException or WriteException on failure. This restores the file position of s so that it is unchanged.
- void copyFrom(Stream s, ulong count);
- 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 of s.
- abstract ulong seek(long offset, SeekPos whence);
- Change the current position of the stream. whence is either SeekPos.Set, in which case the offset is an absolute index from the beginning of the stream, SeekPos.Current, in which case the offset is a delta from the current position, or SeekPos.End, in which case the offset 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.
- ulong seekSet(long offset);
ulong seekCur(long offset);
ulong seekEnd(long offset); - Aliases for their normal seek counterparts.
- @property void position(ulong pos);
Jump to: 2
- @property ulong position();
- @property ulong size();
- string toString();
- 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_t toHash();
- Get a hash of the stream by reading each byte and using it in a CRC-32 checksum.
- class FilterStream: std.stream.Stream;
Jump to: nestClose · resetSource · source · this
- 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. A FilterStream can change the position of the source stream arbitrarily and may not keep the source stream state in sync with the FilterStream, even upon flushing and closing the FilterStream. It is recommended to not make any assumptions about the state of the source position and read/write state after a FilterStream has acted upon it. Specifc subclasses of FilterStream should document how they modify the source stream and if any invariants hold true between the source and filter.
- bool nestClose;
- Property indicating when this stream closes to close the source stream aswell. Defaults to true.
- this(Stream source);
- Construct a FilterStream for the given source.
- final Stream source();
Jump to: 2
- void source(Stream s);
- void resetSource();
- Indicates the source stream changed state and that this stream should reset any readable, writeable, seekable, isopen and buffering flags.
- class BufferedStream: std.stream.FilterStream;
Jump to: this
- This subclass is for buffering a source stream.
- class StreamFileException: std.stream.StreamException;
Jump to: this
- An exception for File errors.
- class OpenException: std.stream.StreamFileException;
Jump to: this
- An exception for errors during File.open.
- enum FileMode: int;
- Specifies the File access mode used when opening the file.
- class File: std.stream.Stream;
- This subclass is for unbuffered file system streams.
- this(string filename, FileMode mode = FileMode.In);
- Create the stream with no open file, an open file in read mode, or an open file with explicit file mode. 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.OutNew mode will open the file for writing and reset the length to zero. The FileMode.Append mode will open the file for writing and move the file position to the end of the file.
- void open(string filename, FileMode mode = FileMode.In);
- Open a file for the stream, in an identical manner to the constructors. If an error occurs an OpenException is thrown.
- void create(string filename);
void create(string filename, FileMode mode); - Create a file for writing.
- void close();
- Close the current file if it is open; otherwise it does nothing.
- @property size_t available();
- For a seekable file returns the difference of the size and position and otherwise returns 0.
- class BufferedFile: 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(string filename, FileMode mode = FileMode.In, size_t bufferSize = DefaultBufferSize);
- opens file in requested mode and buffer size
- this(File file, size_t bufferSize = DefaultBufferSize);
- opens file for reading with requested buffer size
- this(HANDLE hFile, FileMode mode, size_t buffersize = DefaultBufferSize);
- opens existing handle; use with care!
- void open(string filename, FileMode mode = FileMode.In);
- opens file in requested mode
- void create(string filename, FileMode mode = FileMode.OutNew);
- creates file in requested mode
- enum BOM: int;
- UTF byte-order-mark signatures
- class EndianStream: 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 an EndianStream should not be used as the source of another FilterStream since a FilterStream call the source with byte-oriented read/write requests and the EndianStream will not perform any byte swapping. The EndianStream 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 the EndianStream if only non-getc functions are called.
- Endian endian;
- Endianness property of the source stream.
- this(Stream source, Endian end = std.system.endian);
- Create the endian stream for the source stream source with endianness end. The default endianness is the native byte order. The Endian type is defined in the std.system module.
- int readBOM(int ungetCharSize = 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. Pass ungetCharSize == 2 to use ungetcw instead of ungetc when no BOM is present.
- final void fixBO(const(void)* buffer, size_t size);
- Correct the byte order of buffer to match native endianness. size must be even.
- final void fixBlockBO(void* buffer, uint size, size_t repeat);
- Correct the byte order of the given buffer in blocks of the given size and repeated the given number of times. size must be even.
- void writeBOM(BOM b);
- Write the specified BOM b to the source stream.
- class TArrayStream(Buffer): Stream;
- Parameterized subclass that wraps an array-like buffer with a stream interface.
- class MemoryStream: std.stream.TArrayStream!(ubyte[]).TArrayStream;
- This subclass reads and constructs an array of bytes in memory.
- this();
Jump to: 2
- 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.
- void reserve(size_t count);
- Ensure the stream can write count extra bytes from cursor position without an allocation.
- class MmFileStream: std.stream.TArrayStream!(MmFile).TArrayStream;
Jump to: this
- This subclass wraps a memory-mapped file with the stream API. See std.mmfile module.
- class SliceStream: std.stream.FilterStream;
Jump to: this
- 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 a SliceStream does not modify the position of the source stream if it is seekable.
- this(Stream s, ulong low);
Jump to: 2
- Indicate both the source stream to use for reading from and the low 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(Stream s, ulong low, ulong high);
- Indicate the high index as well.Attempting to read or write past the high index results in the end being clipped off.