Class StreamExtensions

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

Inheritance

object

StreamExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

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

View Source

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.

View Source

Combine(IEnumerable<Stream>, bool)

Combines multiple readable streams.

Declaration

public static Stream Combine(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.

View Source

Combine(ReadOnlySpan<Stream>, bool)

Combines multiple readable streams.

Declaration

public static Stream Combine(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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

Create(Memory<byte>, bool)

Creates a stream wrapper over the memory block.

Declaration

public static MemorySegmentStream Create(Memory<byte> memory, bool skipOnOverflow = false)

Parameters

Type	Name	Description
Memory<byte>	memory	The memory block to wrap.
bool	skipOnOverflow	Indicates that Write(ReadOnlySpan<byte>) and WriteAsync(ReadOnlyMemory<byte>, CancellationToken) must throw IOException if the caller is trying to write past to the end of the underlying buffer.

Returns

Type	Description
MemorySegmentStream	The wrapper stream.

View Source

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.

View Source

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.

View Source

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.

View Source

EnsureReadable(Stream, string?)

Ensures that the stream is readable.

Declaration

public static void EnsureReadable(Stream stream, string? paramName = null)

Parameters

Type	Name	Description
Stream	stream	The stream to check.
string	paramName	The name of the parameter providing the stream.

Exceptions

Type	Condition
ArgumentException	CanRead is false.

View Source

EnsureWritable(Stream, string?)

Ensures that the stream is writable.

Declaration

public static void EnsureWritable(Stream stream, string? paramName = null)

Parameters

Type	Name	Description
Stream	stream	The stream to check.
string	paramName	The name of the parameter providing the stream.

Exceptions

Type	Condition
ArgumentException	CanWrite is false.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

ParseAsync<TArg, TResult>(Stream, TArg, Func<ReadOnlySpan<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, Func<ReadOnlySpan<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`.
Func<ReadOnlySpan<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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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) where TArg : allows ref struct

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.

View Source

Slice(Stream, long, long)

Creates a slice over the specified stream.

Declaration

public static StreamSegment Slice(this Stream stream, long offset, long length)

Parameters

Type	Name	Description
Stream	stream
long	offset	The offset within a stream.
long	length	The length of the segment.

Returns

Type	Description
StreamSegment	The slice over the stream.

View Source

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.

View Source

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.

View Source

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.

View Source

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.

View Source

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.