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

interface ITextStream in Tinman.Core.IO.Streams

An IDataStream object provides access to a file in the filesystem in a stream oriented (i.e. sequential) manner.

interface ITextStream extends ICanReadWrite
  ICopyable<ITextStream>
  IDisposable
  IFlushable
  IPathInfo
  base of TextStreamBase

Remarks

The interface provides methods for manipulating the file cursor of the underlying file in the filesystem and methods for reading and writing of single bytes values and blocks of bytes.

Additional methods provide support for reading and writing of multibyte values, byte endianess and a file cursor stack for simplified navigation in data streams that support seeking.

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

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

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.

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.

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.

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.

Read

Reads a number of characters from the stream.

method Read (char[] chars, int32 offset = 0, int32 count = -1)
type int32
params chars [not-null] The buffer where the read characters will be stored.
  offset [0..chars.Length] Offset into chars. Defaults to 0.
  count [-1..chars.Length-offset] Number of characters to read. If -1, characters will be read up to the end of chars. Defaults to -1.
returns [>=0] The number of characters that have been read into chars. A value of 0 indicates that the end of the stream has been reached (assuming that the given count was greater than zero).

Remarks:

The number of characters that are read from the stream may be less than the given count, for any reason.

Exceptions:

ReadChar

Reads a single character from the stream.

method ReadChar ()
type char
returns The read character.

Exceptions:

ReadToEnd

Reads all remaining characters from this stream and disposes this stream afterwards.

[OwnerThis]
method ReadToEnd ()
type string
returns [not-null] The read string.

Skip

Skips the next characters in the stream.

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

TryReadChar

Reads a single character from the stream.

method TryReadChar ()
type int32
returns [>=-1] The read character or -1 if the end of the stream has been reached.

Exceptions:

Write

Writes a number of characters to the stream.

method Write (string chars)
params chars [not-null] The characters to write.

Exceptions:

Writes a number of characters to the stream.

method Write (char[] chars)
params chars [not-null] The characters to write.

Exceptions:

Writes a number of characters to the stream.

method Write (string chars, int32 offset, int32 count)
params chars [not-null] The characters to write.
  offset [>=0] Offset into chars.
  count [>=0] Number of characters to write.

Exceptions:

Writes a number of characters to the stream.

method Write (char[] chars, int32 offset, int32 count)
params chars [not-null] The characters to write.
  offset [>=0] Offset into chars.
  count [>=0] Number of characters to write.

Exceptions:

WriteChar

Writes a single characters to the stream.

method WriteChar (char value)
params value The character to write.

Exceptions:

Extensions

DecodeBase85

Decodes binary data using a base-85 encoding after reading it from this text stream.

[OwnerReturn, OwnerThis]
method DecodeBase85 ()
type IDataStream
returns [not-null] The read-only data stream.

Remarks:

This is the mapping between base-85 digits and printable 7-bit ASCII characters: 

!#$%()*+,-.0123456789:;=?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[^_abcdefghijklmnopqrstuvwxyz{|}~
^         ^         ^         ^         ^         ^         ^         ^         ^    ^
0         10        20        30        40        50        60        70        80   85
The following printable ASCII characters are not used by the encoding, which allows encoded string to be used safely in various contexts (e.g. string literals, XML text, XML attributes, XML CDATA sections): 
"&'/<>\]`

EncodeBase85

Encodes binary data using a base-85 encoding before writing it to this text stream.

[OwnerReturn, OwnerThis]
method EncodeBase85 (int32 columns = 80, LineEnding lineEnding = LineEnding.Native)
type IDataStream
params columns [>=0] Number of columns to output before a line break is emitted. If set to 0, no line breaks will be emitted at all. Defaults to 80.
  lineEnding The line ending token to use for emitting line breaks. Defaults to Native.
returns [not-null] The write-only data stream.

Remarks:

This is the mapping between base-85 digits and printable 7-bit ASCII characters: 

!#$%()*+,-.0123456789:;=?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[^_abcdefghijklmnopqrstuvwxyz{|}~
^         ^         ^         ^         ^         ^         ^         ^         ^    ^
0         10        20        30        40        50        60        70        80   85
The following printable ASCII characters are not used by the encoding, which allows encoded string to be used safely in various contexts (e.g. string literals, XML text, XML attributes, XML CDATA sections): 
"&'/<>\]`

ReadEof

Reads a number of characters from the stream.

method ReadEof (char[] chars, int32 offset = 0, int32 count = -1)
type int32
params chars [not-null] The buffer where the read characters will be stored.
  offset [0..chars.Length] Offset into chars. Defaults to 0.
  count [-1..chars.Length-offset] Number of characters to read. If -1, characters will be read up to the end of chars. Defaults to -1.
returns [>=0] The number of characters that have been read into chars. A value of 0 indicates that the end of the stream has been reached (assuming that the given count was greater than zero).

Remarks:

The number of characters that are read from the stream will be less than the given count only if the end of the stream has been reached.

Exceptions:

Tinman 3D SDK v1.0 | info@tinman3d.com | Copyright © 2012 - 2017 Matthias Englert, Fulda (Germany)