IDataStream

Description

interface Tinman.Core.IO.Streams.IDataStream

Derived from: IDisposableGeneric<IDataStream>
IDataStreamOps
IBinaryReader
IBinaryWriter
IPathInfo
ICanReadWrite
ITransferable<IDataStream>
Extended by: DataStreamBase ^abstract

A IDataStream object provides access to a stream of bytes.

All non-abstract implementations of IDataStream are required to call Finish when they are about to get disposed (e.g. first statement of Disposable.DisposeResources). If an error happens during that call, it will be logged, instead of being thrown as an exception. As best practice, code that writes to a data stream should call the Finish method before disposing the stream.

Public / Methods

Finish

public method Finish → ()

Flushes the data stream and tells it that no more data will be written to it.

After calling this method, ICanWrite.CanWrite will return false. Aggregated data streams will not be finished, so data may still be written to them.

IOException: If an I/O error has occurred.

PopPosition

public method PopPosition → ()

Pops the topmost position from the stack and sets the current file cursor position to that value.

The PushPosition and PopPosition are convenience methods that can be used jump back and forth in the file for reading/writing disjoint blocks of data.

IOException: If an I/O error has occurred.

PushPosition

public method PushPosition → ()

Pushes the current file cursor position onto the stack.

The PushPosition and PopPosition are convenience methods that can be used jump back and forth in the file for reading/writing disjoint blocks of data.

IOException: If an I/O error has occurred.

Skip

public method Skip → (1)

count ⁱⁿ : int64: [>=0]
The number of bytes to skip.

Skips the next bytes in the stream.

IOException: If an I/O error has occurred.

Public / Attributes

CanSeek

public attribute CanSeek → (get)

value : bool: true if this stream supports seeking, false if not.

Does this stream support seeking (via Position)?

Endianness

public attribute Endianness → (get,set)

value : ByteOrder: The byte-order to use.

The byte-order to use for reading and writing multibyte values.

The default byte-order is ByteOrder.LittleEndian.

IsFinished

public attribute IsFinished → (get)

value : bool: true if the data stream writes have finished, false if not.

Has writing to this data stream finished?

See also: IDataStream.Finish

Length

public attribute Length → (get)

value : int64: [>=0]
The length of this data stream. If the length is unknown resp. the stream does not support seeking (see CanSeek), 0 is returned.

Length of this data stream.

IOException: If an I/O error has occurred.

Position

public attribute Position → (get,set)

value : int64: [>=0]
The file cursor position, as an absolute offset from the beginning of the file, in bytes.

The current position of the file cursor.

Settings this property to its current value will never throw a IOException because of CanSeek returning false.

IOException: If an I/O error has occurred.

Extensions

Codec

[OwnerReturn] [OwnerThis]
public static method Codec → (1)

codec ⁱⁿ : IBlockCodec: [not-null]
The block codec to use.
returns → IDataStream: The encoded resp. decoded data stream.

Encodes resp. decodes data using the given block codec before writing it to resp. after reading it from this stream.

For encoding (i.e. IBlockCodec.Mode is CodecMode.Encode), the returned data stream will be write-only: Data that is written to it will be divided into blocks which then get processed by this codec. Block padding will be performed with random data, if necessary. Processed blocks are chained with XOR before being written to the this data stream.

For decoding (i.e. IBlockCodec.Mode is CodecMode.Decode), the returned data stream will be read-only: Data will be read from this data stream in blocks, which then get processed by this codec.

Deflate

[OwnerReturn] [OwnerThis]
public static method Deflate → (2)

skipHeader ⁱⁿ : bool: Write the RFC-1950 stream header?
compressionLevel ^opt : int32 = 6: [0..9]
The compression level.
returns → IDataStream: The compressing data stream.

Compresses data using RFC 1950/1951 before writing it to this stream.

IOException: If this stream does not support writing.

Inflate

[OwnerReturn] [OwnerThis]
public static method Inflate → (4)

skipHeader ⁱⁿ : bool: Input stream has no RFC-1950 header bytes?
pathInfo ^opt : Path = null: Optional path info.
fileFormatName ^opt : string = null: Name of the enclosing file format (this is purely informational).
length ^opt : int64 = 0: [>=0]
Length of uncompressed data.
returns → IDataStream: The decompressing data stream.

Decompresses data using RFC 1950/1951 after reading it from this stream.

IOException: If this stream does not support reading.

ReadBom

[OwnerReturn] [OwnerThis]
public static method ReadBom → (1)

encoding ^opt : CharacterEncoding = null: The character encoding to use if no BOM is found. If null, CharacterEncodingSimple.ASCII will be used.
returns → ITextStream: The data stream.

Creates a ITextStream from the data of this object, consuming resp. byte order marks (BOM) at the current stream position.

The method tries to identify the following byte order marks (BOM) at the current stream position, in order to automatically determine the character encoding:

0xEF 0xBB 0xBF : CharacterEncoding.UTF_8
0xFE 0xFF : CharacterEncoding.UTF_16_BE
0xFF 0xFE : CharacterEncoding.UTF_16_LE

If no BOM is found, the given default encoding ^opt is used.

IOException: If an I/O error has occurred.

Unzip

[OwnerReturn] [OwnerThis]
public static method Unzip → (1)

entry ^opt : string = null: Name of archive entry to extract. If null, the first entry will be extracted.
returns → IDataStream: The resulting data stream.

Interprets the given data stream as a ZIP/GZ archive and extracts the given entry.

IOException: If this stream does not support reading, if the data format is invalid or if some other I/O error has occurred.

UnzipNames

public static method UnzipNames → ()

returns → IVectorConst<string>: List of archive entry names.

Interprets the given data stream as a ZIP/GZ archive and extracts the names of all entries.

The stream position will be modified by this method.

IOException: If this stream does not support reading, if the data format is invalid or if some other I/O error has occurred.

WriteBom

[OwnerReturn] [OwnerThis]
public static method WriteBom → (1)

encoding ^opt : CharacterEncoding = null: The character encoding to use if no BOM is found. If null, CharacterEncodingSimple.ASCII will be used.
returns → ITextStream: The data stream.

Creates a ITextStream from the data of this object, emitting byte order marks (BOM) at the current stream position.

The method will output the byte order marks according to the specified encoding ^opt:

0xEF 0xBB 0xBF : CharacterEncoding.UTF_8
0xFE 0xFF : CharacterEncoding.UTF_16_BE
0xFF 0xFE : CharacterEncoding.UTF_16_LE

IOException: If an I/O error has occurred.