class BufferDataStreamBase in Tinman.Core.IO.Streams

Abstract base class for IDataStream implementations that use a memory buffer for increasing I/O performance.

abstract class

BufferDataStreamBase

extends

DataStreamBase

Public / Attributes

CanRead

Does this object support read access?

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

CanSeek

Does this stream support seeking (via Position)?

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

CanWrite

Does this binary object support write access?

public abstract property	CanWrite { get }
type	bool
value		true if this object supports writing, false if not.
inherited	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.

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 sealed 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 abstract property	PathInfo { get }
type	Path
value	[not-null]	The path info.
inherited	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 sealed 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:

• TinmanException:
  
  • If the parameters are invalid.
  • If an I/O error occurs.
  • If the position is set and CanSeek return false.

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 virtual 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	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 sealed 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).

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

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

Flush

Flushes all cached data.

public override method	Flush ()
overrides	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.

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:

• TinmanException:
  
  • If the stack is empty.
  • If an I/O error occurs.
  • If CanSeek return false.

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:

• TinmanException:
  
  • If an I/O error occurs.
  • If CanSeek return false.

Read

Reads a number of bytes from the stream.

public override sealed 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:

• TinmanException:
  
  • If the parameters are invalid.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the parameters are invalid.
  • If an I/O error occurs.
  • The end of file has been reached.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

ReadInt8

Reads an 8-bit value from the stream.

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

Exceptions:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

ReadToEnd

Reads all remaining data from this stream and disposes it.

[OwnerReturn, OwnerThis]
public virtual method	ReadToEnd ()
type	ByteBuffer
returns		[not-null]	The read bytes.
inherited	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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

ReadUInt8

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

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

Exceptions:

• TinmanException:
  
  • If the end of the stream has been reached.
  • If an I/O error occurs.

Skip

Skips the next bytes in the stream.

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

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 sealed 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

Write

Writes a number of bytes to the stream.

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

Exceptions:

• TinmanException:
  
  • If the parameters are invalid.
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

WriteInt16

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

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

Exceptions:

• TinmanException:
  
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

WriteInt32

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

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

Exceptions:

• TinmanException:
  
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

WriteInt64

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

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

Exceptions:

• TinmanException:
  
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

WriteInt8

Writes an 8-bit integer value to the stream.

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

Exceptions:

• TinmanException:
  
  • If an I/O error occurs.

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:

• TinmanException:
  
  • If an I/O error occurs.

Protected / Attributes

ShallFlush

Checks if the stream has any buffered data to write upon next flush.

protected property	ShallFlush { get }
type	bool
value		true if data will be flushed, false if not.

Protected / Constructors

BufferDataStreamBase

Creates a new instance of BufferDataStreamBase.

protected constructor	BufferDataStreamBase (int32 bufferSize, int64 initialPosition, int64 initialLength)
params	bufferSize		The buffer size, in bytes.
	initialPosition		The initial stream position.
	initialLength		The initial stream length.

Protected / Methods

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method	DisposeManaged ()
overrides	DataStreamBase.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.

protected virtual method	DisposeUnmanaged ()
inherited	Disposable.DisposeUnmanaged

Remarks:

Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.

The DisposeUnmanaged method is called after the DisposeManaged method.

DoFinish

Finishes writing to this data stream.

[EmptyBody]
protected override method	DoFinish ()
overrides	DataStreamBase.DoFinish

Remarks:

The Flush method will be called after this method has returned.

DoRead

Reads a number of bytes.

protected abstract method	DoRead (int64 position, ByteBuffer buffer)
type	int64
params	position		The stream position to start reading at.
	buffer		The output buffer.
returns			The number of read bytes.

DoWrite

Writes a number of bytes.

protected abstract method	DoWrite (int64 position, ByteBuffer buffer)
params	position		The stream position to start writing at.
	buffer		The input buffer.