www.digitalmars.com [Home] [Search] [D]
Last update Jan 15, 2005

Phobos: std.stream

interface InputStream
InputStream is the interface for readable streams.

void readExact(void* buffer, uint size)
Read exactly size bytes into the buffer, throwing a ReadException if it is not correct.

uint read(ubyte[] buffer)
Read a block of data big enough to fill the given array and return 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, throwing 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[] buffer)
wchar[] readLineW()
wchar[] readLineW(wchar[] buffer)
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. When a buffer is supplied as a parameter it is filled unless the content does not fit in the buffer, in which case a new buffer is allocated, filled and returned.

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.

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.

int scanf(char[] fmt, ...)
int vscanf(char[] fmt, va_list args)
Scan a string from the input using a similar form to C's scanf.

uint available()
Retrieve the nubmer of bytes available for immediate reading.


interface OutputStream
OutputStream is the 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)
void write(char[] s)
void write(wchar[] s)
Write a basic type or counted string. Outside of byte, ubyte, and char, the format is implementation-specific and should only be used in conjunction with read.

void writeLine(char[] s)
Write a line of text, appending the line with an operating-system-specific line ending.

void writeLineW(wchar[] s)
Write a line of text, appending the line with an operating-system-specific line ending. The format is implementation-specific.

void writeString(char[] s)
Write a string of text, throwing WriteException if it could not be fully written.

void writeStringW(wchar[] s)
Write a string of text, throwing WriteException if it could not be fully written. The format is implementation-dependent.

uint printf(char[] format, ...)
uint vprintf(char[] format, va_list args)
Print a formatted string into the stream using printf-style syntax, returning the number of bytes written.

void writef(...)
void writefln(...)
Print a formatted string into the stream using writef-style syntax. See std.format


class Stream : InputStream,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.

bit readable
Indicates whether this stream can be read from.

bit writeable
Indicates whether this stream can be written to.

bit seekable
Indicates whether this stream can be seeked within.

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 following methods.

uint readBlock(void* buffer, uint size)
Read up to size bytes into the buffer and return the number of bytes actually read.

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.

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, uint 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.

Seeking

These methods require that the seekable flag be set. Problems with seeking result in a SeekException being thrown.

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.

ulong position()
void position(ulong pos)
Retrieve or set the file position, identical to calling seek(0, SeekPos.Current) or seek(pos, SeekPos.Set) respectively.

ulong size()
Retrieve the size of the stream in bytes.

bit 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 of the file, as with stdio.

bit isOpen()
Return true if the stream is currently open.

void flush()
Flush pending output if appropriate.

void close()
Close the stream, flushing output if appropriate.

char[] toString()
Read the entire stream and return it as a string.

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


class BufferedStream : Stream
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.

this(Stream source, uint bufferSize = 8192)
Create a buffered stream for the stream source with the buffer size bufferSize.

class File : Stream
This subclass is for file system streams.

this()
this(char[] 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 legnth 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 = FileMode.In)
Open a file for the stream, in an identical manner to the constructors.

void create(char[] filename, FileMode mode = FileMode.OutNew)
Create a file for the stream.

void close()
Close the current file if it is open; otherwise it does nothing.

uint readBlock(void* buffer, uint size)
uint writeBlock(void* buffer, uint size)
ulong seek(long offset, SeekPos rel)
Overrides of the Stream methods.


class BufferedFile : 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()
this(char[] filename, FileMode mode = FileMode.In, uint buffersize = 8192)
this(File file, uint buffersize = 8192)
void open(char[] filename, FileMode mode = FileMode.In)
void create(char[] filename, FileMode mode = FileMode.OutNew)
void close()
uint readBlock(void* buffer, uint size)
uint writeBlock(void* buffer, uint size)
ulong seek(long offset, SeekPos rel)
Overrides of the Stream methods.


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 : Stream
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.

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.
Endian endian
property for endianness of the source stream
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.
void writeBOM(BOM b)
Write the BOM b to the source stream
final void fixBO(void* buffer, uint size)
fix the byte order of the given buffer to match the native order
final void fixBlockBO(void* buffer, uint size, uint repeat)
fix the byte order of the given buffer in blocks of the given size and repeated the given number of times


class TArrayStream(Buffer) : Stream
This subclass wraps an array-like buffer with a stream interface. The type Buffer must support the length property and reading ubyte slices.

this(Buffer buf)
Create the stream for the the buffer buf.
uint readBlock(void* buffer, uint size)
uint writeBlock(void* buffer, uint size)
ulong seek(long offset, SeekPos rel)
char[] toString()
Overrides of Stream methods.


class MemoryStream : TArrayStream!(ubyte[])
This subclass reads and constructs an array of bytes in memory.

this()
this(ubyte[] data)
Create the output buffer and setup for reading, writing, and seeking. The second constructor loads it with specific input data.

ubyte[] data()
Get the current memory data in total.

uint readBlock(void* buffer, uint size)
uint writeBlock(void* buffer, uint size)
ulong seek(long offset, SeekPos rel)
char[] toString()
Overrides of Stream methods.


class MmFileStream : TArrayStream!(MmFile)
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 : Stream
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.

this(Stream base, int low)
Indicate both the base 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 base stream, so that if you write beyond the end it resizes the stream normally.

this(Stream base, int low, int high)
Indicate the high index as well. Attempting to read or write past the high index results in the end being clipped off.

uint readBlock(void* buffer, uint size)
uint writeBlock(void* buffer, uint size)
ulong seek(long offset, SeekPos rel)
Overrides of Stream methods.

Copyright (c) 2004-2005 by Digital Mars, All Rights Reserved