Yort.Hexy 1.0.0

Yort.Hexy

An immutable .NET value type for hexadecimal byte sequences — a proper domain type for hex data instead of raw byte[] or string. Parse any common hex format, format with full control, compare with value equality, and use as dictionary keys without writing utility code.

Why Yort.Hexy?

The .NET BCL has Convert.ToHexString for one-off conversions, but if hex values are part of your domain — identifiers, protocol fields, device addresses, cryptographic hashes — you quickly run into friction:

When to Use This

Use Yort.Hexy when hex values are part of your domain model and you want a proper type instead of stringly-typed code. Common in RFID/NFC, network protocols, cryptography, IoT, smart cards, and binary format parsing.

Just use Convert.ToHexString if you need a one-off byte-array-to-string conversion and don't need equality, comparison, or rich formatting.

Features

• Immutable Hex value type — readonly struct backed by byte[], safe to pass around and use as dictionary keys
• Permissive parsing — handles "DEADBEEF", "0xDEADBEEF", "#FF00AA", "DE:AD:BE:EF", "DE-AD-BE-EF", "DE AD BE EF", mixed case, whitespace
• Rich formatting — 10+ built-in formats, custom separator/prefix/casing combos, configurable defaults
• Fast comparison & hashing — SIMD-accelerated on .NET 9+, suitable for high-throughput dictionary lookups
• Zero-copy access — AsSpan(), AsMemory(), implicit ReadOnlyMemory<byte> conversion
• Full .NET integration — IEquatable<T>, IComparable<T>, IFormattable, IConvertible, ISpanFormattable (.NET 9+), IParsable<T> (.NET 9+)
• JSON ready — built-in System.Text.Json converter with permissive deserialization
• Multi-target — .NET Standard 2.0, .NET 9.0, .NET 10.0 with platform-specific optimizations

Quick Start

using Yort.Hexy;

// Parse from any common hex format
Hex value = Hex.Parse("0xDEADBEEF");
Hex fromColons = Hex.Parse("DE:AD:BE:EF");
Hex fromBytes = new Hex(new byte[] { 0xDE, 0xAD, 0xBE, 0xEF });

// All three are equal
Debug.Assert(value == fromColons);
Debug.Assert(value == fromBytes);

// Format in different styles
Console.WriteLine(value.ToString(HexFormat.Uppercase));       // "DEADBEEF"
Console.WriteLine(value.ToString(HexFormat.LowercaseColons)); // "de:ad:be:ef"
Console.WriteLine(value.ToString(HexFormat.LowercasePrefixed)); // "0xdeadbeef"

// Use as dictionary key
var lookup = new Dictionary<Hex, string>
{
    [Hex.Parse("CAFEBABE")] = "Java class file"
};

// Zero-copy byte access
ReadOnlySpan<byte> span = value.AsSpan();
ReadOnlyMemory<byte> memory = value; // implicit conversion

// Generate random hex values
Hex nonce = Hex.CreateRandom(16);

// Safe parsing
if (Hex.TryParse(userInput, out Hex parsed))
    Console.WriteLine(parsed);

Formatting

Built-in Formats

Custom Formats

var dotted = new HexFormat(HexLetterCase.Lower, separator: ".", prefix: "0x");
Console.WriteLine(value.ToString(dotted)); // "0xde.ad.be.ef"

Application Defaults

// Set once at startup
HexDefaults.Format = HexFormat.UppercaseColons;
HexDefaults.Lock(); // Prevent further changes

// All ToString() calls now use the configured default
Console.WriteLine(value.ToString()); // "DE:AD:BE:EF"

Operations

// Concatenation
Hex combined = a + b;
Hex appended = a.Append(b);
Hex multi = Hex.Concat(a, b, c, d);

// Slicing
Hex slice = value.Slice(1, 2);

// Pattern matching
bool starts = value.StartsWith(Hex.Parse("DEAD"));
bool ends = value.EndsWith(Hex.Parse("BEEF"));
bool has = value.Contains(Hex.Parse("ADBE"));

// Reverse (endianness flip)
Hex reversed = value.Reverse();

// Efficient building
var builder = new HexBuilder();
builder.Append(chunk1);
builder.Append(chunk2);
Hex result = builder.ToHex(); // Single allocation

Conversions

// Explicit from byte[]
Hex hex = (Hex)new byte[] { 0xCA, 0xFE };

// Explicit copy to byte[]
byte[] bytes = hex.ToByteArray();

// Zero-allocation write to buffer
Span<byte> buffer = stackalloc byte[16];
hex.TryWriteBytes(buffer);

// Guid interop
Hex fromGuid = Hex.FromGuid(myGuid);
Guid backToGuid = fromGuid.ToGuid();

// String casts
Hex parsed = (Hex)"0xDEADBEEF";
string formatted = (string)hex;

Stream Extensions

// Synchronous
stream.WriteHex(myHex);
Hex read = stream.ReadHex(byteCount: 16);

// Async
await stream.WriteHexAsync(myHex, cancellationToken);
Hex readAsync = await stream.ReadHexAsync(16, cancellationToken);

// BinaryReader/Writer
writer.Write(myHex);
Hex fromReader = reader.ReadHex(16);

JSON Serialization

Hex works automatically with System.Text.Json:

var obj = new MyModel { Id = Hex.Parse("DEADBEEF") };
string json = JsonSerializer.Serialize(obj);   // {"Id":"deadbeef"}
var back = JsonSerializer.Deserialize<MyModel>(json);

Deserialization is permissive — it accepts all the same formats as Hex.Parse.

Performance

Representative benchmarks on .NET 10 (ShortRun, Intel i7-11850H):

Comparison, pattern matching, and hashing are zero-allocation. Run benchmarks yourself for your hardware:

cd benchmarks/Yort.Hexy.Benchmarks
dotnet run -c Release --framework net10.0 -- --filter "*"

Target Frameworks

Platform-specific optimizations are selected automatically at compile time.

Installation

dotnet add package Yort.Hexy

Building from Source

git clone https://github.com/Yortw/Yort.Hexy.git
cd Yort.Hexy
dotnet build
dotnet test

Running Benchmarks

cd benchmarks/Yort.Hexy.Benchmarks
dotnet run -c Release --framework net10.0 -- --filter "*"

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.