Table of Contents

Base16 Class

Definition

Namespace
Bodu.Text.Encoding
Assembly
Bodu.Text.Encoding.dll
Package
Bodu.Text.Encoding 1.0.0
Source
Base16.BclAliases.cs

Provides Base16 (hexadecimal) encoding and decoding of binary data, with support for flexible output formatting (case selection, byte spacing, line wrapping, 0x prefix) and lenient input parsing (prefix tolerance, whitespace stripping).

public static class Base16
Inheritance
Base16
Inherited Members

Examples

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

// Canonical lower-case hex.
string lower = Base16.Encode(data);                                           // "deadbeef"

// Upper-case with the "0x" prefix and byte spacing - useful for diagnostic output.
string pretty = Base16.Encode(data, BaseFormattingOptions.UpperCase
                                   | BaseFormattingOptions.IncludePrefix
                                   | BaseFormattingOptions.InsertSpacing);    // "0xDE AD BE EF"

// Lenient decoding - accepts the "0x" prefix and embedded whitespace.
byte[] roundtrip = Base16.Decode(pretty,
    BaseFormatStyles.AllowPrefix | BaseFormatStyles.IgnoreWhitespace);

Remarks

Encode(ReadOnlySpan<byte>, BaseFormattingOptions) emits two hexadecimal characters per input byte using the configured BaseFormattingOptions flags. Decode(ReadOnlySpan<char>, BaseFormatStyles) reverses the operation and accepts decoration tolerance via BaseFormatStyles.

All public methods are thread-safe - the type is stateless. The implementation provides allocation-minimal fast paths when no decoration flags are set, and falls back to a StringBuilder-based writer when spacing, prefix, or line breaks are requested.

Methods

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

Decodes a portion of a character array containing hexadecimal-encoded data into a byte array.

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

Parameters

chars char[]

The character array containing Base16 (hex) characters.

offset int

The zero-based starting position within chars.

count int

The number of characters to decode.

style BaseFormatStyles

Parsing styles that allow optional prefix and whitespace tolerance.

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 negative, or either exceeds the bounds of chars.

ArgumentException

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

FormatException

Thrown when the input contains non-hexadecimal characters, or when it has an odd number of hex digits after applying style.

Decode(ReadOnlySpan<char>, BaseFormatStyles)

Decodes a read-only span of hexadecimal characters into a byte array.

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

Parameters

chars ReadOnlySpan<char>

The span containing Base16 (hex) characters.

style BaseFormatStyles

Parsing styles that allow optional prefix and whitespace tolerance.

Returns

byte[]

A new byte array representing the decoded binary data. Returns Empty<T>() when chars is empty.

Exceptions

FormatException

Thrown when the input contains non-hexadecimal characters, or when it has an odd number of hex digits after applying style.

Decode(string, BaseFormatStyles)

Decodes a hexadecimal-encoded string into a byte array.

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

Parameters

s string

The string containing Base16 (hex) characters.

style BaseFormatStyles

Parsing styles that allow optional prefix and whitespace tolerance.

Returns

byte[]

A new byte array representing the decoded binary data.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when the input contains non-hexadecimal characters, or when it has an odd number of hex digits after applying style.

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

Streaming decode of a UTF-8 hexadecimal byte span into a byte span, with leniency styles and a streaming indicator.

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

Parameters

source ReadOnlySpan<byte>

The UTF-8 hexadecimal source bytes.

destination Span<byte>

The destination span receiving decoded bytes.

bytesConsumed int

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

bytesWritten int

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

styles BaseFormatStyles

Parsing styles influencing leniency.

isFinalBlock bool

When true, the decoder enforces that the input forms complete byte pairs and any trailing partial pair is reported as InvalidData. When false, a trailing single character is reported as NeedMoreData so the caller can resume on more input.

Returns

OperationStatus

An OperationStatus describing the outcome.

DecodeGuid(ReadOnlySpan<char>, BaseFormatStyles)

Decodes a hexadecimal representation of a Guid.

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

Parameters

source ReadOnlySpan<char>

The hexadecimal characters (32 hex digits after any decoration is stripped).

styles BaseFormatStyles

Parsing styles to apply when interpreting decorations.

Returns

Guid

The decoded Guid.

Exceptions

FormatException

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

Encode(byte[], Base16Variant, BaseFormattingOptions)

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

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

Parameters

bytes byte[]

The byte array to encode.

variant Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options to apply, such as spacing, prefix, or line breaks.

Returns

string

A Base16 encoded string representing the input bytes.

Remarks

This is the variant-based form of Encode(byte[], BaseFormattingOptions), sharing the uniform (bytes, variant, options) shape used by the other Base-N families. The case selected by variant takes precedence over UpperCase.

Exceptions

ArgumentNullException

Thrown when bytes is null.

Encode(byte[], BaseFormattingOptions)

Encodes the entire byte array into a hexadecimal string.

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

Parameters

bytes byte[]

The byte array to encode.

options BaseFormattingOptions

Formatting options to apply, such as upper case, spacing, prefix, or line breaks.

Returns

string

A Base16 encoded string representing the input bytes.

Exceptions

ArgumentNullException

Thrown when bytes is null.

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

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

public static string Encode(byte[] bytes, int offset, int count, Base16Variant variant, 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 Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options to apply, such as spacing, prefix, or line breaks.

Returns

string

A Base16 encoded string representing the selected slice of bytes.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when offset or count is negative, or either exceeds the bounds of bytes.

ArgumentException

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

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

Encodes a portion of a byte array into a formatted hexadecimal string.

public static string Encode(byte[] bytes, int offset, int count, 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.

options BaseFormattingOptions

Formatting options to apply, such as upper case, spacing, prefix, or line breaks.

Returns

string

A Base16 encoded string representing the selected slice of bytes.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when offset or count is negative, or either exceeds the bounds of bytes.

ArgumentException

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

Encode(Guid, BaseFormattingOptions)

Encodes the byte representation of value as a hexadecimal string.

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

Parameters

value Guid

The Guid to encode.

options BaseFormattingOptions

Formatting options applied to the hex output (case, prefix, spacing, line breaks).

Returns

string

A Base16 string of the Guid's 16 underlying bytes (mixed-endian, matching TryWriteBytes(Span<byte>)).

Remarks

The encoding uses the GUID's native byte layout - the first three fields are little-endian, the fourth is big-endian. This matches ToByteArray() and TryWriteBytes(Span<byte>), so the result of DecodeGuid(ReadOnlySpan<char>, BaseFormatStyles) reconstructs the original Guid exactly.

Encode(ReadOnlySpan<byte>, Base16Variant, BaseFormattingOptions)

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

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

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

variant Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options to apply, such as spacing, prefix, or line breaks.

Returns

string

A Base16 encoded string.

Remarks

The case selected by variant takes precedence over UpperCase.

Encode(ReadOnlySpan<byte>, BaseFormattingOptions)

Encodes a read-only span of bytes into a formatted hexadecimal string.

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

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

options BaseFormattingOptions

Formatting options to apply, such as upper case, spacing, prefix, or line breaks.

Returns

string

A Base16 encoded string. When bytes is empty and IncludePrefix is set, the result is the prefix string alone; otherwise the result is Empty.

Remarks

Provides the optimal allocation profile when no formatting flags beyond UpperCase are specified. When spacing, prefix, or line break flags are requested, the implementation falls back to a StringBuilder-backed writer.

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

Encodes source as hexadecimal characters into writer using the supplied variant.

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

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<char>

The buffer writer that receives the encoded characters.

variant Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options. Only UpperCase is supported on this overload; variant takes precedence over it for the alphabet case.

Returns

int

The number of characters written to writer.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentException

Thrown when options contains any flag other than UpperCase.

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

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

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

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<char>

The buffer writer that receives the encoded characters.

options BaseFormattingOptions

Formatting options. Only UpperCase is supported on this overload - formatted output (spacing, prefix, line breaks) is not compatible with the writer's contiguous span contract. For decorated output, call Encode(ReadOnlySpan<byte>, BaseFormattingOptions) and write the resulting string explicitly.

Returns

int

The number of characters written to writer.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentException

Thrown when options contains any flag other than UpperCase.

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

Encodes a read-only span of bytes directly into a pre-allocated character destination using the supplied variant.

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

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The span that receives the encoded characters.

variant Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options. Only UpperCase is supported on this overload; variant takes precedence over it for the alphabet case.

Returns

int

The number of characters written to destination.

Exceptions

ArgumentException

Thrown when options contains any flag other than UpperCase, or when destination is too small to receive the encoded output.

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

Encodes a read-only span of bytes directly into a pre-allocated character destination.

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

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The span that receives the encoded characters.

options BaseFormattingOptions

Formatting options. Only UpperCase is supported on this overload.

Returns

int

The number of characters written to destination.

Exceptions

ArgumentException

Thrown when options contains any flag other than UpperCase, or when destination is too small to receive the encoded output.

EncodeToUtf8(ReadOnlySpan<byte>)

Encodes source into a UTF-8 hexadecimal byte array using lower case characters.

public static byte[] EncodeToUtf8(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

Returns

byte[]

A UTF-8 encoded hexadecimal byte array. Each input byte produces two output bytes.

Remarks

Hexadecimal characters are ASCII, so each UTF-8 byte equals the ASCII code of its corresponding character.

EncodeToUtf8(ReadOnlySpan<byte>, Base16Variant)

Encodes source into a UTF-8 hexadecimal byte array using the supplied variant.

public static byte[] EncodeToUtf8(ReadOnlySpan<byte> source, Base16Variant variant)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

variant Base16Variant

The Base16 alphabet case.

Returns

byte[]

A UTF-8 encoded hexadecimal byte array. Each input byte produces two output bytes.

Remarks

This is the variant-based form of EncodeToUtf8(ReadOnlySpan<byte>). Hexadecimal characters are ASCII, so each UTF-8 byte equals the ASCII code of its corresponding character.

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

Encodes source as UTF-8 hexadecimal bytes into writer using the supplied variant.

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

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<byte>

The buffer writer that receives the UTF-8 hexadecimal bytes.

variant Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options. Only UpperCase is supported on this overload; variant takes precedence over it for the alphabet case.

Returns

int

The number of UTF-8 bytes written to writer.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentException

Thrown when options contains any flag other than UpperCase.

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

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

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

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<byte>

The buffer writer that receives the UTF-8 hexadecimal bytes.

options BaseFormattingOptions

Formatting options. Only UpperCase is supported on this overload.

Returns

int

The number of UTF-8 bytes written to writer.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentException

Thrown when options contains any flag other than UpperCase.

FromHexString(ReadOnlySpan<byte>)

Decodes a UTF-8 encoded hexadecimal byte span into a byte array using strict parsing.

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

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 hexadecimal source.

Returns

byte[]

The decoded byte array.

Remarks

Hexadecimal characters are ASCII, so the UTF-8 representation is bit-identical to the character form. This overload avoids allocating a string when the caller already has the input as bytes.

Exceptions

FormatException

Thrown when the input is not strict hex.

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

Strict-mode streaming decode of a UTF-8 hexadecimal byte span into a byte span.

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

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 hexadecimal 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

Done on full success; DestinationTooSmall when destination cannot fit the result; InvalidData for invalid characters or odd source length.

FromHexString(ReadOnlySpan<char>)

Decodes a hexadecimal character span into a byte array using strict parsing.

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

Parameters

chars ReadOnlySpan<char>

The hexadecimal characters.

Returns

byte[]

The decoded byte array.

Exceptions

FormatException

Thrown when the input is not strict hex.

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

Strict-mode streaming decode of a hexadecimal character span into a byte span.

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

Parameters

source ReadOnlySpan<char>

The hexadecimal 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

Done on full success; DestinationTooSmall when destination cannot fit the result; InvalidData for invalid characters or odd source length.

FromHexString(string)

Decodes a hexadecimal string into a byte array using strict parsing (no prefix, no whitespace).

public static byte[] FromHexString(string s)

Parameters

s string

The hexadecimal input.

Returns

byte[]

The decoded byte array.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when the input is not strict hex.

GetDecodedLength(ReadOnlySpan<char>, BaseFormatStyles)

Computes the exact number of bytes that decoding source would produce after stripping decorations permitted by styles.

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

Parameters

source ReadOnlySpan<char>

The hexadecimal input.

styles BaseFormatStyles

The parsing styles.

Returns

int

The exact byte count that Decode(ReadOnlySpan<char>, BaseFormatStyles) would return.

Exceptions

FormatException

Thrown when the post-decoration digit count is odd, which indicates the input cannot decode cleanly.

GetEncodedLength(int)

Returns the number of characters produced by encoding byteCount bytes with strict formatting (no decorations).

public static int GetEncodedLength(int byteCount)

Parameters

byteCount int

The input byte count. Must be non-negative.

Returns

int

byteCount * 2.

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative.

GetEncodedLength(int, BaseFormattingOptions)

Computes the number of characters required to encode byteCount bytes with the supplied formatting options.

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

Parameters

byteCount int

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

options BaseFormattingOptions

The formatting options that influence the output length.

Returns

int

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

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative.

OverflowException

Thrown when byteCount is large enough that 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 number of decoded bytes. The actual byte count will be lower when the input contains decorations that are stripped during parsing.

Exceptions

ArgumentOutOfRangeException

Thrown when charCount is negative.

IsHexDigit(char)

Indicates whether value is one of the 22 hexadecimal digit characters.

public static bool IsHexDigit(char value)

Parameters

value char

The character to test.

Returns

bool

true for '0'-'9', 'A'-'F', and 'a'-'f'; otherwise false.

IsValid(ReadOnlySpan<char>, BaseFormatStyles)

Indicates whether source is a valid hexadecimal input under the supplied parsing styles.

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

Parameters

source ReadOnlySpan<char>

The input characters.

styles BaseFormatStyles

The parsing styles.

Returns

bool

true when every retained character is a hex digit and the retained count is even; otherwise false.

ToHexString(byte[])

Encodes inArray into an upper case hexadecimal string. Aliases ToHexString(byte[]) with no formatting decorations.

public static string ToHexString(byte[] inArray)

Parameters

inArray byte[]

The byte array to encode.

Returns

string

An upper case hexadecimal string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ToHexString(byte[], int, int)

Encodes a portion of inArray into an upper case hexadecimal string.

public static string ToHexString(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

An upper case hexadecimal string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ArgumentOutOfRangeException

Thrown when offset or length is out of range for inArray.

ArgumentException

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

ToHexString(ReadOnlySpan<byte>)

Encodes bytes into an upper case hexadecimal string.

public static string ToHexString(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

An upper case hexadecimal string.

ToHexStringLower(byte[])

Encodes inArray into a lower case hexadecimal string. Mirrors Convert.ToHexStringLower introduced in .NET 9.

public static string ToHexStringLower(byte[] inArray)

Parameters

inArray byte[]

The byte array to encode.

Returns

string

A lower case hexadecimal string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ToHexStringLower(byte[], int, int)

Encodes a portion of inArray into a lower case hexadecimal string.

public static string ToHexStringLower(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 lower case hexadecimal string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ArgumentOutOfRangeException

Thrown when offset or length is out of range for inArray.

ArgumentException

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

ToHexStringLower(ReadOnlySpan<byte>)

Encodes bytes into a lower case hexadecimal string.

public static string ToHexStringLower(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

Returns

string

A lower case hexadecimal string.

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

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

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

Parameters

chars ReadOnlySpan<char>

The span of characters to decode.

destination Span<byte>

The span that receives the decoded bytes.

bytesWritten int

When this method returns, contains the number of bytes written, or 0 when decoding failed.

style BaseFormatStyles

Parsing styles that allow optional prefix and whitespace tolerance.

Returns

bool

true when decoding succeeded; false when the input is malformed or destination is too small.

Remarks

This method never throws for malformed input - it returns false instead. Callers that require exception semantics should use Decode(ReadOnlySpan<char>, BaseFormatStyles).

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

Attempts to decode a hexadecimal representation of a Guid.

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

Parameters

source ReadOnlySpan<char>

The hexadecimal characters.

value Guid

When this method returns, contains the decoded Guid or Empty when the input is invalid.

styles BaseFormatStyles

Parsing styles to apply when interpreting decorations.

Returns

bool

true when decoding succeeds; otherwise false.

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

Attempts to encode binary bytes into hexadecimal characters using the supplied variant and destination span.

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

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The span that receives the encoded characters.

charsWritten int

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

variant Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options. Only UpperCase is supported on this overload; variant takes precedence over it for the alphabet case.

Returns

bool

true when the destination is large enough and the encoding succeeded; otherwise false.

Exceptions

ArgumentException

Thrown when options contains any flag other than UpperCase.

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

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

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

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The span that receives the encoded characters.

charsWritten int

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

options BaseFormattingOptions

Formatting options. Only UpperCase is supported on this overload.

Returns

bool

true when the destination is large enough and the encoding succeeded; otherwise false.

Exceptions

ArgumentException

Thrown when options contains any flag other than UpperCase.

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

Attempts to encode source into destination as UTF-8 hexadecimal bytes using the supplied variant.

public static bool TryEncodeToUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, Base16Variant variant, 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 UTF-8 bytes written.

variant Base16Variant

The Base16 alphabet case.

options BaseFormattingOptions

Additional formatting options. Only UpperCase is honoured; variant takes precedence over it for the alphabet case.

Returns

bool

true when destination is large enough; otherwise false .

Exceptions

ArgumentException

Thrown when options contains any flag other than UpperCase.

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

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

public static bool TryEncodeToUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, 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 UTF-8 bytes written.

options BaseFormattingOptions

Formatting options. Only UpperCase is honoured; line-break / spacing / prefix flags are not supported on the UTF-8 fast path.

Returns

bool

true when destination is large enough; otherwise false .

Exceptions

ArgumentException

Thrown when options contains any flag other than UpperCase.

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

Attempts to compute the exact number of bytes that decoding source would produce.

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

Parameters

source ReadOnlySpan<char>

The hexadecimal input.

byteCount int

When this method returns, contains the byte count, or 0 when the input is malformed.

styles BaseFormatStyles

The parsing styles.

Returns

bool

true when the input would decode cleanly; otherwise false.

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

Attempts to encode source into UTF-8 utf8Destination using upper case hex.

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

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

Attempts to encode source into destination using upper case hex.

public static bool TryToHexString(ReadOnlySpan<byte> source, Span<char> destination, out int charsWritten)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

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

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

Attempts to encode source into UTF-8 utf8Destination using lower case hex.

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

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

Attempts to encode source into destination using lower case hex.

public static bool TryToHexStringLower(ReadOnlySpan<byte> source, Span<char> destination, out int charsWritten)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The destination character 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

ProductVersions
.NET8, 10