Home

Awesome

<div align="center">

Darp.BinaryObjects

NuGet Downloads

Dotnet Version Language Version

Tests License

A source generator to generate TryRead/Write Little/BigEndian methods for struct/class definitions.

</div>

[!IMPORTANT]
This package is under heavy development. Anything is subject to change.

You should use the source generation when you want:

If these requirements do not meet your expectations, check out those other wonderful projects

Supported properties

Here is a list of the property types currently supported by the library:

For all of these types, it should be possible to define as array types:

To control these types there are attributes

Unplanned:

What is serialized?

There are warnings if:

How it's supposed to work

Let's pretend we have a series of bytes:

01020003040506

A: 01
B: 0200
Data: 03040506

Normally, you would have to write serialization methods for yourself. By adding the BinaryObjectAttribute, this is done automatically by the source generator.

This:

public readonly record struct SomeTestStruct(byte A, ushort B, ReadOnlyMemory<int> Data);

bool TryReadSomeTestStruct(ReadOnlySpan<byte> source, out SomeTestStruct value)
{
    if (source.Length < 3)
    {
        value = default;
        return false;
    }
    var a = source[0];
    var b = BinaryPrimitives.ReadUInt16LittleEndian(source[1..]);
    var dataArray = new int[(source.Length - 3) / sizeof(int)];
    ReadOnlySpan<int> reinterpretedData = MemoryMarshal.Cast<byte, int>(source[2..]);
    if (BitConverter.IsLittleEndian)
    {
        reinterpretedData.CopyTo(dataArray);
    }
    else
    {
        BinaryPrimitives.ReverseEndianness(reinterpretedData, dataArray);
    }
    value = new SomeTestStruct(a, b, dataArray);
    return true;
}

TryReadSomeTestStruct(buffer, out SomeTestStruct value);

Becomes this:

[BinaryObject]
public readonly partial record struct SomeTestStruct(byte A, ushort B, ReadOnlyMemory<int> Data);

SomeTestStruct.TryReadLittleEndian(buffer, out SomeTestStruct value);

Usage

// Define your object
[BinaryObject]
partial record struct YourStruct(ushort A, byte B);

// Read the struct from the buffer using either little or big endian format
var buffer = Convert.FromHexString("AABBCC");
var success = YourStruct.TryReadLittleEndian(source: buffer, out var value);
var success2 = YourStruct.TryReadBigEndian(source: buffer, out var value2, out int bytesRead);

// Get the actual size of the struct
var size = value.GetByteCount();

// Write the values back to a buffer
var writeBuffer = new byte[size];
var success3 = value.TryWriteLittleEndian(destination: writeBuffer);
var success4 = value2.TryWriteLittleEndian(destination: writeBuffer, out int bytesWritten);

The code generated by the struct will attempt to maximize readability by still maintaining performance and as little allocations as possible.

<details> <summary>Generated code</summary> 
// <auto-generated/>
#nullable enable

using BinaryHelpers = global::Darp.BinaryObjects.BinaryHelpers;
using NotNullWhenAttribute = global::System.Diagnostics.CodeAnalysis.NotNullWhenAttribute;

namespace Your.Namespace;

/// <remarks> <list type="table">
/// <item> <term><b>Field</b></term> <description><b>Byte Length</b></description> </item>
/// <item> <term><see cref="A"/></term> <description>2</description> </item>
/// <item> <term><see cref="B"/></term> <description>1</description> </item>
/// <item> <term> --- </term> <description>3</description> </item>
/// </list> </remarks>
public partial record struct YourStruct : global::Darp.BinaryObjects.IBinaryWritable, global::Darp.BinaryObjects.IBinaryReadable<YourStruct>
{
    /// <inheritdoc />
    [global::System.Runtime.CompilerServices.MethodImpl(global::System.Runtime.CompilerServices.MethodImplOptions.AggressiveInlining)]
    public int GetByteCount() => 3;

    /// <inheritdoc />
    public bool TryWriteLittleEndian(global::System.Span<byte> destination) => TryWriteLittleEndian(destination, out _);
    /// <inheritdoc />
    public bool TryWriteLittleEndian(global::System.Span<byte> destination, out int bytesWritten)
    {
        bytesWritten = 0;

        if (destination.Length < 3)
            return false;
        BinaryHelpers.WriteUInt16LittleEndian(destination[0..], this.A);
        BinaryHelpers.WriteUInt8(destination[2..], this.B);
        bytesWritten += 3;

        return true;
    }
    /// <inheritdoc />
    public bool TryWriteBigEndian(global::System.Span<byte> destination) => TryWriteBigEndian(destination, out _);
    /// <inheritdoc />
    public bool TryWriteBigEndian(global::System.Span<byte> destination, out int bytesWritten)
    {
        bytesWritten = 0;

        if (destination.Length < 3)
            return false;
        BinaryHelpers.WriteUInt16BigEndian(destination[0..], this.A);
        BinaryHelpers.WriteUInt8(destination[2..], this.B);
        bytesWritten += 3;

        return true;
    }

    /// <inheritdoc />
    public static bool TryReadLittleEndian(global::System.ReadOnlySpan<byte> source, out YourStruct value) => TryReadLittleEndian(source, out value, out _);
    /// <inheritdoc />
    public static bool TryReadLittleEndian(global::System.ReadOnlySpan<byte> source, out YourStruct value, out int bytesRead)
    {
        bytesRead = 0;
        value = default;

        if (source.Length < 3)
            return false;
        var ___readA = BinaryHelpers.ReadUInt16LittleEndian(source[0..]);
        var ___readB = BinaryHelpers.ReadUInt8(source[2..]);
        bytesRead += 3;

        value = new YourStruct(___readA, ___readB);
        return true;
    }
    /// <inheritdoc />
    public static bool TryReadBigEndian(global::System.ReadOnlySpan<byte> source, out YourStruct value) => TryReadBigEndian(source, out value, out _);
    /// <inheritdoc />
    public static bool TryReadBigEndian(global::System.ReadOnlySpan<byte> source, out YourStruct value, out int bytesRead)
    {
        bytesRead = 0;
        value = default;

        if (source.Length < 3)
            return false;
        var ___readA = BinaryHelpers.ReadUInt16BigEndian(source[0..]);
        var ___readB = BinaryHelpers.ReadUInt8(source[2..]);
        bytesRead += 3;

        value = new YourStruct(___readA, ___readB);
        return true;
    }
}
</details>

Development

After cloning the repository, you will find the following project structure:

Code formatting

This repository uses CSharpier (inspired by prettier) for code formatting. CSharpier should be installed automatically when building the solution as a local dotnet tool.

To run it, execute

dotnet csharpier .

If you want to format you code on save, check out available Editor integration for your IDE.

Testing

Snapshot tests are done using Verify. If you want to optimize running these tests in your local IDE, you might adjust some settings. Please, check your local configuration in the VerifyDocs