Base64 Class

Definition

Namespace

Bodu.Text.Encoding

Assembly

Bodu.Text.Encoding.dll

Package

Bodu.Text.Encoding 1.0.0

Source

Base64.BclAliases.cs

Provides Base64 encoding and decoding of binary data across the RFC 4648 standard, URL-safe, and MIME variants, with optional padding control and whitespace tolerance during parsing.

public static class Base64

Inheritance

object

Base64

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 Base64 (default).
string standard = Base64.Encode(data);                                       // "aGVsbG8="

// URL-safe alphabet, no padding - the form used by JWT and OAuth tokens.
string urlSafe  = Base64.Encode(data, Base64Variant.UrlSafe);                // "aGVsbG8"

// MIME variant - wraps every 76 characters with CRLF.
string mime     = Base64.Encode(longerPayload, Base64Variant.Mime);

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

Remarks

The implementation delegates the inner radix conversion to Convert's ToBase64String(byte[], Base64FormattingOptions), TryToBase64Chars(ReadOnlySpan<byte>, Span<char>, out int, Base64FormattingOptions), and TryFromBase64Chars(ReadOnlySpan<char>, Span<byte>, out int) to inherit their hardware-accelerated paths. The wrapper supplies the alphabet swapping for UrlSafe, the line-break convention for Mime, and the padding / leniency flag handling that the BCL does not expose directly.

MIME line breaks are inserted every 76 characters (RFC 2045). The UpperCase, IncludePrefix, and InsertSpacing flags have no effect on Base64.

Methods

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

Decodes a portion of a character array into a byte array.

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

Parameters

chars char[]

The character array.

offset int

The starting offset.

count int

The number of characters.

variant Base64Variant

The Base64 variant.

style BaseFormatStyles

Parsing styles.

Returns

byte[]

A new byte array containing the decoded data.

Exceptions

ArgumentNullException

Thrown when chars is null.

ArgumentOutOfRangeException

Thrown when offset or count is out of range, or when variant is undefined.

ArgumentException

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

FormatException

Thrown when the input is not valid Base64.

Decode(ReadOnlySpan<char>, Base64Variant, BaseFormatStyles)

Decodes a Base64 character span into a byte array.

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

Parameters

chars ReadOnlySpan<char>

The character span.

variant Base64Variant

The Base64 variant.

style BaseFormatStyles

Parsing styles.

Returns

byte[]

A new byte array containing the decoded data. Returns Empty<T>() when the input is empty.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

FormatException

Thrown when the input is not valid Base64.

Decode(string, Base64Variant, BaseFormatStyles)

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

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

Parameters

s string

The Base64 input string.

variant Base64Variant

The Base64 variant.

style BaseFormatStyles

Parsing styles.

Returns

byte[]

A new byte array containing the decoded data.

Exceptions

ArgumentNullException

Thrown when s is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

FormatException

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

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

Decodes UTF-8 Base64 bytes into a byte span using the OperationStatus return convention.

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

Parameters

source ReadOnlySpan<byte>

The UTF-8 Base64 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.

variant Base64Variant

The variant.

styles BaseFormatStyles

Parsing styles.

isFinalBlock bool

Whether source represents the final block.

Returns

OperationStatus

An OperationStatus describing the outcome.

DecodeGuid(ReadOnlySpan<char>, Base64Variant, BaseFormatStyles)

Decodes a Base64 representation of a Guid.

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

Parameters

source ReadOnlySpan<char>

The Base64 characters.

variant Base64Variant

The Base64 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[], Base64Variant, BaseFormattingOptions)

Encodes the entire byte array into a Base64 string.

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

Parameters

bytes byte[]

The byte array to encode.

variant Base64Variant

The Base64 variant.

options BaseFormattingOptions

Formatting options. Only InsertLineBreaks and OmitPadding have an effect on Base64.

Returns

string

The Base64 encoded string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

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

Encodes a portion of a byte array into a Base64 string.

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

Parameters

bytes byte[]

The byte array to encode.

offset int

The starting offset.

count int

The number of bytes to encode.

variant Base64Variant

The Base64 variant.

options BaseFormattingOptions

Formatting options.

Returns

string

The Base64 encoded string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when offset or count is out of range, or when variant is undefined.

ArgumentException

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

Encode(Guid, Base64Variant, BaseFormattingOptions)

Encodes the byte representation of value as a Base64 string. With RFC 4648 padding the result is 24 characters; without padding it is 22 characters.

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

Parameters

value Guid

The Guid to encode.

variant Base64Variant

The Base64 variant.

options BaseFormattingOptions

Formatting options.

Returns

string

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

Encode(ReadOnlySpan<byte>, Base64Variant, BaseFormattingOptions)

Encodes a span of bytes into a Base64 string.

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

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

variant Base64Variant

The Base64 variant.

options BaseFormattingOptions

Formatting options.

Returns

string

The Base64 encoded string.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

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

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

public static int Encode(ReadOnlySpan<byte> source, IBufferWriter<char> writer, Base64Variant variant = Base64Variant.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 Base64Variant

The Base64 variant.

options BaseFormattingOptions

Formatting options. Only OmitPadding is 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>, Base64Variant, BaseFormattingOptions)

Encodes a span of bytes directly into a destination character span.

public static int Encode(ReadOnlySpan<byte> bytes, Span<char> destination, Base64Variant variant = Base64Variant.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, Base64Variant, BaseFormattingOptions) characters in size.

variant Base64Variant

The Base64 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 undefined.

EncodeToUtf8(ReadOnlySpan<byte>, Base64Variant, BaseFormattingOptions)

Encodes source into a UTF-8 Base64 byte array.

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

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

variant Base64Variant

The Base64 variant.

options BaseFormattingOptions

Formatting options. Only OmitPadding has an effect on the UTF-8 fast path.

Returns

byte[]

The UTF-8 encoded Base64 bytes.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

ArgumentException

Thrown when options contains any flag other than OmitPadding.

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

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

public static int EncodeToUtf8(ReadOnlySpan<byte> source, IBufferWriter<byte> writer, Base64Variant variant = Base64Variant.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 Base64Variant

The Base64 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.

FromBase64String(ReadOnlySpan<byte>)

Decodes UTF-8 Base64 bytes into a byte array using the Standard variant.

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

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 Base64 source.

Returns

byte[]

The decoded byte array.

Exceptions

FormatException

Thrown when the input is not valid Standard Base64.

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

Strict-mode Standard Base64 decode from a UTF-8 byte span.

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

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 Base64 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.

Returns

OperationStatus

An OperationStatus describing the outcome.

FromBase64String(ReadOnlySpan<char>)

Decodes chars as a Standard Base64 character span into a byte array, mirroring the lenient whitespace behaviour of FromBase64String(string).

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

Parameters

chars ReadOnlySpan<char>

The Base64 character span.

Returns

byte[]

The decoded byte array.

Exceptions

FormatException

Thrown when the input is not valid Standard Base64.

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

Strict-mode Standard Base64 decode from a character span using the OperationStatus return convention.

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

Parameters

source ReadOnlySpan<char>

The Base64 characters.

destination Span<byte>

The destination byte 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.

FromBase64String(string)

Decodes s as a Standard Base64 string into a byte array, mirroring the lenient whitespace behaviour of FromBase64String(string). ASCII whitespace anywhere in the input is silently ignored; the canonical-padding rule and alphabet are otherwise enforced strictly.

public static byte[] FromBase64String(string s)

Parameters

s string

The Base64 input.

Returns

byte[]

The decoded byte array.

Remarks

To reject whitespace strictly, call Decode(string, Base64Variant, BaseFormatStyles) directly with None.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when the input is not valid Standard Base64.

GetDecodedLength(ReadOnlySpan<char>, Base64Variant, 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, Base64Variant variant = Base64Variant.Standard, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The Base64 character span.

variant Base64Variant

The Base64 variant.

styles BaseFormatStyles

Parsing styles.

Returns

int

The exact decoded byte count.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

FormatException

Thrown when the input contains invalid characters or the digit count is not a valid Base64 length.

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, Base64Variant)

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

public static int GetEncodedLength(int byteCount, Base64Variant variant)

Parameters

byteCount int

The input byte count.

variant Base64Variant

The Base64 variant.

Returns

int

The number of characters the encoder will produce.

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative or variant is undefined.

GetEncodedLength(int, Base64Variant, BaseFormattingOptions)

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

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

Parameters

byteCount int

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

variant Base64Variant

The Base64 variant.

options BaseFormattingOptions

The formatting options.

Returns

int

The number of characters the matching encode overload will produce.

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative.

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.

IsBase64Digit(char, Base64Variant)

Indicates whether value is a valid Base64 alphabet character for the supplied variant. Padding (=) is not considered a digit.

public static bool IsBase64Digit(char value, Base64Variant variant = Base64Variant.Standard)

Parameters

value char

The character to test.

variant Base64Variant

The variant.

Returns

bool

true when the character belongs to the variant alphabet.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

IsValid(ReadOnlySpan<char>, Base64Variant, BaseFormatStyles)

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

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

Parameters

source ReadOnlySpan<char>

The character span.

variant Base64Variant

The variant.

styles BaseFormatStyles

Parsing styles.

Returns

bool

true when the input would decode cleanly; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

ToBase64String(byte[])

Encodes inArray into a Standard Base64 string with default formatting.

public static string ToBase64String(byte[] inArray)

Parameters

inArray byte[]

The byte array to encode.

Returns

string

A Base64 (RFC 4648 §4) string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ToBase64String(byte[], int, int)

Encodes a portion of inArray into a Standard Base64 string.

public static string ToBase64String(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 Base64 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.

ToBase64String(ReadOnlySpan<byte>)

Encodes bytes into a Standard Base64 string.

public static string ToBase64String(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

A Base64 string.

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

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

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

Parameters

chars ReadOnlySpan<char>

The input characters.

destination Span<byte>

The destination byte span.

bytesWritten int

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

variant Base64Variant

The Base64 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 undefined.

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

Attempts to decode a Base64 representation of a Guid.

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

Parameters

source ReadOnlySpan<char>

The Base64 characters.

value Guid

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

variant Base64Variant

The Base64 variant.

styles BaseFormatStyles

Parsing styles.

Returns

bool

true when decoding succeeds; otherwise false.

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

Attempts to encode a span of bytes into a destination character span.

public static bool TryEncode(ReadOnlySpan<byte> bytes, Span<char> destination, out int charsWritten, Base64Variant variant = Base64Variant.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 Base64Variant

The Base64 variant.

options BaseFormattingOptions

Formatting options.

Returns

bool

true when the destination is large enough; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

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

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

public static bool TryEncodeToUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, Base64Variant variant = Base64Variant.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 Base64Variant

The Base64 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 unsupported flags are set in options.

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

Attempts to compute the exact decoded byte count for source.

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

Parameters

source ReadOnlySpan<char>

The Base64 character span.

byteCount int

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

variant Base64Variant

The Base64 variant.

styles BaseFormatStyles

Parsing styles.

Returns

bool

true when the input would decode cleanly; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

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

Attempts to encode source as a Standard Base64 UTF-8 byte sequence into utf8Destination.

public static bool TryToBase64String(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.

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

Attempts to encode source into destination as a Standard Base64 character sequence.

public static bool TryToBase64String(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