Class StreamExtensions

Represents high-level read/write methods for the stream.

Inheritance

object

StreamExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: DotNext.IO

Assembly: DotNext.IO.dll

Syntax

public static class StreamExtensions

Remarks

This class provides alternative way to read and write typed data from/to the stream without instantiation of BinaryReader and BinaryWriter.

Methods

AsUnbufferedStream(SafeFileHandle, FileAccess)

Creates a stream for the specified file handle.

Declaration

public static Stream AsUnbufferedStream(this SafeFileHandle handle, FileAccess access)

Parameters

Type	Name	Description
SafeFileHandle	handle	The file handle.
FileAccess	access	Desired access to the file via stream.

Returns

Type	Description
Stream	The unbuffered file stream.

Remarks

The returned stream doesn't own the handle.

Exceptions

Type	Condition
ArgumentNullException	handle is null.
ArgumentException	handle is closed or invalid.

Combine(IEnumerable<Stream>, bool)

Combines multiple readable streams.

Declaration

public static Stream Combine(this IEnumerable<Stream> streams, bool leaveOpen = true)

Parameters

Type	Name	Description
IEnumerable<Stream>	streams	A collection of streams.
bool	leaveOpen	true to keep the wrapped streams alive when combined stream disposed; otherwise, false.

Returns

Type	Description
Stream	An object that represents multiple streams as one logical stream.

Exceptions

Type	Condition
ArgumentException	streams is empty.

Combine(Stream, ReadOnlySpan<Stream>)

Combines multiple readable streams.

Declaration

public static Stream Combine(this Stream stream, ReadOnlySpan<Stream> others)

Parameters

Type	Name	Description
Stream	stream	The stream to combine.
ReadOnlySpan<Stream>	others	A collection of streams.

Returns

Type	Description
Stream	An object that represents multiple streams as one logical stream.

Combine(ReadOnlySpan<Stream>, bool)

Combines multiple readable streams.

Declaration

public static Stream Combine(this ReadOnlySpan<Stream> streams, bool leaveOpen = true)

Parameters

Type	Name	Description
ReadOnlySpan<Stream>	streams	A collection of streams.
bool	leaveOpen	true to keep the wrapped streams alive when combined stream disposed; otherwise, false.

Returns

Type	Description
Stream	An object that represents multiple streams as one logical stream.

Exceptions

Type	Condition
ArgumentException	streams is empty.

CopyToAsync(Stream, IBufferWriter<byte>, int, CancellationToken)

Asynchronously reads the bytes from the current stream and writes them to buffer writer, using a specified cancellation token.

Declaration

public static ValueTask CopyToAsync(this Stream source, IBufferWriter<byte> destination, int bufferSize = 0, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	source	The source stream.
IBufferWriter<byte>	destination	The writer to which the contents of the current stream will be copied.
int	bufferSize	The size, in bytes, of the buffer.
CancellationToken	token	The token to monitor for cancellation requests.

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Exceptions

Type	Condition
ArgumentNullException	destination is null.
ArgumentOutOfRangeException	bufferSize is negative or zero.
NotSupportedException	source doesn't support reading.
OperationCanceledException	The operation has been canceled.

CopyToAsync(Stream, IBufferWriter<byte>, long, int, CancellationToken)

Asynchronously reads the bytes from the current stream and writes them to buffer writer, using a specified cancellation token.

Declaration

public static ValueTask CopyToAsync(this Stream source, IBufferWriter<byte> destination, long count, int bufferSize = 0, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	source	The source stream.
IBufferWriter<byte>	destination	The writer to which the contents of the current stream will be copied.
long	count	The number of bytes to copy.
int	bufferSize	The size, in bytes, of the buffer.
CancellationToken	token	The token to monitor for cancellation requests.

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Exceptions

Type	Condition
ArgumentNullException	destination is null.
ArgumentOutOfRangeException	bufferSize or count is negative.
NotSupportedException	source doesn't support reading.
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes.

CopyToAsync(Stream, Stream, long, Memory<byte>, CancellationToken)

Asynchronously reads the bytes from the source stream and writes them to another stream, using a specified buffer.

Declaration

public static ValueTask CopyToAsync(this Stream source, Stream destination, long count, Memory<byte> buffer, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	source	The source stream to read from.
Stream	destination	The destination stream to write into.
long	count	The number of bytes to copy.
Memory<byte>	buffer	The buffer used to hold copied content temporarily.
CancellationToken	token	The token that can be used to cancel this operation.

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Exceptions

Type	Condition
ArgumentOutOfRangeException	count is negative.
ArgumentException	buffer is empty.
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes.

CopyToAsync(Stream, Stream, Memory<byte>, CancellationToken)

Asynchronously reads the bytes from the source stream and writes them to another stream, using a specified buffer.

Declaration

public static ValueTask CopyToAsync(this Stream source, Stream destination, Memory<byte> buffer, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	source	The source stream to read from.
Stream	destination	The destination stream to write into.
Memory<byte>	buffer	The buffer used to hold copied content temporarily.
CancellationToken	token	The token that can be used to cancel this operation.

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Exceptions

Type	Condition
ArgumentException	buffer is empty.
OperationCanceledException	The operation has been canceled.

CopyToAsync<TConsumer>(Stream, TConsumer, long, Memory<byte>, CancellationToken)

Asynchronously reads the bytes from the source stream and passes them to the consumer, using a specified buffer.

Declaration

public static ValueTask CopyToAsync<TConsumer>(this Stream source, TConsumer consumer, long count, Memory<byte> buffer, CancellationToken token = default) where TConsumer : ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>

Parameters

Type	Name	Description
Stream	source	The source stream to read from.
TConsumer	consumer	The destination stream to write into.
long	count	The number of bytes to copy.
Memory<byte>	buffer	The buffer used to hold copied content temporarily.
CancellationToken	token	The token that can be used to cancel this operation.

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Type Parameters

Name	Description
TConsumer	The type of the consumer.

Exceptions

Type	Condition
ArgumentOutOfRangeException	count is negative.
ArgumentException	buffer is empty.
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes.

CopyToAsync<TConsumer>(Stream, TConsumer, Memory<byte>, CancellationToken)

Asynchronously reads the bytes from the source stream and passes them to the consumer, using a specified buffer.

Declaration

public static ValueTask CopyToAsync<TConsumer>(this Stream source, TConsumer consumer, Memory<byte> buffer, CancellationToken token = default) where TConsumer : ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>

Parameters

Type	Name	Description
Stream	source	The source stream to read from.
TConsumer	consumer	The destination stream to write into.
Memory<byte>	buffer	The buffer used to hold copied content temporarily.
CancellationToken	token	The token that can be used to cancel this operation.

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Type Parameters

Name	Description
TConsumer	The type of the consumer.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ArgumentException	buffer is empty.

DecodeAsync(Stream, DecodingContext, LengthFormat, Memory<byte>, MemoryAllocator<char>?, CancellationToken)

Reads a length-prefixed string asynchronously using the specified encoding and supplied reusable buffer.

Declaration

public static ValueTask<MemoryOwner<char>> DecodeAsync(this Stream stream, DecodingContext context, LengthFormat lengthFormat, Memory<byte> buffer, MemoryAllocator<char>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
DecodingContext	context	The text decoding context.
LengthFormat	lengthFormat	The format of the string length encoded in the stream.
Memory<byte>	buffer	The buffer that is allocated by the caller.
MemoryAllocator<char>	allocator	The allocator of the buffer of characters.
CancellationToken	token	The token that can be used to cancel asynchronous operation.

Returns

Type	Description
ValueTask<MemoryOwner<char>>	The buffer of characters.

Exceptions

Type	Condition
ArgumentException	buffer too small for decoding characters.
EndOfStreamException	Unexpected end of stream.
OperationCanceledException	The operation has been canceled.
ArgumentOutOfRangeException	lengthFormat is invalid.

DecodeAsync(Stream, DecodingContext, LengthFormat, Memory<char>, Memory<byte>, CancellationToken)

Decodes the sequence of characters.

Declaration

public static IAsyncEnumerable<ReadOnlyMemory<char>> DecodeAsync(this Stream stream, DecodingContext context, LengthFormat lengthFormat, Memory<char> charBuffer, Memory<byte> byteBuffer, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
DecodingContext	context	The decoding context containing string characters encoding.
LengthFormat	lengthFormat	The format of the string length encoded in the stream.
Memory<char>	charBuffer	The buffer of characters.
Memory<byte>	byteBuffer	The buffer of bytes.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
IAsyncEnumerable<ReadOnlyMemory<char>>	The enumerator of characters.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes to decode the value.
ArgumentOutOfRangeException	lengthFormat is invalid.

EncodeAsync(Stream, ReadOnlyMemory<char>, EncodingContext, LengthFormat?, Memory<byte>, CancellationToken)

Writes a length-prefixed or raw string to the stream asynchronously using supplied reusable buffer.

Declaration

public static ValueTask<long> EncodeAsync(this Stream stream, ReadOnlyMemory<char> chars, EncodingContext context, LengthFormat? lengthFormat, Memory<byte> buffer, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
ReadOnlyMemory<char>	chars	The string to be encoded.
EncodingContext	context	The encoding context.
LengthFormat?	lengthFormat	String length encoding format; or null to prevent encoding of string length.
Memory<byte>	buffer	The buffer allocated by the caller needed for characters encoding.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<long>	The task representing asynchronous state of the operation.

Remarks

This method doesn't encode the length of the string.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ArgumentException	buffer is too small for encoding minimal portion of chars.
ArgumentOutOfRangeException	lengthFormat is invalid.

FormatAsync<T>(Stream, T, EncodingContext, LengthFormat?, Memory<byte>, string?, IFormatProvider?, MemoryAllocator<char>?, CancellationToken)

Encodes formattable value as a set of characters using the specified encoding.

Declaration

public static ValueTask<long> FormatAsync<T>(this Stream stream, T value, EncodingContext context, LengthFormat? lengthFormat, Memory<byte> buffer, string? format = null, IFormatProvider? provider = null, MemoryAllocator<char>? allocator = null, CancellationToken token = default) where T : ISpanFormattable

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
T	value	The type value to be written as string.
EncodingContext	context	The context describing encoding of characters.
LengthFormat?	lengthFormat	String length encoding format; or null to prevent encoding of string length.
Memory<byte>	buffer	The buffer to be used for characters encoding.
string	format	The format of the value.
IFormatProvider	provider	The format provider.
MemoryAllocator<char>	allocator	A memory allocator for internal buffer of chars.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<long>	The number of written bytes.

Type Parameters

Name	Description
T	The type of formattable value.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ArgumentOutOfRangeException	lengthFormat is invalid.

FormatAsync<T>(Stream, T, LengthFormat?, Memory<byte>, string?, IFormatProvider?, CancellationToken)

Encodes formattable value as a set of UTf-8 encoded characters.

Declaration

public static ValueTask<int> FormatAsync<T>(this Stream stream, T value, LengthFormat? lengthFormat, Memory<byte> buffer, string? format = null, IFormatProvider? provider = null, CancellationToken token = default) where T : IUtf8SpanFormattable

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
T	value	The type value to be written as string.
LengthFormat?	lengthFormat	String length encoding format.
Memory<byte>	buffer	The buffer to be used for characters encoding.
string	format	The format of the value.
IFormatProvider	provider	The format provider.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<int>	The number of written bytes.

Type Parameters

Name	Description
T	The type of formattable value.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ArgumentOutOfRangeException	lengthFormat is invalid.

ParseAsync<T>(Stream, LengthFormat, Memory<byte>, NumberStyles, IFormatProvider?, CancellationToken)

Parses the numeric value from UTF-8 encoded characters.

Declaration

public static ValueTask<T> ParseAsync<T>(this Stream stream, LengthFormat lengthFormat, Memory<byte> buffer, NumberStyles style, IFormatProvider? provider = null, CancellationToken token = default) where T : INumberBase<T>

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
LengthFormat	lengthFormat	The format of the string length (in bytes) encoded in the stream.
Memory<byte>	buffer	The buffer that is allocated by the caller.
NumberStyles	style	A combination of number styles.
IFormatProvider	provider	Culture-specific formatting information.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<T>	The result of parsing.

Type Parameters

Name	Description
T	The numeric type.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes to decode the value.
ArgumentOutOfRangeException	lengthFormat is invalid.

ParseAsync<T>(Stream, LengthFormat, Memory<byte>, IFormatProvider?, CancellationToken)

Parses the sequence of characters encoded as UTF-8.

Declaration

public static ValueTask<T> ParseAsync<T>(this Stream stream, LengthFormat lengthFormat, Memory<byte> buffer, IFormatProvider? provider = null, CancellationToken token = default) where T : IUtf8SpanParsable<T>

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
LengthFormat	lengthFormat	The format of the string length (in bytes) encoded in the stream.
Memory<byte>	buffer	The buffer that is allocated by the caller.
IFormatProvider	provider	Culture-specific formatting information.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<T>	The result of parsing.

Type Parameters

Name	Description
T	The type that supports parsing from UTF-8.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes to decode the value.
ArgumentOutOfRangeException	lengthFormat is invalid.

ParseAsync<TArg, TResult>(Stream, TArg, ReadOnlySpanFunc<char, TArg, TResult>, DecodingContext, LengthFormat, Memory<byte>, MemoryAllocator<char>?, CancellationToken)

Parses the sequence of characters.

Declaration

public static ValueTask<TResult> ParseAsync<TArg, TResult>(this Stream stream, TArg arg, ReadOnlySpanFunc<char, TArg, TResult> parser, DecodingContext context, LengthFormat lengthFormat, Memory<byte> buffer, MemoryAllocator<char>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
TArg	arg	The argument to be passed to parser.
ReadOnlySpanFunc<char, TArg, TResult>	parser	The parser of characters.
DecodingContext	context	The decoding context containing string characters encoding.
LengthFormat	lengthFormat	The format of the string length (in bytes) encoded in the stream.
Memory<byte>	buffer	The buffer that is allocated by the caller.
MemoryAllocator<char>	allocator	The allocator of internal buffer.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<TResult>	The parsed value.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to parser.
TResult	The type of the result.

Exceptions

Type	Condition
ArgumentNullException	parser is null.
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes to decode the value.
ArgumentOutOfRangeException	lengthFormat is invalid.

ReadAllAsync(Stream, int, MemoryAllocator<byte>?, CancellationToken)

Reads the stream sequentially.

Declaration

public static IAsyncEnumerable<ReadOnlyMemory<byte>> ReadAllAsync(this Stream source, int bufferSize, MemoryAllocator<byte>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	source	Readable stream.
int	bufferSize	The buffer size.
MemoryAllocator<byte>	allocator	The allocator of the buffer.
CancellationToken	token	The token that can be used to cancel the enumeration.

Returns

Type	Description
IAsyncEnumerable<ReadOnlyMemory<byte>>	A collection of memory blocks that can be obtained sequentially to read a whole stream.

Remarks

The returned memory block should not be used between iterations.

Exceptions

Type	Condition
ArgumentOutOfRangeException	bufferSize is less than 1.
OperationCanceledException	The operation has been canceled.
NotSupportedException	source doesn't support reading.

ReadAsync<T>(Stream, Memory<byte>, CancellationToken)

Parses the value encoded as a sequence of bytes.

Declaration

public static ValueTask<T> ReadAsync<T>(this Stream stream, Memory<byte> buffer, CancellationToken token = default) where T : IBinaryFormattable<T>

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
Memory<byte>	buffer	The buffer allocated by the caller.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<T>	The parsed value.

Type Parameters

Name	Description
T	The type of the result.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes to decode the value.
ArgumentException	buffer too small for decoding value.

ReadBigEndianAsync<T>(Stream, Memory<byte>, CancellationToken)

Reads integer encoded in big-endian format.

Declaration

public static ValueTask<T> ReadBigEndianAsync<T>(this Stream stream, Memory<byte> buffer, CancellationToken token = default) where T : IBinaryInteger<T>

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
Memory<byte>	buffer	The buffer allocated by the caller.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<T>	The integer value.

Type Parameters

Name	Description
T	The integer type.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes to decode the value.

ReadBlockAsync(Stream, LengthFormat, MemoryAllocator<byte>?, CancellationToken)

Decodes the block of bytes asynchronously.

Declaration

public static ValueTask<MemoryOwner<byte>> ReadBlockAsync(this Stream stream, LengthFormat lengthFormat, MemoryAllocator<byte>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
LengthFormat	lengthFormat	The format of the block length encoded in the underlying stream.
MemoryAllocator<byte>	allocator	The memory allocator used to place the decoded block of bytes.
CancellationToken	token	The token that can be used to cancel asynchronous operation.

Returns

Type	Description
ValueTask<MemoryOwner<byte>>	The decoded block of bytes.

Exceptions

Type	Condition
EndOfStreamException	The end of the stream is reached.
OperationCanceledException	The operation has been canceled.

ReadExactlyAsync(Stream, long, int, MemoryAllocator<byte>?, CancellationToken)

Reads exactly the specified amount of bytes as a sequence of chunks.

Declaration

public static IAsyncEnumerable<ReadOnlyMemory<byte>> ReadExactlyAsync(this Stream stream, long length, int bufferSize, MemoryAllocator<byte>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
long	length	The numbers of bytes to read.
int	bufferSize	The maximum size of chunks to be returned.
MemoryAllocator<byte>	allocator	The buffer allocator.
CancellationToken	token	The token that can be used to cancel the enumeration.

Returns

Type	Description
IAsyncEnumerable<ReadOnlyMemory<byte>>	A collection of memory blocks that can be obtained sequentially to read the requested amount of bytes.

Remarks

The returned memory block should not be used between iterations.

Exceptions

Type	Condition
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes.
ArgumentOutOfRangeException	bufferSize is less than 1; or length is less than 0.
OperationCanceledException	The operation has been canceled.

ReadLittleEndianAsync<T>(Stream, Memory<byte>, CancellationToken)

Reads integer encoded in little-endian format.

Declaration

public static ValueTask<T> ReadLittleEndianAsync<T>(this Stream stream, Memory<byte> buffer, CancellationToken token = default) where T : IBinaryInteger<T>

Parameters

Type	Name	Description
Stream	stream	The stream to read from.
Memory<byte>	buffer	The buffer allocated by the caller.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<T>	The integer value.

Type Parameters

Name	Description
T	The integer type.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
EndOfStreamException	The underlying source doesn't contain necessary amount of bytes to decode the value.

ReadUtf8(Stream, Span<byte>, IBufferWriter<char>)

Decodes null-terminated UTF-8 encoded string synchronously.

Declaration

public static int ReadUtf8(this Stream stream, Span<byte> buffer, IBufferWriter<char> output)

Parameters

Type	Name	Description
Stream	stream	The stream containing encoded string.
Span<byte>	buffer	The buffer used to read from stream.
IBufferWriter<char>	output	The output buffer for decoded characters.

Returns

Type	Description
int	The number of used bytes in buffer.

Remarks

This method returns when end of stream or null char reached.

Exceptions

Type	Condition
ArgumentNullException	stream or output is null.
ArgumentException	buffer is too small to decode at least one character.

ReadUtf8Async(Stream, Memory<byte>, IBufferWriter<char>, CancellationToken)

Decodes null-terminated UTF-8 encoded string asynchronously.

Declaration

public static ValueTask<int> ReadUtf8Async(this Stream stream, Memory<byte> buffer, IBufferWriter<char> output, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream containing encoded string.
Memory<byte>	buffer	The buffer used to read from stream.
IBufferWriter<char>	output	The output buffer for decoded characters.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<int>	The number of used bytes in buffer.

Remarks

This method returns when end of stream or null char reached.

Exceptions

Type	Condition
ArgumentNullException	stream or output is null.
ArgumentException	buffer is too small to decode at least one character.
OperationCanceledException	The operation has been canceled.

ReadUtf8Async<TArg>(Stream, Memory<byte>, Memory<char>, Func<ReadOnlyMemory<char>, TArg, CancellationToken, ValueTask>, TArg, CancellationToken)

Decodes null-terminated UTF-8 encoded string asynchronously.

Declaration

public static ValueTask<int> ReadUtf8Async<TArg>(this Stream stream, Memory<byte> bytesBuf, Memory<char> charsBuf, Func<ReadOnlyMemory<char>, TArg, CancellationToken, ValueTask> action, TArg arg, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream containing encoded string.
Memory<byte>	bytesBuf	The buffer used to read from stream.
Memory<char>	charsBuf	The buffer used to place decoded characters.
Func<ReadOnlyMemory<char>, TArg, CancellationToken, ValueTask>	action	The callback to be executed for each decoded portion of char data.
TArg	arg	The argument to be passed to action.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<int>	The number of used bytes in bytesBuf.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to action.

Remarks

This method returns when end of stream or null char reached.

Exceptions

Type	Condition
ArgumentNullException	stream or action is null.
ArgumentException	bytesBuf is too small to decode at least one character; or charsBuf is empty.
OperationCanceledException	The operation has been canceled.

ReadUtf8<TArg>(Stream, Span<byte>, Span<char>, ReadOnlySpanAction<char, TArg>, TArg)

Decodes null-terminated UTF-8 encoded string synchronously.

Declaration

public static int ReadUtf8<TArg>(this Stream stream, Span<byte> bytesBuf, Span<char> charsBuf, ReadOnlySpanAction<char, TArg> action, TArg arg)

Parameters

Type	Name	Description
Stream	stream	The stream containing encoded string.
Span<byte>	bytesBuf	The buffer used to read from stream.
Span<char>	charsBuf	The buffer used to place decoded characters.
ReadOnlySpanAction<char, TArg>	action	The callback to be executed for each decoded portion of char data.
TArg	arg	The argument to be passed to action.

Returns

Type	Description
int	The number of used bytes in bytesBuf.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to action.

Remarks

This method returns when end of stream or null char reached.

Exceptions

Type	Condition
ArgumentNullException	stream or action is null.
ArgumentException	bytesBuf is too small to decode at least one character; or charsBuf is empty.

WriteAsync(Stream, ReadOnlySequence<byte>, CancellationToken)

Writes sequence of bytes to the underlying stream asynchronously.

Declaration

public static ValueTask WriteAsync(this Stream stream, ReadOnlySequence<byte> sequence, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
ReadOnlySequence<byte>	sequence	The sequence of bytes.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

WriteAsync(Stream, ReadOnlyMemory<byte>, LengthFormat, Memory<byte>, CancellationToken)

Encodes the octet string asynchronously.

Declaration

public static ValueTask WriteAsync(this Stream stream, ReadOnlyMemory<byte> value, LengthFormat lengthFormat, Memory<byte> buffer, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
ReadOnlyMemory<byte>	value	The octet string to encode.
LengthFormat	lengthFormat	The format of the octet string length that must be inserted before the payload.
Memory<byte>	buffer	The buffer for internal I/O operations.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing asynchronous state of the operation.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ArgumentException	buffer is too small for encoding minimal portion of value.
ArgumentOutOfRangeException	lengthFormat is invalid.

WriteAsync<T>(Stream, T, Memory<byte>, CancellationToken)

Encodes formattable value as a sequence of bytes.

Declaration

public static ValueTask WriteAsync<T>(this Stream stream, T value, Memory<byte> buffer, CancellationToken token = default) where T : IBinaryFormattable<T>

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
T	value	The type value to be written as string.
Memory<byte>	buffer	The buffer to be used for characters encoding.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing state of asynchronous execution.

Type Parameters

Name	Description
T	The type of formattable value.

Exceptions

Type	Condition
ArgumentException	buffer is too small to encode value.
OperationCanceledException	The operation has been canceled.

WriteBigEndianAsync<T>(Stream, T, Memory<byte>, CancellationToken)

Writes the integer to the stream in big-endian format.

Declaration

public static ValueTask WriteBigEndianAsync<T>(this Stream stream, T value, Memory<byte> buffer, CancellationToken token = default) where T : IBinaryInteger<T>

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
T	value	The value to be written in big-endian format.
Memory<byte>	buffer	The buffer to be used for characters encoding.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing state of asynchronous execution.

Type Parameters

Name	Description
T	The integer type.

Exceptions

Type	Condition
ArgumentException	buffer is too small to encode value.
OperationCanceledException	The operation has been canceled.

WriteLittleEndianAsync<T>(Stream, T, Memory<byte>, CancellationToken)

Writes the integer to the stream in little-endian format.

Declaration

public static ValueTask WriteLittleEndianAsync<T>(this Stream stream, T value, Memory<byte> buffer, CancellationToken token = default) where T : IBinaryInteger<T>

Parameters

Type	Name	Description
Stream	stream	The stream to write into.
T	value	The value to be written in little-endian format.
Memory<byte>	buffer	The buffer to be used for characters encoding.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing state of asynchronous execution.

Type Parameters

Name	Description
T	The integer type.

Exceptions

Type	Condition
ArgumentException	buffer is too small to encode value.
OperationCanceledException	The operation has been canceled.