D
Language
Phobos
Comparisons
object
std
std.base64
std.boxer
std.compiler
std.conv
std.cover
std.ctype
std.date
std.demangle
std.file
std.format
std.gc
std.intrinsic
std.math
std.md5
std.mmfile
std.openrj
std.outbuffer
std.path
std.process
std.random
std.recls
std.regexp
std.socket
std.socketstream
std.stdint
std.stdio
std.cstream
std.stream
std.string
std.system
std.thread
std.uri
std.utf
std.zip
std.zlib
std.c.fenv
std.c.math
std.c.process
std.c.stdarg
std.c.stddef
std.c.stdio
std.c.stdlib
std.c.string
std.c.time
std.c.wcharh
std.windows.charset
std.windows
std.linux
std.c.windows
std.c.linux
|
std.stream
- class StreamException: object.Exception;
- A base class for stream exceptions.
- this(char[] msg);
- Construct a StreamException with given error message.
- class ReadException: std.stream.StreamException;
- Thrown when unable to read data from Stream.
- this(char[] msg);
- Construct a ReadException with given error message.
- class WriteException: std.stream.StreamException;
- Thrown when unable to write data to Stream.
- this(char[] msg);
- Construct a WriteException with given error message.
- class SeekException: std.stream.StreamException;
- Thrown when unable to move Stream pointer.
- this(char[] msg);
- Construct a SeekException with given error message.
- interface InputStream;
- InputStream is the interface for readable streams.
- void readExact(void* buffer, uint size);
- Read exactly size bytes into the buffer.
Throws a ReadException if it is not correct.
- uint read(ubyte[] buffer);
- Read a block of data big enough to fill the given array buffer.
Returns:
the actual number of bytes read. Unfilled bytes are not modified.
- void read(out byte x);
void read(out ubyte x);
void read(out short x);
void read(out ushort x);
void read(out int x);
void read(out uint x);
void read(out long x);
void read(out ulong x);
void read(out float x);
void read(out double x);
void read(out real x);
void read(out ifloat x);
void read(out idouble x);
void read(out ireal x);
void read(out cfloat x);
void read(out cdouble x);
void read(out creal x);
void read(out char x);
void read(out wchar x);
void read(out dchar x);
void read(out char[] s);
void read(out wchar[] s);
- Read a basic type or counted string.
Throw a ReadException if it could not be read.
Outside of byte, ubyte, and char, the format is
implementation-specific and should not be used except as opposite actions
to write.
- char[] readLine();
char[] readLine(char[] result);
wchar[] readLineW();
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.
- int opApply(int delegate(inout char[] line) dg);
int opApply(int delegate(inout ulong n, inout char[] line) dg);
int opApply(int delegate(inout wchar[] line) dg);
int opApply(int delegate(inout ulong n, inout 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) {
stdout.writefln("line %d: %s",n,line);
}
file.close();
- char[] readString(uint length);
- Read a string of the given length,
throwing ReadException if there was a problem.
- wchar[] readStringW(uint 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.
- char getc();
wchar getcw();
- 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 then getc returns char.init and getcw returns wchar.init.
- char ungetc(char c);
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().
- int vreadf(TypeInfo[] arguments, void* args);
int readf(...);
- Scan a string from the input using a similar form to C's scanf
and std.format.
An argument of type char[] 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 char[]* 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;
char[] 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);
- uint available();
- Retrieve the number of bytes available for immediate reading.
- 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.
- bool isOpen();
- Return true if the stream is currently open.
- interface OutputStream;
- Interface for writable streams.
- void writeExact(void* buffer, uint size);
- Write exactly size bytes from buffer, or throw a WriteException if that
could not be done.
- uint write(ubyte[] buffer);
- Write as much of the buffer as possible,
returning the number of bytes written.
- void write(byte x);
void write(ubyte x);
void write(short x);
void write(ushort x);
void write(int x);
void write(uint x);
void write(long x);
void write(ulong x);
void write(float x);
void write(double x);
void write(real x);
void write(ifloat x);
void write(idouble x);
void write(ireal x);
void write(cfloat x);
void write(cdouble x);
void write(creal x);
void write(char x);
void write(wchar x);
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.
- void write(char[] s);
void write(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.
- void writeLine(char[] s);
- Write a line of text,
appending the line with an operating-system-specific line ending.
Throws WriteException on error.
- void writeLineW(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.
- void writeString(char[] s);
- Write a string of text.
Throws WriteException if it could not be fully written.
- void writeStringW(wchar[] s);
- Write a string of text.
The format is implementation-specific.
Throws WriteException if it could not be fully written.
- uint vprintf(char[] format, void* args);
uint printf(char[] format,...);
- Print a formatted string into the stream using printf-style syntax,
returning the number of bytes written.
- OutputStream writef(...);
OutputStream writefln(...);
OutputStream writefx(TypeInfo[] arguments, void* argptr, int newline = cast(int)false);
- Print a formatted string into the stream using writef-style syntax.
References:
std.format.
Returns:
self to chain with other stream commands like flush.
- void flush();
- Flush pending output if appropriate.
- void close();
- Close the stream, flushing output if appropriate.
- bool isOpen();
- Return true if the stream is currently open.
- class Stream: 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
- 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
- protected bool prevCr;
- For a non-seekable stream indicates that
after the last read attempt.
For a non-seekable stream indicates that
- this();
- the last readLine or readLineW ended on a
'\r' character.
- uint readBlock(void* buffer, uint 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.
- uint writeBlock(void* buffer, uint size);
- Write up to size bytes from buffer in the stream, returning the actual
number of bytes that were written.
- void copyFrom(Stream s);
- 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.
- 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.
- void position(ulong pos);
- Sets file position. Equivalent to calling seek(pos, SeekPos.Set).
- ulong position();
- Returns current file position. Equivalent to seek(0, SeekPos.Current).
- ulong size();
- Retrieve the size of the stream in bytes.
The stream must be seekable or a SeekException is thrown.
- char[] 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.
- uint toHash();
- Get a hash of the stream by reading each byte and using it in a CRC-32
checksum.
- class FilterStream: 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. 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 as
well.
Defaults to true.
- this(Stream source);
- Construct a FilterStream for the given source.
- final Stream source();
- Get the current source stream.
- void source(Stream s);
- Set the current source stream.
Setting the source stream closes this stream before attaching the new
source. Attaching an open stream reopens this stream and resets the stream
state.
- 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;
- 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 the BufferedStream may not change the source stream
position by the same amount.
- this(Stream source, uint bufferSize = 8192u);
- Create a buffered stream for the stream source with the buffer size
bufferSize.
- class StreamFileException: std.stream.StreamException;
- An exception for File errors.
- this(char[] msg);
- Construct a StreamFileException with given error message.
- class OpenException: std.stream.StreamFileException;
- An exception for errors during File.open.
- this(char[] msg);
- Construct an OpenFileException with given error message.
- class File: std.stream.Stream;
- This subclass is for unbuffered file system streams.
- this(char[] filename, FileMode mode = cast(FileMode)1);
- 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(char[] filename, FileMode mode = cast(FileMode)1);
- Open a file for the stream, in an identical manner to the constructors.
If an error occurs an OpenException is thrown.
- void create(char[] filename);
void create(char[] filename, FileMode mode);
- Create a file for writing.
- void close();
- Close the current file if it is open; otherwise it does nothing.
- uint 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.
- enum BOM;
- 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
- 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 = cast(Endian)1);
- 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(void* buffer, uint size);
- Correct the byte order of buffer to match native endianness.
size must be even.
- final void fixBlockBO(void* buffer, uint size, uint 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.
The type Buffer must support the length property, opIndex and opSlice.
Compile in release mode when directly instantiating a TArrayStream to avoid
link errors.
- this(Buffer buf);
- Create the stream for the the buffer buf. Non-copying.
- ubyte[] data();
- Get the current memory data in total.
- class MemoryStream: 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.
- void reserve(uint count);
- Ensure the stream can hold count bytes.
- class MmFileStream: std.stream.TArrayStream!(MmFile).TArrayStream;
- This subclass wraps a memory-mapped file with the stream API.
See std.mmfile module.
- this(MmFile file);
- Create stream wrapper for file.
- class SliceStream: 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 a
SliceStream does not modify the position of the source stream if it is
seekable.
- this(Stream s, ulong low);
- 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.
|