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

class MemoryDataStream in Tinman.Core.IO.Streams

An implementation of the IDataStream that uses a growing memory buffer.

sealed class MemoryDataStream extends DataStreamBase
  implements IInternalBuffer<ByteBuffer>

Public / Attributes

CanRead

Does this object support read access?

public override property CanRead { get }
type bool
value true if this object supports reading, false if not.
implements DataStreamBase.CanRead

CanSeek

Does this stream support seeking (via Position)?

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

CanWrite

Does this binary object support write access?

public override property CanWrite { get }
type bool
value true if this object supports writing, false if not.
implements DataStreamBase.CanWrite

Endianess

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

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

Remarks:

The default byte-order is LittleEndian.

InternalBuffer

Returns the internal data buffer of this object.

public property InternalBuffer { get }
type ByteBuffer
value [not-null] The internal buffer.
implements IInternalBuffer.InternalBuffer

Remarks:

In most cases, client code will never use the internal buffer of an object. However, under some circumstances it can be advantageous to access the internal buffer directly (e.g. in order to avoid copy operations, reduce amount of produced garbage). Messing with the internal buffer of an object will result in undefined behaviour. So anyone using the internal buffer must know exactly what he or she is doing.

IsFinished

Has writing to this data stream finished?

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

See also:

IDataStream.Finish

Length

Length of this data stream.

public override 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.
implements DataStreamBase.Length

LifecycleState

Returns the lifecycle state of this object.

public virtual property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited Disposable.LifecycleState

PathInfo

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

public override property PathInfo { get }
type Path
value [not-null] The path info.
implements DataStreamBase.PathInfo

Remarks:

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

Position

The current position of the file cursor.

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

Exceptions:

Public / Constructors

MemoryDataStream

Creates a new instance of MemoryDataStream.

public constructor MemoryDataStream (int32 initialCapacity = 65536)
params initialCapacity [>=0] The initial buffer size, in bytes. Defaults to 65536.

Remarks:

The stream will be in write mode.

See also:

Flip

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method AcquireTry ()
type IDisposable
returns this if a new strong reference has been acquired, null if this object is already being disposed.
inherited Disposable.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]
public override 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.
overrides DataStreamBase.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]
public override 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.
overrides DataStreamBase.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).

Clear

Clears this memory stream so that it can be used again for writing.

public method Clear (int32 initialBufferSize = 0)
params initialBufferSize [>=0] The initial buffer size or 0.

Remarks:

After returning, the stream will be in write mode.

CopyFrom

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

public virtual method CopyFrom (IDataStream stream)
params stream [not-null] The object.
inherited DataStreamBase.CopyFrom

CopyTo

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

public virtual method CopyTo (IDataStream stream)
params stream [not-null] The object.
inherited DataStreamBase.CopyTo

CreatePool

Creates an object pool for MemoryDataStream objects of the given size.

[OwnerReturn]
public static method CreatePool (string name, int32 size, int32 count)
type ObjectPool<MemoryDataStream>
params name [not-empty] Name of the object pool.
  size [>0] The size of each memory data stream, in bytes.
  count [>0] The maximum number of memory data streams in the pool.
returns [not-null] The object pool.

Remarks:

Each MemoryDataStream object that is returned by the object pool will already have its state reset via Clear.

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]
public method Dispose ()
inherited Disposable.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.

public method Finish ()
inherited DataStreamBase.Finish

Flip

Flips this memory stream so that it reads back the data that has been written to it.

public method Flip ()

Remarks:

When calling this method, the stream must be in write mode. After returning, the stream will be in read mode.

See also:

ToBuffer

Flush

Flushes all cached data.

public virtual method Flush ()
inherited DataStreamBase.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.

For

Creates a new instance of MemoryDataStream that reads the given data.

[OwnerReturn]
public static method For (ByteBuffer bytes)
type MemoryDataStream
params bytes [not-null] The bytes to read.
returns [not-null] The created data stream.

Remarks:

The stream will be in read mode.


Creates a new instance of MemoryDataStream that reads the given data.

[OwnerReturn]
public static method For (int8[] bytes)
type MemoryDataStream
params bytes [not-null] The bytes to read.
returns [not-null] The created data stream.

Remarks:

The stream will be in read mode.


Creates a new instance of MemoryDataStream that reads the given data.

[OwnerReturn]
public static method For (int8[] bytes, int32 offset, int32 count)
type MemoryDataStream
params bytes [not-null] The bytes to read.
  offset [>=0] Offset into bytes to first byte to read.
  count [>=0] Total number of bytes to read.
returns [not-null] The created data stream.

Remarks:

The stream will be in read mode.

PopPosition

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

public method PopPosition ()
inherited DataStreamBase.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.

public method PushPosition ()
inherited DataStreamBase.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.

public override 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.
implements DataStreamBase.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.

public method ReadAll (ByteBuffer bytes)
params bytes [not-null] The buffer where the read bytes will be stored.
inherited DataStreamBase.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.

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

Exceptions:

ReadFloat32s

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

public virtual 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 DataStreamBase.ReadFloat32s

Exceptions:

ReadFloat64

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

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

Exceptions:

ReadFloat64s

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

public 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 DataStreamBase.ReadFloat64s

Exceptions:

ReadInt16

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

public override method ReadInt16 ()
type int16
returns The read value.
overrides DataStreamBase.ReadInt16

Exceptions:

ReadInt16s

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

public 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 DataStreamBase.ReadInt16s

Exceptions:

ReadInt32

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

public override method ReadInt32 ()
type int32
returns The read value.
overrides DataStreamBase.ReadInt32

Exceptions:

ReadInt32s

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

public 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 DataStreamBase.ReadInt32s

Exceptions:

ReadInt64

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

public override method ReadInt64 ()
type int64
returns The read value.
overrides DataStreamBase.ReadInt64

Exceptions:

ReadInt64s

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

public 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 DataStreamBase.ReadInt64s

Exceptions:

ReadInt8

Reads an 8-bit value from the stream.

public override method ReadInt8 ()
type int8
returns The read value.
overrides DataStreamBase.ReadInt8

Exceptions:

ReadInt8s

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

public 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 DataStreamBase.ReadInt8s

Exceptions:

ReadToEnd

Reads all remaining data from this stream and disposes it.

[OwnerReturn, OwnerThis]
public override method ReadToEnd ()
type ByteBuffer
returns [not-null] The read bytes.
overrides DataStreamBase.ReadToEnd

ReadUInt16

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

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

Exceptions:

ReadUInt32

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

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

Exceptions:

ReadUInt8

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

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

Exceptions:

Skip

Skips the next bytes in the stream.

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

ToBuffer

Returns the current content of this memory stream.

[OwnerReturn]
public method ToBuffer ()
type ByteBuffer
returns [not-null] A byte buffer holding a copy of the current stream content.

Remarks:

When calling this method, the stream must be in write mode. The stream state is not modified by this method.

See also:

Flip

ToFile

Converts this data stream into a random-access file.

[OwnerReturn, OwnerThis]
public virtual method ToFile ()
type IFile
returns [not-null] The data file.
inherited DataStreamBase.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]
public virtual method ToTextStream (CharacterEncoding encoding)
type ITextStream
params encoding [not-null] The character encoding to use.
returns [not-null] The data stream.
inherited DataStreamBase.ToTextStream

TryReadUInt8

Reads an unsigned 8-bit value from the stream.

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

Wrap

Creates a new instance of MemoryDataStream that reads the given data.

[OwnerReturn]
public static method Wrap ([Owner] ByteBuffer bytes)
type MemoryDataStream
params bytes [not-null] The byte buffer to wrap.
returns [not-null] The wrapping data stream.

Remarks:

The stream will be in read mode.

Write

Writes a number of bytes to the stream.

public override method Write (ByteBuffer bytes)
params bytes [not-null] The bytes to write.
implements DataStreamBase.Write

Exceptions:

WriteChunk

Prepares the internal buffer of this memory stream for writing a chunk of bytes.

public method WriteChunk (int32 count)
type ByteBuffer
params count [>=0] The maximum number of bytes that will be written to the returned buffer.
returns [not-null] The internal buffer, correctly positioned, with at least count remaining bytes.

WriteFloat32

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

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

Exceptions:

WriteFloat32s

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

public virtual 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 DataStreamBase.WriteFloat32s

Exceptions:

WriteFloat64

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

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

Exceptions:

WriteFloat64s

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

public virtual 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 DataStreamBase.WriteFloat64s

Exceptions:

WriteInt16

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

public override method WriteInt16 (int16 value)
params value The value to write.
overrides DataStreamBase.WriteInt16

Exceptions:

WriteInt16s

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

public virtual 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 DataStreamBase.WriteInt16s

Exceptions:

WriteInt32

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

public override method WriteInt32 (int32 value)
params value The value to write.
overrides DataStreamBase.WriteInt32

Exceptions:

WriteInt32s

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

public virtual 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 DataStreamBase.WriteInt32s

Exceptions:

WriteInt64

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

public override method WriteInt64 (int64 value)
params value The value to write.
overrides DataStreamBase.WriteInt64

Exceptions:

WriteInt64s

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

public virtual 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 DataStreamBase.WriteInt64s

Exceptions:

WriteInt8

Writes an 8-bit integer value to the stream.

public override method WriteInt8 (int8 value)
params value The value to write.
implements DataStreamBase.WriteInt8

Exceptions:

WriteInt8s

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

public virtual 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 DataStreamBase.WriteInt8s

Exceptions: