BinaryEncodingExtensions Class

Definition

Namespace

Bodu.Text.Encoding

Assembly

Bodu.Text.Encoding.dll

Package

Bodu.Text.Encoding 1.0.0

Source

BinaryEncodingExtensions.cs

Provides fluent extension methods on byte arrays, ReadOnlySpan<T> of byte and char, and string that route through the canonical encoding implementations.

public static class BinaryEncodingExtensions

Inheritance

object

BinaryEncodingExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

byte[] data = "hello"u8.ToArray();

// Direct shortcuts - discoverable from IntelliSense via the byte[] receiver.
string hex     = data.ToBase16String();                  // "68656c6c6f"
string base32  = data.ToBase32String();                  // "NBSWY3DP"
string base64  = data.ToBase64String();                  // "aGVsbG8="
string base58  = data.ToBase58String();                  // "Cn8eVZg"

// Round-trip via the matching FromBase*String extension.
byte[] roundtrip = base64.FromBase64String();

// Generic dispatch via IBinaryEncoding for runtime-selected encodings.
IBinaryEncoding chosen = BinaryEncodings.Get(appConfig["encoding"] ?? "base64");
string encoded = data.Encode(chosen);
byte[] decoded = encoded.Decode(chosen);

Remarks

These extensions exist purely for ergonomic discoverability - typing bytes. in an editor brings up ToBase16String, ToBase64String, ToBase58String, and so on. They delegate without overhead to the static Base16, Base32, Base64, Base58, and Base85 classes.

The generic Encode(byte[], IBinaryEncoding) and Decode(string, IBinaryEncoding) overloads route through IBinaryEncoding so that runtime-selected encodings work with the same extension surface.

Methods

Decode(string, IBinaryEncoding)

Decodes encoded using encoding.

public static byte[] Decode(this string encoded, IBinaryEncoding encoding)

Parameters

encoded string

The encoded string.

encoding IBinaryEncoding

The encoding to use.

Returns

byte[]

The decoded bytes.

Exceptions

ArgumentNullException

Thrown when either argument is null.

FormatException

Thrown when the input is not valid for the chosen encoding.

Encode(byte[], IBinaryEncoding)

Encodes bytes using encoding.

public static string Encode(this byte[] bytes, IBinaryEncoding encoding)

Parameters

bytes byte[]

The bytes to encode.

encoding IBinaryEncoding

The encoding to use.

Returns

string

The encoded string.

Exceptions

ArgumentNullException

Thrown when either argument is null.

FromBase16String(string)

Decodes a Base16 hexadecimal string into a byte array using strict parsing.

public static byte[] FromBase16String(this string hex)

Parameters

hex string

The hex input.

Returns

byte[]

The decoded bytes.

Exceptions

ArgumentNullException

Thrown when hex is null.

FormatException

Thrown when the input is not valid hexadecimal.

FromBase32String(string)

Decodes a Standard RFC 4648 Base32 string into a byte array.

public static byte[] FromBase32String(this string base32)

Parameters

base32 string

The Base32 input.

Returns

byte[]

The decoded bytes.

Exceptions

ArgumentNullException

Thrown when base32 is null.

FormatException

Thrown when the input is not valid Base32.

FromBase58String(string)

Decodes a Bitcoin/Flickr Base58 string into a byte array.

public static byte[] FromBase58String(this string base58)

Parameters

base58 string

The Base58 input.

Returns

byte[]

The decoded bytes.

Exceptions

ArgumentNullException

Thrown when base58 is null.

FormatException

Thrown when the input is not valid Bitcoin/Flickr Base58.

FromBase64String(string)

Decodes a Standard RFC 4648 Base64 string into a byte array.

public static byte[] FromBase64String(this string base64)

Parameters

base64 string

The Base64 input.

Returns

byte[]

The decoded bytes.

Exceptions

ArgumentNullException

Thrown when base64 is null.

FormatException

Thrown when the input is not valid Base64.

FromBase85String(string)

Decodes an Adobe Ascii85 string into a byte array.

public static byte[] FromBase85String(this string ascii85)

Parameters

ascii85 string

The Ascii85 input.

Returns

byte[]

The decoded bytes.

Exceptions

ArgumentNullException

Thrown when ascii85 is null.

FormatException

Thrown when the input is not valid Ascii85.

GetBase64EncodedLength(ReadOnlySpan<byte>)

Returns the exact number of standard RFC 4648 Base64 characters required to encode bytes, including any trailing = padding.

public static int GetBase64EncodedLength(this ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The byte span whose encoded length is computed.

Returns

int

The encoded length in characters.

ToBase16String(byte[])

Encodes bytes to lower-case hexadecimal (the default Bodu Base16 form).

public static string ToBase16String(this byte[] bytes)

Parameters

bytes byte[]

The bytes to encode.

Returns

string

The lower-case hex string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ToBase16String(ReadOnlySpan<byte>)

Encodes bytes to lower-case hexadecimal.

public static string ToBase16String(this ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

The lower-case hex string.

ToBase32String(byte[])

Encodes bytes using the Standard RFC 4648 Base32 alphabet.

public static string ToBase32String(this byte[] bytes)

Parameters

bytes byte[]

The bytes to encode.

Returns

string

The Base32 string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ToBase32String(ReadOnlySpan<byte>)

Encodes bytes using the Standard RFC 4648 Base32 alphabet.

public static string ToBase32String(this ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

The Base32 string.

ToBase58String(byte[])

Encodes bytes using the Bitcoin/Flickr Base58 alphabet.

public static string ToBase58String(this byte[] bytes)

Parameters

bytes byte[]

The bytes to encode.

Returns

string

The Base58 string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ToBase58String(ReadOnlySpan<byte>)

Encodes bytes using the Bitcoin/Flickr Base58 alphabet.

public static string ToBase58String(this ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

The Base58 string.

ToBase64String(byte[])

Encodes bytes using the Standard RFC 4648 Base64 alphabet.

public static string ToBase64String(this byte[] bytes)

Parameters

bytes byte[]

The bytes to encode.

Returns

string

The Base64 string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ToBase64String(ReadOnlySpan<byte>)

Encodes bytes using the Standard RFC 4648 Base64 alphabet.

public static string ToBase64String(this ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

The Base64 string.

ToBase64UrlString(ReadOnlySpan<byte>)

Encodes bytes using the URL- and filename-safe Base64 alphabet (RFC 4648 §5), conventionally omitting trailing = padding (the JWT and OAuth convention).

public static string ToBase64UrlString(this ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

The URL-safe Base64 string.

ToBase85String(byte[])

Encodes bytes using Adobe Ascii85.

public static string ToBase85String(this byte[] bytes)

Parameters

bytes byte[]

The bytes to encode.

Returns

string

The Ascii85 string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ToBase85String(ReadOnlySpan<byte>)

Encodes bytes using Adobe Ascii85.

public static string ToBase85String(this ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

The Ascii85 string.

TryDecodeBase64FromUtf8(ReadOnlySpan<byte>, Span<byte>, out int)

Decodes a UTF-8 (ASCII) encoded standard RFC 4648 Base64 byte sequence into destination without throwing when the destination is too small.

public static bool TryDecodeBase64FromUtf8(this ReadOnlySpan<byte> utf8, Span<byte> destination, out int bytesWritten)

Parameters

utf8 ReadOnlySpan<byte>

The UTF-8 Base64 source bytes.

destination Span<byte>

The destination buffer that receives the decoded bytes.

bytesWritten int

When this method returns true, contains the number of decoded bytes written; otherwise zero.

Returns

bool

true when decoding completed successfully; false when destination is too small or when utf8 contains invalid input.

TryDecodeBase64UrlFromUtf8(ReadOnlySpan<byte>, Span<byte>, out int)

Decodes a UTF-8 (ASCII) encoded URL-safe Base64 byte sequence (RFC 4648 §5) into destination without throwing when the destination is too small.

public static bool TryDecodeBase64UrlFromUtf8(this ReadOnlySpan<byte> utf8, Span<byte> destination, out int bytesWritten)

Parameters

utf8 ReadOnlySpan<byte>

The UTF-8 URL-safe Base64 source bytes.

destination Span<byte>

The destination buffer that receives the decoded bytes.

bytesWritten int

When this method returns true, contains the number of decoded bytes written; otherwise zero.

Returns

bool

true when decoding completed successfully; false when destination is too small or when utf8 contains invalid input.

Remarks

Accepts inputs both with and without trailing = padding to match the JWT and OAuth conventions where padding is typically omitted.

TryEncodeBase64ToUtf8(ReadOnlySpan<byte>, Span<byte>, out int)

Encodes bytes into destination as standard RFC 4648 Base64 in UTF-8 (ASCII) encoded form without throwing when the destination is too small.

public static bool TryEncodeBase64ToUtf8(this ReadOnlySpan<byte> bytes, Span<byte> destination, out int bytesWritten)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<byte>

The destination buffer that receives the UTF-8 Base64 bytes.

bytesWritten int

When this method returns true, contains the number of UTF-8 Base64 bytes written; otherwise zero.

Returns

bool

true when the destination was large enough; false otherwise.

Remarks

The output is byte-identical to ToBase64String(ReadOnlySpan<byte>) after passing the resulting bytes through ASCII.GetString. Use this overload to avoid the intermediate string allocation when the consumer accepts UTF-8 bytes directly (network writers, file streams, log sinks).

TryEncodeBase64UrlToUtf8(ReadOnlySpan<byte>, Span<byte>, out int)

Encodes bytes into destination as URL-safe Base64 (RFC 4648 §5) in UTF-8 (ASCII) encoded form without throwing when the destination is too small.

public static bool TryEncodeBase64UrlToUtf8(this ReadOnlySpan<byte> bytes, Span<byte> destination, out int bytesWritten)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<byte>

The destination buffer that receives the UTF-8 URL-safe Base64 bytes.

bytesWritten int

When this method returns true, contains the number of UTF-8 bytes written; otherwise zero.

Returns

bool

true when the destination was large enough; false otherwise.

Applies to

Product	Versions
.NET	8, 10