IBinaryEncoding Interface

Definition

Namespace

Bodu.Text.Encoding

Assembly

Bodu.Text.Encoding.dll

Package

Bodu.Text.Encoding 1.0.0

Source

IBinaryEncoding.cs

Represents a binary-to-text encoding scheme (Base16, Base32, Base64, Base58, Base85, …) with the variant pre-bound, so that callers can pick or inject an encoding at runtime instead of dispatching through static classes.

public interface IBinaryEncoding

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Pick an encoding at runtime from configuration.
string             configured = appConfig["encoding"];                     // e.g. "base64-urlsafe"
IBinaryEncoding    encoding   = BinaryEncodings.Get(configured);

// Use the same call shape regardless of which variant was chosen.
string encoded = encoding.Encode(payload);
byte[] decoded = encoding.Decode(encoded);

Console.WriteLine($"{encoding.Name}: {encoding.Description}");

Remarks

Instances are obtained from BinaryEncodings - each property there returns a singleton implementation bound to a specific variant. The pattern mirrors Encoding, but for radix encoding rather than character-set transcoding.

Implementations are stateless and thread-safe. The static convenience methods on Base16, Base32, Base64, Base58, and Base85 remain the recommended entry points when the encoding is known at compile time; the interface is intended for code that must choose between encodings at runtime (configuration-driven serializers, plugin pipelines, generic utilities).

Properties

Description

Gets a human-readable description of the encoding and its origin (specification clause, RFC, etc.).

string Description { get; }

Property Value

string

Name

Gets a short stable name identifying the encoding and variant - for example, "base16-lower", "base32", "base64-urlsafe". Suitable as a key in configuration and for diagnostic output.

string Name { get; }

Property Value

string

Methods

Decode(ReadOnlySpan<char>)

Decodes chars into a newly allocated byte array using the variant's strict parsing rules.

byte[] Decode(ReadOnlySpan<char> chars)

Parameters

chars ReadOnlySpan<char>

The encoded character span.

Returns

byte[]

The decoded bytes.

Encode(ReadOnlySpan<byte>)

Encodes bytes into a newly allocated string using the variant's canonical formatting.

string Encode(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

The encoded string.

GetMaxDecodedLength(int)

Returns an upper bound on the number of bytes that decoding charCount characters could produce.

int GetMaxDecodedLength(int charCount)

Parameters

charCount int

The input character count. Must be non-negative.

Returns

int

The maximum decoded byte count.

GetMaxEncodedLength(int)

Returns an upper bound on the number of characters required to encode byteCount bytes.

int GetMaxEncodedLength(int byteCount)

Parameters

byteCount int

The input byte count. Must be non-negative.

Returns

int

The maximum encoded character count.

IsValid(ReadOnlySpan<char>)

Indicates whether source is a valid encoded input under this encoding's variant rules.

bool IsValid(ReadOnlySpan<char> source)

Parameters

source ReadOnlySpan<char>

The character span to validate.

Returns

bool

true when source would decode without error; otherwise false.

TryDecode(ReadOnlySpan<char>, Span<byte>, out int)

Attempts to decode source into destination without allocation.

bool TryDecode(ReadOnlySpan<char> source, Span<byte> destination, out int bytesWritten)

Parameters

source ReadOnlySpan<char>

The encoded character span.

destination Span<byte>

The destination byte span.

bytesWritten int

When this method returns, contains the number of bytes written.

Returns

bool

true when the destination is large enough and the input is valid; otherwise false.

Remarks

On failure bytesWritten is set to zero and the contents of destination are unspecified - the BCL convention shared with TryFromBase64Chars(ReadOnlySpan<char>, Span<byte>, out int). Callers must not rely on any partial bytes that may have been written before the failure was detected.

TryEncode(ReadOnlySpan<byte>, Span<char>, out int)

Attempts to encode source into destination without allocation.

bool TryEncode(ReadOnlySpan<byte> source, Span<char> destination, out int charsWritten)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The destination span.

charsWritten int

When this method returns, contains the number of characters written.

Returns

bool

true when the destination is large enough; otherwise false.

Applies to

Product	Versions
.NET	8, 10