Base32 Class

Definition

Namespace

Bodu.Text.Encoding

Assembly

Bodu.Text.Encoding.dll

Package

Bodu.Text.Encoding 1.0.0

Source

Base32.BclAliases.cs

Provides Base32 encoding and decoding of binary data across multiple variants (RFC 4648 standard and hex-extended, Crockford, z-base-32), with optional padding control and whitespace tolerance during parsing.

public static class Base32

Inheritance

object

Base32

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();

// RFC 4648 Standard Base32 (default).
string standard = Base32.Encode(data);                                      // "NBSWY3DP"

// Crockford Base32 - human-friendly alphabet, no padding.
string crockford = Base32.Encode(data, Base32Variant.Crockford);

// RFC 4648 base32hex - preserves sort order with binary keys.
string base32hex = Base32.Encode(data, Base32Variant.HexExtended);

// Round-trip.
byte[] roundtrip = Base32.Decode(standard);

Remarks

Each variant uses 5 bits per character (radix 32) and groups input bytes into five-byte blocks that map to eight output characters. The padding character = is appended on encode when the input is not a multiple of five bytes; whether padding is emitted by default depends on the variant.

The UpperCase, IncludePrefix, and InsertSpacing flags have no effect on Base32 - each variant emits its canonical alphabet case and there is no standard prefix. The AllowPrefix flag is also ignored on decode for the same reason.

Methods

Decode(char[], int, int, Base32Variant, BaseFormatStyles)

Decodes a portion of a character array into a byte array using the supplied variant.

public static byte[] Decode(char[] chars, int offset, int count, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

chars char[]

The character array.

offset int

The zero-based starting offset.

count int

The number of characters to decode.

variant Base32Variant

The Base32 variant.

style BaseFormatStyles

Parsing styles.

Returns

byte[]

A new byte array representing the decoded binary data.

Exceptions

ArgumentNullException

Thrown when chars is null.

ArgumentOutOfRangeException

Thrown when offset or count is out of range, or when variant is not a defined value.

ArgumentException

Thrown when the segment defined by offset and count exceeds the available range of chars.

FormatException

Thrown when the input is not valid Base32 for the chosen variant and parsing styles.

Decode(ReadOnlySpan<char>, Base32Variant, BaseFormatStyles)

Decodes a Base32 character span into a byte array.

public static byte[] Decode(ReadOnlySpan<char> chars, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

chars ReadOnlySpan<char>

The character span.

variant Base32Variant

The Base32 variant.

style BaseFormatStyles

Parsing styles.

Returns

byte[]

The decoded byte array. Returns Empty<T>() when the input is empty.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is not a defined value.

FormatException

Thrown when the input is not valid Base32 for the chosen variant and parsing styles.

Decode(string, Base32Variant, BaseFormatStyles)

Decodes a Base32 string into a byte array using the supplied variant.

public static byte[] Decode(string s, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

s string

The Base32 input string.

variant Base32Variant

The Base32 variant.

style BaseFormatStyles

Parsing styles that tolerate whitespace and missing padding.

Returns

byte[]

A new byte array representing the decoded binary data.

Exceptions

ArgumentNullException

Thrown when s is null.

ArgumentOutOfRangeException

Thrown when variant is not a defined value.

FormatException

Thrown when the input contains characters outside the variant alphabet, has invalid padding, or has an invalid length for the selected variant.

DecodeFromUtf8(ReadOnlySpan<byte>, Span<byte>, out int, out int, Base32Variant, BaseFormatStyles, bool)

Decodes a UTF-8 Base32 byte span into a byte span with the OperationStatus return convention.

public static OperationStatus DecodeFromUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesConsumed, out int bytesWritten, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles styles = BaseFormatStyles.None, bool isFinalBlock = true)

Parameters

source ReadOnlySpan<byte>

The UTF-8 Base32 source.

destination Span<byte>

The destination byte span.

bytesConsumed int

When this method returns, contains the number of source bytes consumed.

bytesWritten int

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

variant Base32Variant

The variant.

styles BaseFormatStyles

Parsing styles.

isFinalBlock bool

Whether source represents the final block of a streamed input.

Returns

OperationStatus

An OperationStatus describing the outcome.

DecodeGuid(ReadOnlySpan<char>, Base32Variant, BaseFormatStyles)

Decodes a Base32 representation of a Guid.

public static Guid DecodeGuid(ReadOnlySpan<char> source, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The Base32 characters (26 alphabet chars + optional padding).

variant Base32Variant

The Base32 variant.

styles BaseFormatStyles

Parsing styles.

Returns

Guid

The decoded Guid.

Exceptions

FormatException

Thrown when the input does not decode to exactly 16 bytes.

Encode(byte[], Base32Variant, BaseFormattingOptions)

Encodes the entire byte array into a Base32 string using the supplied variant.

public static string Encode(byte[] bytes, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

bytes byte[]

The byte array to encode.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options. Only InsertLineBreaks and OmitPadding are honoured; other flags are ignored.

Returns

string

A Base32 encoded string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when variant is not a defined value.

Encode(byte[], int, int, Base32Variant, BaseFormattingOptions)

Encodes a portion of a byte array into a Base32 string using the supplied variant.

public static string Encode(byte[] bytes, int offset, int count, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

bytes byte[]

The byte array to encode.

offset int

The zero-based offset in bytes at which to begin encoding.

count int

The number of bytes to encode.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options.

Returns

string

A Base32 encoded string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when offset or count is out of range, or when variant is not a defined value.

ArgumentException

Thrown when the segment defined by offset and count exceeds the available range of bytes.

Encode(Guid, Base32Variant, BaseFormattingOptions)

Encodes the byte representation of value as a Base32 string. With no padding the result is 26 characters; with RFC 4648 padding it is 32 characters.

public static string Encode(Guid value, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

value Guid

The Guid to encode.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options.

Returns

string

A Base32 string of the GUID bytes (mixed-endian, matching TryWriteBytes(Span<byte>)).

Encode(ReadOnlySpan<byte>, Base32Variant, BaseFormattingOptions)

Encodes a read-only span of bytes into a Base32 string using the supplied variant.

public static string Encode(ReadOnlySpan<byte> bytes, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options.

Returns

string

A Base32 encoded string. Returns Empty when the input is empty.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is not a defined value.

Encode(ReadOnlySpan<byte>, IBufferWriter<char>, Base32Variant, BaseFormattingOptions)

Encodes source as Base32 characters into writer, suitable for use in pipelines and other IBufferWriter<T>-based scenarios.

public static int Encode(ReadOnlySpan<byte> source, IBufferWriter<char> writer, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<char>

The buffer writer that receives the encoded characters.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options. Only OmitPadding has an effect on this overload; line-break and spacing flags are not supported.

Returns

int

The number of characters written.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

ArgumentException

Thrown when options contains an unsupported flag.

Encode(ReadOnlySpan<byte>, Span<char>, Base32Variant, BaseFormattingOptions)

Encodes a read-only span of bytes directly into a pre-allocated character destination using the supplied variant. Line-break and padding decoration flags are honoured.

public static int Encode(ReadOnlySpan<byte> bytes, Span<char> destination, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The destination span. Must be at least GetEncodedLength(int, Base32Variant, BaseFormattingOptions) characters in size.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options.

Returns

int

The number of characters written.

Exceptions

ArgumentException

Thrown when destination is too small.

ArgumentOutOfRangeException

Thrown when variant is not a defined value.

EncodeToUtf8(ReadOnlySpan<byte>, Base32Variant, BaseFormattingOptions)

Encodes source into a UTF-8 Base32 byte array using the supplied variant and the variant's default padding convention.

public static byte[] EncodeToUtf8(ReadOnlySpan<byte> source, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options. Only OmitPadding has an effect on the UTF-8 path; line-break and spacing flags are not supported.

Returns

byte[]

The UTF-8 encoded Base32 bytes.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

ArgumentException

Thrown when options contains any flag other than OmitPadding.

EncodeToUtf8(ReadOnlySpan<byte>, IBufferWriter<byte>, Base32Variant, BaseFormattingOptions)

Encodes source as UTF-8 Base32 bytes into writer, suitable for use in pipelines and other IBufferWriter<T>-based scenarios.

public static int EncodeToUtf8(ReadOnlySpan<byte> source, IBufferWriter<byte> writer, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<byte>

The buffer writer that receives the UTF-8 bytes.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options. Only OmitPadding is supported.

Returns

int

The number of UTF-8 bytes written.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

ArgumentException

Thrown when options contains an unsupported flag.

FromBase32String(ReadOnlySpan<byte>)

Decodes a UTF-8 encoded Base32 byte span into a byte array using the Standard variant with strict parsing.

public static byte[] FromBase32String(ReadOnlySpan<byte> utf8Source)

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 hexadecimal source.

Returns

byte[]

The decoded byte array.

Remarks

Base32 alphabet characters are ASCII, so the UTF-8 byte form is byte-identical to the character form.

Exceptions

FormatException

Thrown when the input is not strict Standard Base32.

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

Strict-mode Base32 decode from a UTF-8 byte span into a byte span, using the Standard variant.

public static OperationStatus FromBase32String(ReadOnlySpan<byte> utf8Source, Span<byte> destination, out int bytesConsumed, out int bytesWritten)

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 Base32 source.

destination Span<byte>

The destination span.

bytesConsumed int

When this method returns, contains the number of source bytes consumed.

bytesWritten int

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

Returns

OperationStatus

An OperationStatus describing the outcome.

FromBase32String(ReadOnlySpan<char>)

Decodes chars into a byte array using the Standard variant with strict parsing.

public static byte[] FromBase32String(ReadOnlySpan<char> chars)

Parameters

chars ReadOnlySpan<char>

The Base32 character span.

Returns

byte[]

The decoded byte array.

Exceptions

FormatException

Thrown when the input is not strict Standard Base32.

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

Strict-mode Base32 decode from a character span into a byte span, using the Standard variant and the OperationStatus return convention.

public static OperationStatus FromBase32String(ReadOnlySpan<char> source, Span<byte> destination, out int charsConsumed, out int bytesWritten)

Parameters

source ReadOnlySpan<char>

The Base32 characters.

destination Span<byte>

The destination span.

charsConsumed int

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

bytesWritten int

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

Returns

OperationStatus

An OperationStatus describing the outcome.

FromBase32String(string)

Decodes s into a byte array using the Standard variant with strict parsing.

public static byte[] FromBase32String(string s)

Parameters

s string

The Base32 input.

Returns

byte[]

The decoded byte array.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when the input is not strict Standard Base32.

GetDecodedLength(ReadOnlySpan<char>, Base32Variant, BaseFormatStyles)

Computes the exact number of bytes that decoding source would produce after applying styles and stripping padding for the supplied variant.

public static int GetDecodedLength(ReadOnlySpan<char> source, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The input characters.

variant Base32Variant

The Base32 variant.

styles BaseFormatStyles

The parsing styles.

Returns

int

The exact decoded byte count.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

FormatException

Thrown when the input contains characters outside the variant alphabet, or when the digit count is invalid after stripping decorations.

GetEncodedLength(int)

Returns the number of characters produced by encoding byteCount bytes using the Standard variant with default formatting.

public static int GetEncodedLength(int byteCount)

Parameters

byteCount int

The input byte count. Must be non-negative.

Returns

int

The number of characters the encoder will produce.

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative.

GetEncodedLength(int, Base32Variant)

Returns the number of characters produced by encoding byteCount bytes using variant with default formatting.

public static int GetEncodedLength(int byteCount, Base32Variant variant)

Parameters

byteCount int

The input byte count. Must be non-negative.

variant Base32Variant

The Base32 variant.

Returns

int

The number of characters the encoder will produce.

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative or variant is undefined.

GetEncodedLength(int, Base32Variant, BaseFormattingOptions)

Computes the number of characters required to encode byteCount bytes with the given variant and options.

public static int GetEncodedLength(int byteCount, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

byteCount int

The number of input bytes. Must be non-negative.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

The formatting options influencing the output length.

Returns

int

The number of characters that Encode(ReadOnlySpan<byte>, Base32Variant, BaseFormattingOptions) will produce.

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative.

OverflowException

Thrown when the resulting character count would overflow int.

GetMaxDecodedLength(int)

Computes the maximum number of bytes that can result from decoding charCount characters.

public static int GetMaxDecodedLength(int charCount)

Parameters

charCount int

The number of input characters. Must be non-negative.

Returns

int

The upper bound on the decoded byte count.

Exceptions

ArgumentOutOfRangeException

Thrown when charCount is negative.

IsBase32Digit(char, Base32Variant)

Indicates whether value is a valid symbol for the supplied Base32 variant. Padding (= ) is not considered a symbol.

public static bool IsBase32Digit(char value, Base32Variant variant = Base32Variant.Standard)

Parameters

value char

The character to test.

variant Base32Variant

The variant.

Returns

bool

true when the character maps to a value within the variant's alphabet.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

IsValid(ReadOnlySpan<char>, Base32Variant, BaseFormatStyles)

Indicates whether source is a valid Base32 input under the supplied variant and parsing styles.

public static bool IsValid(ReadOnlySpan<char> source, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The input characters.

variant Base32Variant

The variant.

styles BaseFormatStyles

The parsing styles.

Returns

bool

true when the input is valid; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

ToBase32String(byte[])

Encodes inArray into a Base32 string using the Standard variant with default formatting.

public static string ToBase32String(byte[] inArray)

Parameters

inArray byte[]

The byte array to encode.

Returns

string

A Base32 (RFC 4648 §6) string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ToBase32String(byte[], int, int)

Encodes a portion of inArray into a Base32 string using the Standard variant.

public static string ToBase32String(byte[] inArray, int offset, int length)

Parameters

inArray byte[]

The byte array to encode.

offset int

The starting offset.

length int

The number of bytes to encode.

Returns

string

A Base32 string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ArgumentOutOfRangeException

Thrown when offset or length is out of range.

ArgumentException

Thrown when the segment defined by offset and length exceeds the available range of inArray.

ToBase32String(ReadOnlySpan<byte>)

Encodes bytes into a Base32 string using the Standard variant.

public static string ToBase32String(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

A Base32 string.

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

Attempts to decode Base32 characters into bytes using the provided destination span.

public static bool TryDecode(ReadOnlySpan<char> chars, Span<byte> destination, out int bytesWritten, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

chars ReadOnlySpan<char>

The input characters.

destination Span<byte>

The destination span.

bytesWritten int

When this method returns, contains the number of bytes written, or 0 on failure.

variant Base32Variant

The Base32 variant.

style BaseFormatStyles

Parsing styles.

Returns

bool

true on success; false when the input is malformed or the destination is too small.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is not a defined value.

TryDecodeGuid(ReadOnlySpan<char>, out Guid, Base32Variant, BaseFormatStyles)

Attempts to decode a Base32 representation of a Guid.

public static bool TryDecodeGuid(ReadOnlySpan<char> source, out Guid value, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The Base32 characters.

value Guid

When this method returns, contains the decoded Guid or Empty.

variant Base32Variant

The Base32 variant.

styles BaseFormatStyles

Parsing styles.

Returns

bool

true when decoding succeeds; otherwise false.

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

Attempts to encode binary bytes into Base32 characters using the provided destination span.

public static bool TryEncode(ReadOnlySpan<byte> bytes, Span<char> destination, out int charsWritten, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The destination span.

charsWritten int

When this method returns, contains the number of characters written, or 0 when the destination is too small.

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options.

Returns

bool

true when the destination is large enough; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is not a defined value.

TryEncodeToUtf8(ReadOnlySpan<byte>, Span<byte>, out int, Base32Variant, BaseFormattingOptions)

Attempts to encode source as UTF-8 Base32 bytes into destination.

public static bool TryEncodeToUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, Base32Variant variant = Base32Variant.Standard, BaseFormattingOptions options = BaseFormattingOptions.None)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

destination Span<byte>

The destination UTF-8 byte span.

bytesWritten int

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

variant Base32Variant

The Base32 variant.

options BaseFormattingOptions

Formatting options. Only OmitPadding is supported.

Returns

bool

true on success; false when the destination is too small.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

ArgumentException

Thrown when options contains unsupported flags.

TryGetDecodedLength(ReadOnlySpan<char>, out int, Base32Variant, BaseFormatStyles)

Attempts to compute the exact number of decoded bytes for source.

public static bool TryGetDecodedLength(ReadOnlySpan<char> source, out int byteCount, Base32Variant variant = Base32Variant.Standard, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The input characters.

byteCount int

When this method returns, contains the decoded byte count, or 0 on failure.

variant Base32Variant

The Base32 variant.

styles BaseFormatStyles

The parsing styles.

Returns

bool

true when the input would decode cleanly; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

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

Attempts to encode source as UTF-8 Base32 bytes into utf8Destination using the Standard variant.

public static bool TryToBase32String(ReadOnlySpan<byte> source, Span<byte> utf8Destination, out int bytesWritten)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

utf8Destination Span<byte>

The UTF-8 destination span.

bytesWritten int

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

Returns

bool

true on success; false when the destination is too small.

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

Attempts to encode source into destination using the Standard variant without padding decoration.

public static bool TryToBase32String(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 on success; false when the destination is too small.

Applies to

Product	Versions
.NET	8, 10