IDataStream

Description

interface Tinman.Core.IO.Streams.IDataStream

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.

Pop​Position


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.

Push​Position


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 in : 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

Can​Seek


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.

Is​Finished


public attribute IsFinished → (get)

value : bool

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

Has writing to this data stream finished?

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

Read​Bom


[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:

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.

Unzip​Names


[OwnerReturn]
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.

Write​Bom


[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:

IOException

If an I/O error has occurred.