Class GorgonBinaryReader

An extended binary reader class.

Inheritance

object

BinaryReader

GorgonBinaryReader

Implements

IDisposable

Inherited Members

BinaryReader.Close()

BinaryReader.Dispose(bool)

BinaryReader.Dispose()

BinaryReader.PeekChar()

BinaryReader.Read()

BinaryReader.ReadBoolean()

BinaryReader.ReadByte()

BinaryReader.ReadSByte()

BinaryReader.ReadChar()

BinaryReader.ReadInt16()

BinaryReader.ReadUInt16()

BinaryReader.ReadInt32()

BinaryReader.ReadUInt32()

BinaryReader.ReadInt64()

BinaryReader.ReadUInt64()

BinaryReader.ReadSingle()

BinaryReader.ReadDouble()

BinaryReader.ReadDecimal()

BinaryReader.ReadString()

BinaryReader.Read(char[], int, int)

BinaryReader.ReadChars(int)

BinaryReader.Read(byte[], int, int)

BinaryReader.ReadBytes(int)

BinaryReader.FillBuffer(int)

BinaryReader.Read7BitEncodedInt()

BinaryReader.BaseStream

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.IO

Assembly: Gorgon.Core.dll

Syntax

public class GorgonBinaryReader : BinaryReader, IDisposable

Remarks

This object extends the functionality of the BinaryReader type by adding extra functions to read from a pointer (or nint), and from generic value types.

Constructors

GorgonBinaryReader(Stream, bool)

Initializes a new instance of the GorgonBinaryReader class.

Declaration

public GorgonBinaryReader(Stream input, bool keepStreamOpen = false)

Parameters

Type	Name	Description
Stream	input	Input stream.
bool	keepStreamOpen	[Optional] true to keep the underlying stream open when the writer is closed, false to close when done.

GorgonBinaryReader(Stream, Encoding, bool)

Initializes a new instance of the GorgonBinaryReader class.

Declaration

public GorgonBinaryReader(Stream input, Encoding encoder, bool keepStreamOpen = false)

Parameters

Type	Name	Description
Stream	input	Input stream.
Encoding	encoder	Encoding for the binary reader.
bool	keepStreamOpen	[Optional] true to keep the underlying stream open when the writer is closed, false to close when done.

Properties

BufferSize

Property to set or return the size of the buffer, in bytes, used to stream the data in.

Declaration

public int BufferSize { get; set; }

Property Value

Type	Description
int

Remarks

This value is meant to help in buffering data from the data source if the data is large. It will only accept a value between 128 and 81920. The upper bound is to ensure that the temporary buffer is not pushed into the Large Object Heap.

KeepStreamOpen

Property to return whether to keep the underlying stream open or not after the reader is closed.

Declaration

public bool KeepStreamOpen { get; }

Property Value

Type	Description
bool

Methods

Read(ref byte, int)

Function to read bytes from a stream into a reference to a buffer.

Declaration

public void Read(ref byte buffer, int size)

Parameters

Type	Name	Description
byte	buffer	The reference to the buffer to fill with data.
int	size	Number of bytes to read.

Remarks

This method will read the number of bytes specified by the size parameter into memory referenced by buffer.

caution

This method is unsafe, therefore a proper size must be passed to the method. Failure to do so can lead to memory corruption. Use this method at your own peril.

Read(void*, int)

Function to read bytes from a stream into a buffer pointed at by the pointer.

Declaration

public void Read(void* pointer, int size)

Parameters

Type	Name	Description
void*	pointer	Pointer to the buffer to fill with data.
int	size	Number of bytes to read.

Remarks

This method will read the number of bytes specified by the size parameter into memory pointed at by the raw pointer.

caution

This method is unsafe, therefore a proper size must be passed to the method. Failure to do so can lead to memory corruption. Use this method at your own peril.

ReadRange<T>(GorgonPtr<T>, int, int?)

Function to read a range of generic values.

Declaration

public void ReadRange<T>(GorgonPtr<T> pointer, int startIndex = 0, int? count = null) where T : unmanaged

Parameters

Type	Name	Description
GorgonPtr<T>	pointer	Pointer to memory that will store the values.
int	startIndex	[Optional] Starting index in the pointer.
int?	count	[Optional] Number of elements to copy.

Type Parameters

Name	Description
T	Type of value to read. Must be an unmanaged value type.

Remarks

This will read data from the binary stream into the specified memory pointer containing values of type T. The values will be populated starting at the startIndex up to the count specified. If the count is not specified (i.e. it is null), then the entire memory block minus the startIndex will be used.

important

The type referenced by T type parameter must have a StructLayoutAttribute with a Sequential or Explicit struct layout. Otherwise, .NET may rearrange the members and the data may not appear in the correct place.

Value types with marshalling attributes (MarshalAsAttribute) are not supported and will not be read correctly.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the pointer parameter is null.
ArgumentOutOfRangeException	Thrown when the startIndex parameter is less than 0. -or- Thrown when the startIndex parameter is equal to or greater than the number of elements in the value parameter. -or- Thrown when the sum of startIndex and count is greater than the number of elements in the value parameter.
IOException	Thrown when the stream is write-only.

ReadRange<T>(int)

Function to read a range of generic values.

Declaration

public T[] ReadRange<T>(int count) where T : unmanaged

Parameters

Type	Name	Description
int	count	Number of array elements to copy.

Returns

Type	Description
T[]	An array filled with values of type T.

Type Parameters

Name	Description
T	Type of value to read. Must be an unmanaged value type.

Remarks

This method will read the specified count of values of type T into an array from a binary data stream and return that array.

important

The return value for this type will always create a new array of type T. This may be inefficient depending on the use case.

important

The type referenced by T type parameter must have a StructLayoutAttribute with a Sequential or Explicit struct layout. Otherwise, .NET may rearrange the members and the data may not appear in the correct place.

Value types with marshalling attributes (MarshalAsAttribute) are not supported and will not be read correctly.

Exceptions

Type	Condition
IOException	Thrown when the stream is write-only.

ReadRange<T>(Span<T>)

Function to read a range of generic values into a span.

Declaration

public void ReadRange<T>(Span<T> buffer) where T : unmanaged

Parameters

Type	Name	Description
Span<T>	buffer	The span buffer to read data into.

Type Parameters

Name	Description
T	Type of value to read. Must be an unmanaged value type.

Remarks

This will read data from the binary stream into the specified span of type T.

important

The type referenced by T type parameter must have a StructLayoutAttribute with a Sequential or Explicit struct layout. Otherwise, .NET may rearrange the members and the data may not appear in the correct place.

Value types with marshalling attributes (MarshalAsAttribute) are not supported and will not be read correctly.

ReadRange<T>(T[], int, int?)

Function to read a range of generic values.

Declaration

public void ReadRange<T>(T[] value, int startIndex = 0, int? count = null) where T : unmanaged

Parameters

Type	Name	Description
T[]	value	Array of values to read.
int	startIndex	[Optional] Starting index in the array.
int?	count	[Optional] Number of array elements to copy.

Type Parameters

Name	Description
T	Type of value to read. Must be an unmanaged value type.

Remarks

This will read data from the binary stream into the specified array of values of type T. The values will be populated starting at the startIndex up to the count specified. If the count is not specified (i.e. it is null), then the entire array minus the startIndex will be used.

important

The type referenced by T type parameter must have a StructLayoutAttribute with a Sequential or Explicit struct layout. Otherwise, .NET may rearrange the members and the data may not appear in the correct place.

Value types with marshalling attributes (MarshalAsAttribute) are not supported and will not be read correctly.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the value parameter is null.
ArgumentOutOfRangeException	Thrown when the startIndex parameter is less than 0. -or- Thrown when the startIndex parameter is equal to or greater than the number of elements in the value parameter. -or- Thrown when the sum of startIndex and count is greater than the number of elements in the value parameter.
IOException	Thrown when the stream is write-only.

ReadValue<T>()

Function to read a generic value from the stream.

Declaration

public T ReadValue<T>() where T : unmanaged

Returns

Type	Description
T	The value in the stream.

Type Parameters

Name	Description
T	Type of value to read. Must be an unmanaged value type.

Remarks

This method will read the data from the binary stream into a value of type T, and return that value.

important

The type referenced by T type parameter must have a StructLayoutAttribute with a Sequential or Explicit struct layout. Otherwise, .NET may rearrange the members and the data may not appear in the correct place.

Value types with marshalling attributes (MarshalAsAttribute) are not supported and will not be read correctly.

ReadValue<T>(out T)

Function to read a generic value from the stream.

Declaration

public void ReadValue<T>(out T result) where T : unmanaged

Parameters

Type	Name	Description
T	result	The value from the stream.

Type Parameters

Name	Description
T	Type of value to read. Must be an unmanaged value type.

Remarks

This method will read the data from the binary stream into a value of type T, and return that value.

important

The type referenced by T type parameter must have a StructLayoutAttribute with a Sequential or Explicit struct layout. Otherwise, .NET may rearrange the members and the data may not appear in the correct place.

Value types with marshalling attributes (MarshalAsAttribute) are not supported and will not be read correctly.

Implements

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)