TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface IDataStream in Tinman.Core.IO.Streams

An IDataStream object provides access to a stream of bytes.

interface IDataStream extends IBinaryReader
  IBinaryWriter
  ICanReadWrite
  ICopyable<IDataStream>
  IDataStreamOps
  IDisposable
  IPathInfo
  base of DataStreamBase

Remarks

It is not necessary to call Flush resp. Finish before disposing a data stream.

All non-abstract implementations of IDataStream are required to call Finish when they are about to get disposed (e.g. first statement of DisposeManaged).

Attributes

CanRead

Does this object support read access?

property CanRead { get }
type bool
value true if this object supports reading, false if not.
inherited ICanReadWrite.CanRead

CanSeek

Does this stream support seeking (via Position)?

property CanSeek { get }
type bool
value true if this stream supports seeking, false if not.

CanWrite

Does this binary object support write access?

property CanWrite { get }
type bool
value true if this object supports writing, false if not.
inherited ICanReadWrite.CanWrite

Endianess

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

property Endianess { get set }
type ByteOrder
value The byte-order to use.

Remarks:

The default byte-order is LittleEndian.

IsFinished

Has writing to this data stream finished?

property IsFinished { get }
type bool
value true if the data stream writes have finished, false if not.

See also:

Finish

Length

Length of this data stream.

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

LifecycleState

Returns the lifecycle state of this object.

property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited ILifecycleState.LifecycleState

PathInfo

Returns a Path object that represents the file path this object is associated with.

property PathInfo { get }
type Path
value [not-null] The path info.
inherited IPathInfo.PathInfo

Remarks:

Objects that do not have a meaningful file path association simply return Unknown.

Position

The current position of the file cursor.

property Position { get set }
type int64
value [>=0] The file cursor position, as an absolute offset from the beginning of the file, in bytes.

Exceptions:

Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method AcquireTry ()
type IDisposable
returns this if a new strong reference has been acquired, null if this object is already being disposed.
inherited IDisposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Background

Uses a background thread to prefetch data from this data stream.

[OwnerReturn, OwnerThis]
method Background (int32 bufferSize = 65536, int32 bufferCount = 16)
type IDataStream
params bufferSize [>0] The buffer size, in bytes. Defaults to 65536.
  bufferCount [>0] The buffer count. Defaults to 16.
returns [not-null] The sequential read-only data stream.
inherited IDataStreamOps.Background

Remarks:

If this data stream is already being prefetched in a background thread, this method may return this.

The resulting data stream does not support seeking (i.e. CanSeek returns false) and it will be in read-only ( CanRead) mode.

Buffer

Wraps this data stream in a buffered stream.

[OwnerReturn, OwnerThis]
method Buffer (int32 bufferSize = 65536)
type IDataStream
params bufferSize [>0] The buffer size, in bytes. Defaults to 65536.
returns [not-null] The buffered data stream.
inherited IDataStreamOps.Buffer

Remarks:

If this data stream is already buffered in memory, this method may return this.

If both read and write operations are going to be used on the returned stream, seeking must be supported by this stream (see CanSeek).

CopyFrom

Copies all remaining data in the given object to this object.

method CopyFrom (T stream)
params stream [not-null] The object.
inherited ICopyable.CopyFrom

CopyTo

Copies all remaining data in this object to the given object.

method CopyTo (T stream)
params stream [not-null] The object.
inherited ICopyable.CopyTo

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
method Dispose ()
inherited IDisposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

Finish

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

method Finish ()

Flush

Flushes all cached data.

method Flush ()
inherited IFlushable.Flush

Remarks:

Performing a flush may result in I/O work. Depending on the semantics of the implementing class, this work may need to be wrapped in special Begin / End method calls. See the documentation of the implementing classes for details.

In case this object represents a read-only resource, calling the Flush method has no effect.

PopPosition

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

method PopPosition ()

Remarks:

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.

Exceptions:

PushPosition

Pushes the current file cursor position onto the stack.

method PushPosition ()

Remarks:

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.

Exceptions:

Read

Reads a number of bytes from the stream.

method Read (ByteBuffer bytes)
type int32
params bytes [not-null] The buffer where the read bytes will be stored.
returns [>=0] The number of bytes the have been read.
inherited IBinaryReader.Read

Remarks:

The number of bytes that are read from the stream may be less than the number of Remaining bytes in the given ByteBuffer, for any arbitrary reason.

Exceptions:

ReadAll

Reads a number of bytes from the stream.

method ReadAll (ByteBuffer bytes)
params bytes [not-null] The buffer where the read bytes will be stored.
inherited IBinaryReader.ReadAll

Remarks:

The number of bytes that are read from the stream will be equal to the number of Remaining bytes in the given ByteBuffer.

Exceptions:

ReadFloat32

Reads a 32-bit floating point value from the data stream.

method ReadFloat32 ()
type float32
returns The read value.
inherited IBinaryReader.ReadFloat32

Exceptions:

ReadFloat32s

Reads 32-bit floating point values from the data stream.

method ReadFloat32s (float32[] array, int32 offset, int32 count)
params array [not-null] The output array.
  offset [>=0] Index of first array element to write.
  count [>=0] Number of values to read.
returns The read value.
inherited IBinaryReader.ReadFloat32s

Exceptions:

ReadFloat64

Reads a 64-bit floating point value from the data stream.

method ReadFloat64 ()
type float64
returns The read value.
inherited IBinaryReader.ReadFloat64

Exceptions:

ReadFloat64s

Reads 64-bit floating point values from the data stream.

method ReadFloat64s (float64[] array, int32 offset, int32 count)
params array [not-null] The output array.
  offset [>=0] Index of first array element to write.
  count [>=0] Number of values to read.
returns The read value.
inherited IBinaryReader.ReadFloat64s

Exceptions:

ReadInt16

Reads a signed 16-bit integer value from the data stream using.

method ReadInt16 ()
type int16
returns The read value.
inherited IBinaryReader.ReadInt16

Exceptions:

ReadInt16s

Reads signed 16-bit integer value values from the data stream.

method ReadInt16s (int16[] array, int32 offset, int32 count)
params array [not-null] The output array.
  offset [>=0] Index of first array element to write.
  count [>=0] Number of values to read.
returns The read value.
inherited IBinaryReader.ReadInt16s

Exceptions:

ReadInt32

Reads a signed 32-bit integer value from the data stream.

method ReadInt32 ()
type int32
returns The read value.
inherited IBinaryReader.ReadInt32

Exceptions:

ReadInt32s

Reads signed 32-bit integer value values from the data stream.

method ReadInt32s (int32[] array, int32 offset, int32 count)
params array [not-null] The output array.
  offset [>=0] Index of first array element to write.
  count [>=0] Number of values to read.
returns The read value.
inherited IBinaryReader.ReadInt32s

Exceptions:

ReadInt64

Reads a signed 64-bit integer value from the data stream.

method ReadInt64 ()
type int64
returns The read value.
inherited IBinaryReader.ReadInt64

Exceptions:

ReadInt64s

Reads signed 64-bit integer value values from the data stream.

method ReadInt64s (int64[] array, int32 offset, int32 count)
params array [not-null] The output array.
  offset [>=0] Index of first array element to write.
  count [>=0] Number of values to read.
returns The read value.
inherited IBinaryReader.ReadInt64s

Exceptions:

ReadInt8

Reads an 8-bit value from the stream.

method ReadInt8 ()
type int8
returns The read value.
inherited IBinaryReader.ReadInt8

Exceptions:

ReadInt8s

Reads signed 8-bit integer value values from the data stream.

method ReadInt8s (int8[] array, int32 offset, int32 count)
params array [not-null] The output array.
  offset [>=0] Index of first array element to write.
  count [>=0] Number of values to read.
returns The read value.
inherited IBinaryReader.ReadInt8s

Exceptions:

ReadToEnd

Reads all remaining data from this stream and disposes it.

[OwnerReturn, OwnerThis]
method ReadToEnd ()
type ByteBuffer
returns [not-null] The read bytes.
inherited IDataStreamOps.ReadToEnd

ReadUInt16

Reads an unsigned 16-bit integer value from the data stream.

method ReadUInt16 ()
type int32
returns The read value.
inherited IBinaryReader.ReadUInt16

Exceptions:

ReadUInt32

Reads an unsigned 32-bit integer value from the data stream.

method ReadUInt32 ()
type int64
returns The read value.
inherited IBinaryReader.ReadUInt32

Exceptions:

ReadUInt8

Reads an unsigned 8-bit integer from the data stream.

method ReadUInt8 ()
type int32
returns The read value.
inherited IBinaryReader.ReadUInt8

Exceptions:

Skip

Skips the next bytes in the stream.

method Skip (int64 count)
params count [>=0] The number of bytes to skip.

ToFile

Converts this data stream into a random-access file.

[OwnerReturn, OwnerThis]
method ToFile ()
type IFile
returns [not-null] The data file.
inherited IDataStreamOps.ToFile

Remarks:

It may be necessary to copy the data stream bytes to a temporary file.

ToTextStream

Creates an ITextStream from the data of this object.

[OwnerReturn, OwnerThis]
method ToTextStream (CharacterEncoding encoding)
type ITextStream
params encoding [not-null] The character encoding to use.
returns [not-null] The data stream.
inherited ITextStreamFactory.ToTextStream

TryReadUInt8

Reads an unsigned 8-bit value from the stream.

method TryReadUInt8 ()
type int32
returns [-1..255] The unsigned 8-bit value or -1 if the end of the stream has been reached.
inherited IBinaryReader.TryReadUInt8

Write

Writes a number of bytes to the stream.

method Write (ByteBuffer bytes)
params bytes [not-null] The bytes to write.
inherited IBinaryWriter.Write

Exceptions:

WriteFloat32

Writes a 32-bit floating point value to the data stream.

method WriteFloat32 (float32 value)
params value The value to write.
inherited IBinaryWriter.WriteFloat32

Exceptions:

WriteFloat32s

Writes 32-bit floating point values to the data stream.

method WriteFloat32s (float32[] array, int32 offset, int32 count)
params array [not-null] The input array.
  offset [>=0] Index of first array element to read.
  count [>=0] Number of values to write.
returns The read value.
inherited IBinaryWriter.WriteFloat32s

Exceptions:

WriteFloat64

Writes a 64-bit floating point value to the data stream.

method WriteFloat64 (float64 value)
params value The value to write.
inherited IBinaryWriter.WriteFloat64

Exceptions:

WriteFloat64s

Writes 64-bit floating point values to the data stream.

method WriteFloat64s (float64[] array, int32 offset, int32 count)
params array [not-null] The input array.
  offset [>=0] Index of first array element to read.
  count [>=0] Number of values to write.
returns The read value.
inherited IBinaryWriter.WriteFloat64s

Exceptions:

WriteInt16

Writes a signed 16-bit integer value to the data stream.

method WriteInt16 (int16 value)
params value The value to write.
inherited IBinaryWriter.WriteInt16

Exceptions:

WriteInt16s

Writes signed 16-bit integer values to the data stream.

method WriteInt16s (int16[] array, int32 offset, int32 count)
params array [not-null] The input array.
  offset [>=0] Index of first array element to read.
  count [>=0] Number of values to write.
returns The read value.
inherited IBinaryWriter.WriteInt16s

Exceptions:

WriteInt32

Writes a signed 32-bit integer value to the data stream.

method WriteInt32 (int32 value)
params value The value to write.
inherited IBinaryWriter.WriteInt32

Exceptions:

WriteInt32s

Writes signed 32-bit integer values to the data stream.

method WriteInt32s (int32[] array, int32 offset, int32 count)
params array [not-null] The input array.
  offset [>=0] Index of first array element to read.
  count [>=0] Number of values to write.
returns The read value.
inherited IBinaryWriter.WriteInt32s

Exceptions:

WriteInt64

Writes a signed 64-bit integer value to the data stream.

method WriteInt64 (int64 value)
params value The value to write.
inherited IBinaryWriter.WriteInt64

Exceptions:

WriteInt64s

Writes signed 64-bit integer values to the data stream.

method WriteInt64s (int64[] array, int32 offset, int32 count)
params array [not-null] The input array.
  offset [>=0] Index of first array element to read.
  count [>=0] Number of values to write.
returns The read value.
inherited IBinaryWriter.WriteInt64s

Exceptions:

WriteInt8

Writes an 8-bit integer value to the stream.

method WriteInt8 (int8 value)
params value The value to write.
inherited IBinaryWriter.WriteInt8

Exceptions:

WriteInt8s

Writes signed 8-bit integer values to the data stream.

method WriteInt8s (int8[] array, int32 offset, int32 count)
params array [not-null] The input array.
  offset [>=0] Index of first array element to read.
  count [>=0] Number of values to write.
returns The read value.
inherited IBinaryWriter.WriteInt8s

Exceptions:

Extensions

Codec

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

[OwnerReturn, OwnerThis]
method Codec (IBlockCodec codec)
type IDataStream
params codec [not-null] The block codec to use.
returns [not-null] The encoded resp. decoded data stream.

Remarks:

For encoding (i.e. Mode is 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 given data stream.

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

Deflate

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

[OwnerReturn, OwnerThis]
method Deflate (bool skipHeader, int32 compressionLevel = 6)
type IDataStream
params skipHeader Write the RFC-1950 stream header?
  compressionLevel [0..9] The compression level. Defaults to 6.
returns [not-null] The compressing data stream.

Inflate

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

[OwnerReturn, OwnerThis]
method Inflate (bool skipHeader, Path pathInfo = null, string fileFormatName = null, int64 length = 0)
type IDataStream
params skipHeader Input stream has no RFC-1950 header bytes?
  pathInfo Optional path info. Defaults to null.
  fileFormatName Name of the enclosing file format (this is purely informational). Defaults to null.
  length [>=0] Length of uncompressed data. Defaults to 0.
returns [not-null] The decompressing data stream.

ReadBom

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

[OwnerReturn, OwnerThis]
method ReadBom (CharacterEncoding encoding = null)
type ITextStream
params encoding The character encoding to use if no BOM is found. If null, ASCII will be used. Defaults to null.
returns [not-null] The data stream.

Remarks:

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 not BOM is found, the given default encoding is used.

Unzip

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

[OwnerReturn, OwnerThis]
method Unzip (string entry = null)
type IDataStream
params entry Name of archive entry to extract. If null, the first entry will be extracted.
returns [not-null] The resulting data stream.

WriteBom

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

[OwnerReturn, OwnerThis]
method WriteBom (CharacterEncoding encoding = null)
type ITextStream
params encoding The character encoding to use if no BOM is found. If null, ASCII will be used. Defaults to null.
returns [not-null] The data stream.

Remarks:

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