Table of Contents

Using Base16 (hexadecimal)

Base16 is the simplest of the encoding family - every input byte maps to exactly two hex characters, so 100 % payload expansion. It is the canonical form for hash digests, low-level binary inspection, and any time the data needs to be human-readable at the byte boundary.

input bytes  : DE AD BE EF                 (4 bytes)
encoded text : deadbeef                    (8 chars, lower case default)
              "DEADBEEF"                    (UpperCase)
              "0xDEADBEEF"                  (UpperCase | IncludePrefix)
              "DE AD BE EF"                 (UpperCase | InsertSpacing)
              "0xDE AD BE EF"               (UpperCase | IncludePrefix | InsertSpacing)

Quick reference

using Bodu.Text.Encoding;

byte[] data = { 0xDE, 0xAD, 0xBE, 0xEF };

// Encode
string lower = Base16.Encode(data);                                  // "deadbeef"
string upper = Base16.Encode(data, BaseFormattingOptions.UpperCase); // "DEADBEEF"

// Or select the case with the variant overload, matching the uniform
// (bytes, variant, options) shape used by Base32/58/64/85:
string up2  = Base16.Encode(data, Base16Variant.Upper);              // "DEADBEEF"

// Decode (strict - no decorations, even length, alphabet-only)
byte[] back  = Base16.Decode("deadbeef");
byte[] mixed = Base16.Decode("DeAdBeEf");                            // case-insensitive

// Decode (lenient - 0x prefix, whitespace)
byte[] dump = Base16.Decode(
    "0xDE AD BE EF",
    BaseFormatStyles.AllowPrefix | BaseFormatStyles.IgnoreWhitespace);

Formatting decorations

BaseFormattingOptions is a flag enum - combine flags with |:

Flag Effect
None Default: lower case, continuous, no decoration
UpperCase Output upper-case digits
IncludePrefix Prepend 0x
InsertSpacing Single space between byte pairs (no trailing space)
InsertLineBreaks \r\n once a line reaches 64 characters, counting the 0x prefix and any spaces

Decoration examples

byte[] hash = SHA256.HashData("hello"u8);

Base16.Encode(hash);
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

Base16.Encode(hash, BaseFormattingOptions.UpperCase | BaseFormattingOptions.InsertSpacing);
// "2C F2 4D BA 5F B0 A3 0E 26 E8 3B 2A C5 B9 E2 9E 1B 16 1E 5C 1F A7 42 5E 73 04 33 62 93 8B 98 24"

Base16.Encode(hash, BaseFormattingOptions.UpperCase | BaseFormattingOptions.IncludePrefix | BaseFormattingOptions.InsertLineBreaks);
// "0x2CF24DBA5FB0A30E26E83B2AC5B9E29E1B161E5C1FA7425E73043362938B98\r\n24"

InsertLineBreaks breaks at 64 chars to match the PEM / hex-dump convention; InsertSpacing adds one space between every encoded byte. The 0x prefix and the spaces count toward the 64, so the prefixed digest above breaks two digits early, and with InsertSpacing each full line ends in the space that precedes its \r\n.

Lenient parsing

The decoder is strict by default - alphabet only, even length, no decorations. The BaseFormatStyles flags relax specific rules:

Flag Effect
None Strict mode - exact even-length hex digits, nothing else
AllowPrefix Tolerate a leading 0x / 0X
IgnoreWhitespace Strip ASCII space, tab, CR, LF anywhere in the input
AllowMissingPadding No-op - Base16 has no padding character
RequireCanonicalEncoding No-op - every byte maps to exactly two characters, so there are no unused terminal bits to constrain
// All three of these recover the same bytes when the matching flags are set:
Base16.Decode("0xDEADBEEF",      BaseFormatStyles.AllowPrefix);
Base16.Decode("DE AD BE EF",     BaseFormatStyles.IgnoreWhitespace);
Base16.Decode("0xDE AD BE EF",   BaseFormatStyles.AllowPrefix | BaseFormatStyles.IgnoreWhitespace);

Non-ASCII whitespace (no-break space, em space) is not stripped - IgnoreWhitespace is deliberately strict about which characters count as whitespace.

BCL-style aliases

If you prefer the System.Convert naming convention:

Base16.ToHexString(data);        // "DEADBEEF" (upper case, matches Convert.ToHexString)
Base16.ToHexStringLower(data);   // "deadbeef" (matches Convert.ToHexStringLower from .NET 9+)
Base16.FromHexString("DEADBEEF");// byte[] { 0xDE, 0xAD, 0xBE, 0xEF }

The fluent extension methods are also available:

data.ToBase16String();           // lower case (default Bodu form)
"DEADBEEF".FromBase16String();   // byte[] { 0xDE, 0xAD, 0xBE, 0xEF }

Span and UTF-8 paths

When you have a destination buffer and want to avoid the string allocation:

Span<char> buffer = stackalloc char[Base16.GetEncodedLength(data.Length)];
int written = Base16.Encode(data, buffer);
// or non-throwing:
if (Base16.TryEncode(data, buffer, out int charsWritten)) { … }

For UTF-8 byte buffers (network / file pipelines):

byte[] utf8 = Base16.EncodeToUtf8(data);                 // ASCII bytes - bit-identical to chars
Base16.TryEncodeToUtf8(data, utf8Buffer, out int len);

// Streaming decode using OperationStatus
var status = Base16.DecodeFromUtf8(
    utf8Source,
    byteDestination,
    out int bytesConsumed,
    out int bytesWritten,
    BaseFormatStyles.None,
    isFinalBlock: false);

Base16.DecodeFromUtf8 with isFinalBlock: false returns OperationStatus.NeedMoreData when the chunk ends on an odd nibble - the partial pair is left unconsumed for the next call.

Tip

The TryToHexString / TryToHexStringLower overloads come in both a Span<char> and a Span<byte> (UTF-8) destination form, so the BCL-style alias surface covers the same zero-allocation paths as TryEncode / TryEncodeToUtf8.

Encoding a GUID

Base16 encodes a Guid directly - handy for a stable, lower-case hex identifier without round-tripping through Guid.ToString("N"):

Guid id = Guid.NewGuid();

string hex   = Base16.Encode(id);                                 // 32 lower-case hex chars, no dashes
string upper = Base16.Encode(id, BaseFormattingOptions.UpperCase);

Guid back    = Base16.DecodeGuid(hex);                            // FormatException unless it decodes to 16 bytes
bool ok      = Base16.TryDecodeGuid(hex, out Guid parsed);        // non-throwing

The bytes are the GUID's native mixed-endian layout (matching Guid.TryWriteBytes), so DecodeGuid(Encode(id)) reconstructs id exactly. This differs from Guid.ToString("N"), which renders the first three fields in big-endian text order - the two forms are not interchangeable byte-for-byte, so decode hex produced by Encode with DecodeGuid, not by re-parsing a ToString("N") result.

Validation and sizing helpers

Base16.IsValid("deadbeef");        // true
Base16.IsValid("dead beef");       // false (whitespace under strict mode)
Base16.IsValid("0xdead", BaseFormatStyles.AllowPrefix); // true - "dead" is four digits once the prefix is skipped
Base16.IsValid("0xdea", BaseFormatStyles.AllowPrefix);  // false - odd digit count after the prefix
Base16.IsHexDigit('A');            // true
Base16.IsHexDigit('g');            // false

Base16.GetEncodedLength(32);                                    // 64 (bytes * 2)
Base16.GetEncodedLength(32, BaseFormattingOptions.InsertSpacing); // 95 (32*3-1)
Base16.GetMaxDecodedLength(64);                                 // 32 (chars / 2)
Base16.GetDecodedLength("deadbeef");                            // 4 (exact)

Common patterns

Diagnostic hex dump

string Dump(ReadOnlySpan<byte> bytes) =>
    Base16.Encode(bytes,
        BaseFormattingOptions.UpperCase
            | BaseFormattingOptions.InsertSpacing
            | BaseFormattingOptions.InsertLineBreaks);

Hash-digest formatter

string FormatDigest(byte[] hash) => Base16.ToHexStringLower(hash);

CLI / env-var input parser

byte[] ParseHexInput(string input) =>
    Base16.Decode(input,
        BaseFormatStyles.AllowPrefix | BaseFormatStyles.IgnoreWhitespace);

Where to go next