Salar.BinaryBuffers 4.0.1

BinaryBuffers

BinaryBuffers is a high-performance .NET library for reading and writing primitive values directly from binary buffers. It gives you BinaryReader/BinaryWriter-style APIs without requiring an intermediate Stream, which reduces allocations and improves throughput in buffer-heavy workloads.

Why BinaryBuffers?

• Use the recommended span-based reader and writer for direct byte[] access
• Work directly with byte[], Span<byte>, and ReadOnlySpan<byte> buffers
• Reuse existing buffers with ResetBuffer(...)
• Read from ReadOnlyMemory<byte> and ReadOnlySequence<byte>
• Use shared abstractions through IBufferReader and IBufferWriter
• Swap in stream-based compatibility types when you still need a Stream

Installation

dotnet add package Salar.BinaryBuffers

Quick start

When working directly with a byte[], Span<byte>, or ReadOnlySpan<byte>, prefer BinarySpanBufferWriter and BinarySpanBufferReader. They provide the recommended zero-allocation, lowest-overhead path.

Recommended span-based API

using Salar.BinaryBuffers;

var buffer = new byte[32];
var writer = new BinarySpanBufferWriter(buffer);

writer.Write(2022);
writer.Write(8.11);

var reader = new BinarySpanBufferReader(writer.ToReadOnlySpan());
var year = reader.ReadInt32();
var value = reader.ReadDouble();

BinarySpanBufferWriter and BinarySpanBufferReader are ref struct types, so they cannot be stored as class fields or used across async boundaries. In those cases, use BinaryBufferWriter and BinaryBufferReader; they are still very fast and can also be referenced through their shared interfaces.

Class-based API

using Salar.BinaryBuffers;

var buffer = new byte[32];

var writer = new BinaryBufferWriter(buffer);
writer.Write(2022);
writer.Write(8.11);

var bytesWritten = writer.WrittenLength;

var reader = new BinaryBufferReader(buffer, 0, bytesWritten);
var year = reader.ReadInt32();
var value = reader.ReadDouble();

Span-based reader and writer

BinarySpanBufferWriter and BinarySpanBufferReader are zero-allocation, high-performance types that operate directly on spans. As ref struct types, they can work with stack-allocated memory (stackalloc) without copying or allocating intermediate buffers.

BinarySpanBufferWriter

Use BinarySpanBufferWriter to write directly to a Span<byte>:

// Stack-allocated buffer — no heap allocation
Span<byte> buffer = stackalloc byte[1024];
var writer = new BinarySpanBufferWriter(buffer);

writer.Write(2022);
writer.Write(8.11);

// Get the written bytes as a ReadOnlySpan<byte>
ReadOnlySpan<byte> written = writer.ToReadOnlySpan();

BinarySpanBufferWriter implements IBufferWriter and works seamlessly with generic methods:

void Serialize<TBufferWriter>(TBufferWriter writer, int id) where TBufferWriter : IBufferWriter
{
    writer.Write(id);
}

Span<byte> buffer = stackalloc byte[1024];
var writer = new BinarySpanBufferWriter(buffer);
Serialize(writer, 42); // Works via generic constraint — no boxing

BinarySpanBufferReader

Use BinarySpanBufferReader to read directly from a ReadOnlySpan<byte>:

ReadOnlySpan<byte> buffer = GetBuffer();
var reader = new BinarySpanBufferReader(buffer);

var id = reader.ReadInt32();
var amount = reader.ReadDouble();

Because they are ref struct types, span-based readers and writers cannot be stored as class fields, used across async boundaries, or boxed to interfaces directly. Use the still-high-performance BinaryBufferWriter and BinaryBufferReader when those capabilities are needed.

Additional Goodies

Use StreamBufferWriter as a drop-in replacement for BinaryWriter when a Stream is required.

BinaryBufferWriter

Reuse BinaryBufferReader, BinaryBufferWriter, BinarySpanBufferReader, and BinarySpanBufferWriter with ResetBuffer(...) instead of creating new instances.

using Salar.BinaryBuffers;

var buffer = new byte[128];
var writer = new BinaryBufferWriter(buffer);

writer.Write(42);
writer.Write(123.45m);

writer.ResetBuffer();
writer.Write(7);

BinaryBufferReader

Use BinaryBufferReader to read primitive values from a byte[] or ArraySegment<byte>.

using Salar.BinaryBuffers;

var payload = new byte[16];
var writer = new BinaryBufferWriter(payload);
writer.Write(42);
writer.Write(2.5f);

var reader = new BinaryBufferReader(payload);
var id = reader.ReadInt32();
var amount = reader.ReadSingle();

Additional readers and compatibility types

• BinaryBufferMemoryReader reads from ReadOnlyMemory<byte>
• SequenceBufferReader reads from ReadOnlySequence<byte>
• StreamBufferWriter is a stream-based writer that implements the same writer abstraction
• StreamBufferReader is a stream-based reader that integrates with the same reader abstraction

This makes it easier to program against IBufferReader and IBufferWriter instead of tying your code to a single storage model.

When to use it

BinaryBuffers is a good fit when you:

• already own the underlying byte buffer and can use the recommended span-based APIs
• want to avoid wrapping buffers in MemoryStream
• need predictable, low-allocation binary serialization of primitive values
• want to reuse the same buffer across repeated operations

Compatibility

BinaryBuffers does not support cross-endian binary data exchange.

Benchmarks

Benchmarks in this repository show substantial improvements for common primitive reads and writes when compared to BinaryReader and BinaryWriter.

Read benchmarks

Lower is better.

Int

Decimal

Float

Write benchmarks

Lower is better.

Int

Decimal

Float

These benchmark results were recorded with the benchmark project in this repository using .NET 10.0 on:

AMD Ryzen 9 5900X, 1 CPU, 24 logical and 12 physical cores