Class GorgonBinaryWriter

An extended binary writer class.

Inheritance

object

BinaryWriter

GorgonBinaryWriter

Implements

IDisposable

Inherited Members

BinaryWriter.Null

BinaryWriter.OutStream

BinaryWriter.Close()

BinaryWriter.Dispose(bool)

BinaryWriter.Dispose()

BinaryWriter.Flush()

BinaryWriter.Seek(int, SeekOrigin)

BinaryWriter.Write(bool)

BinaryWriter.Write(byte)

BinaryWriter.Write(sbyte)

BinaryWriter.Write(byte[])

BinaryWriter.Write(byte[], int, int)

BinaryWriter.Write(char)

BinaryWriter.Write(char[])

BinaryWriter.Write(char[], int, int)

BinaryWriter.Write(double)

BinaryWriter.Write(decimal)

BinaryWriter.Write(short)

BinaryWriter.Write(ushort)

BinaryWriter.Write(int)

BinaryWriter.Write(uint)

BinaryWriter.Write(long)

BinaryWriter.Write(ulong)

BinaryWriter.Write(float)

BinaryWriter.Write(string)

BinaryWriter.Write7BitEncodedInt(int)

BinaryWriter.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 GorgonBinaryWriter : BinaryWriter, IDisposable

Remarks

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

Constructors

GorgonBinaryWriter(Stream, bool)

Initializes a new instance of the GorgonBinaryWriter class.

Declaration

public GorgonBinaryWriter(Stream output, bool keepStreamOpen = false)

Parameters

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

GorgonBinaryWriter(Stream, Encoding, bool)

Initializes a new instance of the GorgonBinaryWriter class.

Declaration

public GorgonBinaryWriter(Stream output, Encoding encoder, bool keepStreamOpen = false)

Parameters

Type	Name	Description
Stream	output	Output stream.
Encoding	encoder	Encoding for the binary writer.
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 out.

Declaration

public int BufferSize { get; set; }

Property Value

Type	Description
int

Remarks

This value is meant to help in buffering data to the data source if the source 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 set or return whether to keep the underlying stream open or not after the writer is closed.

Declaration

public bool KeepStreamOpen { get; }

Property Value

Type	Description
bool

Methods

Write(ref byte, int)

Function to write the bytes in a referenced buffer into the stream.

Declaration

public void Write(ref byte buffer, int size)

Parameters

Type	Name	Description
byte	buffer	The reference to the buffer to write to the stream.
int	size	Number of bytes to write.

Remarks

This method will write the number of bytes specified by the size parameter from the referenced byte 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.

Write(void*, int)

Function to write the bytes pointed at by the pointer into the stream.

Declaration

public void Write(void* pointer, int size)

Parameters

Type	Name	Description
void*	pointer	Pointer to the buffer containing the data.
int	size	Number of bytes to write.

Remarks

This method will write the number of bytes specified by the size parameter from the data 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.

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

Function to write a range of generic values.

Declaration

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

Parameters

Type	Name	Description
GorgonPtr<T>	value	Pointer to memory containing the values to write.
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 write. Must be an unmanaged value type.

Remarks

This will write data into the binary stream from the specified pointer to memory containing values of type T. The values will start at the startIndex in the array 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.

The amount of data written will be dependant upon the size of type T * (count-startIndex). Packing rules on type T will affect the size of the type.

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 read-only.

WriteRange<T>(Span<T>)

Function to write data from a span to a stream.

Declaration

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

Parameters

Type	Name	Description
Span<T>	buffer	The span buffer to write to the stream.

Type Parameters

Name	Description
T	The type of data in the span buffer. Must be an unmanaged value type.

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

Function to write a range of generic values.

Declaration

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

Parameters

Type	Name	Description
T[]	value	Array of values to write.
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 write. Must be an unmanaged value type.

Remarks

This will write data into the binary stream from the specified array of values of type T. The values will start at the startIndex in the array 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.

The amount of data written will be dependant upon the size of type T * (count-startIndex). Packing rules on type T will affect the size of the type.

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 read-only.

WriteValue<T>(T)

Function to write a generic value to the stream.

Declaration

public void WriteValue<T>(T value) where T : unmanaged

Parameters

Type	Name	Description
T	value	Value to write to the stream.

Type Parameters

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

Remarks

This method will write the data to the binary stream from the value of type T. The amount of data written will be dependant upon the size of T, and any packing rules applied.

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 read-only.

WriteValue<T>(ref T)

Function to write a generic value to the stream.

Declaration

public void WriteValue<T>(ref T value) where T : unmanaged

Parameters

Type	Name	Description
T	value	Value to write to the stream.

Type Parameters

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

Remarks

This method will write the data to the binary stream from the value of type T. The amount of data written will be dependant upon the size of T, and any packing rules applied.

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 read-only.

Implements

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)