AeonSake.BinaryTools 1.6.0

Binary Tools

This library contains a set of tools for handling endian-specific binary data.

Installation

The library is available as NuGet package on nuget.org and this project's GitLab Package Registry.

Features

BinaryReader

The BinaryReader class offers means to read data from a stream with the given endianness.

using var reader = new BinaryReader(stream);

//change the endianness
reader.BigEndian = true;

//set default text encoding
reader.Encoding = Encoding.UTF16;

//skip a number of bytes
reader.Skip(10);

//jump to an absolute position
reader.JumpTo(20);

//align the current reader position
reader.Align(16);

//read data
var val1 = reader.ReadByteArray(10);
var val2 = reader.ReadUInt16();
var val3 = reader.ReadDouble();
var val4 = reader.ReadString(10);
var val5 = reader.ReadPascalString();
var val6 = reader.ReadTerminatedString();
var val7 = reader.ReadInt64At(100);
var val8 = reader.ReadStringAt(120, 10, Encoding.UTF8);
var val9 = reader.ReadInt32Array(16);
//...

//create a temporary scope
//the reader is reset to the initial position when the scope is disposed
using (reader.CreateScope())
{
    reader.ReadUInt16();
    reader.JumpTo(30);
}

BinaryWriter

The BinaryWriter class offers means to write data to a stream with the given endianness.

using var writer = new BinaryWriter(stream);

//change the endianness
writer.BigEndian = true;

//set default text encoding
writer.Encoding = Encoding.UTF16;

//automatically expand the stream when jumping to positions beyond the current stream size
writer.AutoExpand = true;

//skip a number of bytes
writer.Skip(10);

//jump to an absolute position, expand with given byte
writer.JumpTo(20, 0xCD);

//align the current writer position
writer.Align(16);

//append a number of bytes at the current position
writer.Pad(10, 0xAB);

//write data
writer.Write((byte) 1);
writer.Write((ulong) 1234);
writer.WriteAt(10, (double) 134.456);
writer.Write("example");
writer.WriteTerminatedString("example", Encoding.UTF8);
writer.WritePascalString("example");
writer.Write([1, 2, 3]);
//...

//create a temporary scope
//the writer is reset to the initial position when the scope is disposed
using (writer.CreateScope())
{
    writer.Write(123);
    writer.JumpTo(30);
}

StreamSpan

A flexible Span-like wrapper for Stream instances. Allows to define a relative window into a stream without creating a new stream. The StreamSpan class implements the Stream base class and can be used like a normal stream. Reading/writing beyond the defined boundary will throw an exception.

using AeonSake.BinaryTools.Streams;

//define a span with offset 10 and length 20
using var span = new StreamSpan(stream, 10, 20);

//position is relative to the defined offset
span.Position; //returns 0 (10 absolute to base stream)

//seek operations are done relative to the span
span.Seek(5, SeekOrigin.Begin); //returns 5 (15 absolute to base stream)

//reading will only return bytes up to the boundary
var buffer = new byte[10];
span.Position = 12;
var count = span.Read(buffer, 0, 10); //returns 8

//writing is only allowed within the boundary and if the span is writable
span.Write(buffer, 0, 10); //throws ArgumentOutOfRangeException

StreamSlice

A wrapper for Stream instances. Allows to define a relative offset into a stream without creating a new stream. The StreamSlice class implements the Stream base class and can be used like a normal stream. This class behaves similarly to StreamSpan, but without the upper boundary (length).

using AeonSake.BinaryTools.Streams;

//define a slice with offset 10
using var slice = new StreamSlice(stream, 10);

//position is relative to the defined offset
slice.Position; //returns 0 (10 absolute to base stream)

//seek operations are done relative to the slice
slice.Seek(5, SeekOrigin.Begin); //returns 5 (15 absolute to base stream)

//reading and writing works identically to the base stream
var buffer = new byte[10];
var count = slice.Read(buffer, 0, 10); //returns 10
slice.Write(buffer, 0, 10);

Buffer Reader/Writer

The library also has a number of wrapper classes for specific buffer readers/writers that allow specifying the endianness. They also implement the common IBufferReader and IBufferWriter interfaces to allow generic handling. All primitive data types are supported (including floating-point types for versions prior to .NET5). The buffers are always given as ReadOnlySpan<byte> for the readers and Span<byte> for the writers.

using AeonSake.BinaryTools.Buffers;

IBufferReader beReader = new BigEndianBufferReader();
IBufferReader leReader = new LittleEndianBufferReader();

byte[] buffer1 = [1, 2];
byte[] buffer2 = [1, 2, 3, 4, 5, 6, 7, 8];
var val1 = beReader.ReadUInt16(buffer1);
var val2 = leReader.ReadDouble(buffer2);

IBufferWriter beWriter = new BigEndianBufferWriter();
IBufferWriter leWriter = new LittleEndianBufferWriter();

var buffer3 = new byte[2];
var buffer4 = new byte[8];
beWriter.Write(buffer3, (ushort) 123);
leWriter.Write(buffer4, (double) 123.456);

BitHelper

A utility class for common bit operations.

//set the 5th bit in a value
BitHelper.Set(31, 5); //returns 63

//clear the 5th bit in a value
BitHelper.Clear(63, 5); //returns 31

//toggle the 5th bit in a value
BitHelper.Toggle(31, 5); //returns 63
BitHelper.Toggle(63, 5); //returns 31

//check if the 5th bit is set in a value
BitHelper.IsSet(31, 5); //return false

//count all set bits in a value
BitHelper.Count(31); //returns 5

AlignmentHelper

A small utility class for calculating alignment offsets.

//get the relative offset for the position 20 with the byte alignment of 16
var offset = AlignmentHelper.GetOffset(20, 16); //returns 12

HexConverter

A converter class that allows converting byte arrays to and from their hexadecimal string representation.

using AeonSake.BinaryTools.Converters;

var val1 = HexConverter.ToHexString([1, 2, 3]); //returns "010203"
var val2 = HexConverter.ToHexString([0, 255], true); //returns "0x00FF"
var val3 = HexConverter.FromHexString("0x1234"); //returns [18, 52]
HexConverter.TryFromHexString("invalid", out var val4); //returns false

StreamExtensions

Various extension methods for the Stream class.

using AeonSake.BinaryTools.Streams;

//read the stream to byte array (start to end)
var arr1 = stream.ToArray();
var arr2 = await stream.ToArrayAsync();

//read the stream to byte array (from current position)
var arr3 = stream.ReadToEnd();
var arr4 = await stream.ReadToEndAsync();

//checks the stream against a given byte pattern
var valid1 = stream.Match([1, 2, 3, 4]);
var valid2 = await stream.MatchAsync([1, 2, 3, 4]);

//checks if the stream contains data
var isEmpty = stream.IsEmpty();

//jump to start/end of the stream
stream.JumpToStart();
stream.JumpToEnd();

Building from Source

Building this project requires .NET 5.0 SDK or newer, or .NET Core 3.0 or newer. Refer to the full list of supported frameworks to see more.
Some packages are loaded from external sources (nuget.org) and are required for compilation. Make sure to run nuget restore (or Restore NuGet packages from inside Visual Studio) before building.

License

The project is licensed under MIT.