StringEncodingExtensions Class

Definition

Namespace

Bodu.Text

Assembly

Bodu.Core.dll

Package

Bodu.Core 1.0.1

Source

StringEncodingExtensions.EncodeTo.cs

Provides encoding extension methods on string that mirror the span-receiver surface in EncodingExtensions.

public static class StringEncodingExtensions

Inheritance

object

StringEncodingExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Fluent encoding of a string variable.
byte[] utf8       = "héllo".ToUtf8Bytes();
byte[] withBom    = "héllo".ToBytesWithPreamble(new System.Text.UTF8Encoding(true));

// Pool-backed encoding for a network send.
using PooledBufferBuilder<byte> pooled = jsonPayload.GetUtf8BytesPooled();
await socket.SendAsync(pooled.WrittenMemory, SocketFlags.None);

// Pipeline integration.
"key=value\n".WriteUtf8To(pipeWriter);

Remarks

Members are split across partial files following the repository convention (see CLAUDE.md): one partial file per method, named StringEncodingExtensions.<MethodName>.cs. Tests follow the same pattern in test/Text.Encoding/StringEncodingExtensionsTests.<MethodName>.cs.

All overloads delegate to the canonical span- or encoding-receiver implementations in EncodingExtensions so behaviour and performance match the rest of the encoding surface.

Methods

EncodeTo(string, Encoding, Span<byte>)

Encodes text into destination using encoding and returns the number of bytes written.

public static int EncodeTo(this string text, Encoding encoding, Span<byte> destination)

Parameters

text string

The string to encode.

encoding Encoding

The encoding used to produce the bytes.

destination Span<byte>

The destination buffer. Must be large enough to hold the encoded output.

Returns

int

The number of bytes written to destination.

Exceptions

ArgumentNullException

Thrown when text or encoding is null.

ArgumentException

Thrown when destination is too small to hold the encoded output.

EncoderFallbackException

Thrown when encoding uses EncoderExceptionFallback and text contains a code point that cannot be represented.

EncodeUtf8To(string, Span<byte>)

Encodes text as UTF-8 into destination and returns the number of bytes written.

public static int EncodeUtf8To(this string text, Span<byte> destination)

Parameters

text string

The string to encode.

destination Span<byte>

The destination buffer. Must be large enough to hold the UTF-8 encoded output.

Returns

int

The number of bytes written to destination.

Exceptions

ArgumentNullException

Thrown when text is null.

ArgumentException

Thrown when destination is too small to hold the UTF-8 encoded output.

GetBytesPooled(string, Encoding)

Encodes text into a pool-backed PooledBufferBuilder<T> using encoding.

public static PooledBufferBuilder<byte> GetBytesPooled(this string text, Encoding encoding)

Parameters

text string

The string to encode.

encoding Encoding

The encoding used to produce the bytes.

Returns

PooledBufferBuilder<byte>

A PooledBufferBuilder<T> with WrittenCount equal to the exact number of encoded bytes. The builder is both an IBufferWriter<T> and an IMemoryOwner<T>; dispose to return the rented buffer to Shared.

Exceptions

ArgumentNullException

Thrown when text or encoding is null.

EncoderFallbackException

Thrown when encoding uses EncoderExceptionFallback and text contains a code point that cannot be represented.

GetEncodedByteCount(string, Encoding)

Returns the exact number of bytes produced by encoding text with encoding.

public static int GetEncodedByteCount(this string text, Encoding encoding)

Parameters

text string

The string to measure.

encoding Encoding

The encoding used to compute the byte count.

Returns

int

The exact number of bytes required to encode text.

Remarks

Equivalent to GetByteCount(string) but expressed as an extension so fluent code can chain from a string variable.

Exceptions

ArgumentNullException

Thrown when text or encoding is null.

GetUtf8ByteCount(string)

Returns the exact number of UTF-8 bytes required to encode text.

public static int GetUtf8ByteCount(this string text)

Parameters

text string

The string to measure.

Returns

int

The exact UTF-8 byte count.

Exceptions

ArgumentNullException

Thrown when text is null.

GetUtf8BytesPooled(string)

Encodes text as UTF-8 into a pool-backed PooledBufferBuilder<T>.

public static PooledBufferBuilder<byte> GetUtf8BytesPooled(this string text)

Parameters

text string

The string to encode.

Returns

PooledBufferBuilder<byte>

A PooledBufferBuilder<T> with WrittenCount equal to the exact number of UTF-8 bytes. The builder is both an IBufferWriter<T> and an IMemoryOwner<T>; dispose to return the rented buffer to Shared.

Examples

// Encode a large JSON document to UTF-8 without a permanent allocation, then hand the
// pooled buffer to a network writer before disposal returns the array to the pool.
using PooledBufferBuilder<byte> pooled = jsonText.GetUtf8BytesPooled();
await socket.SendAsync(pooled.WrittenMemory, SocketFlags.None);

Exceptions

ArgumentNullException

Thrown when text is null.

ToBytes(string, Encoding)

Encodes text into a freshly allocated byte array using encoding.

public static byte[] ToBytes(this string text, Encoding encoding)

Parameters

text string

The string to encode.

encoding Encoding

The encoding used to produce the bytes.

Returns

byte[]

A new byte array containing the encoded representation of text.

Exceptions

ArgumentNullException

Thrown when text or encoding is null.

EncoderFallbackException

Thrown when encoding uses EncoderExceptionFallback and text contains a code point that cannot be represented.

ToBytesWithPreamble(string, Encoding)

Encodes text into a freshly allocated byte array preceded by encoding's preamble.

public static byte[] ToBytesWithPreamble(this string text, Encoding encoding)

Parameters

text string

The string to encode.

encoding Encoding

The encoding used to produce the bytes.

Returns

byte[]

A new byte array containing the preamble followed by the encoded bytes.

Exceptions

ArgumentNullException

Thrown when text or encoding is null.

EncoderFallbackException

Thrown when encoding uses EncoderExceptionFallback and text contains a code point that cannot be represented.

ToUtf8Bytes(string)

Encodes text into a freshly allocated UTF-8 byte array.

public static byte[] ToUtf8Bytes(this string text)

Parameters

text string

The string to encode.

Returns

byte[]

A new byte array containing the UTF-8 representation of text.

Examples

// Convert a configuration value to UTF-8 bytes for hashing.
byte[] payload = "client-secret".ToUtf8Bytes();
byte[] hash    = SHA256.HashData(payload);

Exceptions

ArgumentNullException

Thrown when text is null.

TryEncodeTo(string, Encoding, Span<byte>, out int)

Attempts to encode text into destination using encoding without throwing when the destination is too small.

public static bool TryEncodeTo(this string text, Encoding encoding, Span<byte> destination, out int bytesWritten)

Parameters

text string

The string to encode.

encoding Encoding

The encoding used to produce the bytes.

destination Span<byte>

The destination buffer.

bytesWritten int

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

Returns

bool

true if the encoding completed successfully; false when destination is too small.

Exceptions

ArgumentNullException

Thrown when text or encoding is null.

EncoderFallbackException

Thrown when encoding uses EncoderExceptionFallback and text contains a code point that cannot be represented.

TryEncodeUtf8To(string, Span<byte>, out int)

Attempts to encode text as UTF-8 into destination without throwing when the destination is too small.

public static bool TryEncodeUtf8To(this string text, Span<byte> destination, out int bytesWritten)

Parameters

text string

The string to encode.

destination Span<byte>

The destination buffer.

bytesWritten int

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

Returns

bool

true if the encoding completed successfully; false when destination is too small.

Exceptions

ArgumentNullException

Thrown when text is null.

WriteTo(string, Encoding, IBufferWriter<byte>)

Encodes text with encoding and writes the bytes into writer.

public static void WriteTo(this string text, Encoding encoding, IBufferWriter<byte> writer)

Parameters

text string

The string to encode.

encoding Encoding

The encoding used to produce the bytes.

writer IBufferWriter<byte>

The buffer writer to receive the encoded bytes.

Exceptions

ArgumentNullException

Thrown when text, encoding, or writer is null.

EncoderFallbackException

Thrown when encoding uses EncoderExceptionFallback and text contains a code point that cannot be represented.

WriteUtf8To(string, IBufferWriter<byte>)

Encodes text as UTF-8 and writes the bytes into writer.

public static void WriteUtf8To(this string text, IBufferWriter<byte> writer)

Parameters

text string

The string to encode.

writer IBufferWriter<byte>

The buffer writer to receive the UTF-8 bytes.

Exceptions

ArgumentNullException

Thrown when text or writer is null.

Applies to

Product	Versions
.NET	8, 10