Interface IAsyncBinaryReader

Providers a uniform way to decode the data from various sources such as streams, pipes, unmanaged memory etc.

Namespace: DotNext.IO

Assembly: DotNext.IO.dll

Syntax

public interface IAsyncBinaryReader

Properties

| Edit this page View Source

Empty

Represents empty reader.

Declaration

public static IAsyncBinaryReader Empty { get; }

Property Value

Type	Description
IAsyncBinaryReader

Methods

| Edit this page View Source

CopyToAsync(IBufferWriter<byte>, long?, CancellationToken)

Copies the content to the specified buffer.

Declaration

ValueTask CopyToAsync(IBufferWriter<byte> destination, long? count = null, CancellationToken token = default)

Parameters

Type	Name	Description
IBufferWriter<byte>	destination	The buffer writer.
long?	count	The number of bytes to copy.
CancellationToken	token	The token that can be used to cancel operation.

Returns

Type	Description
ValueTask	The task representing asynchronous result.

Exceptions

Type	Condition
ArgumentOutOfRangeException	`count` is negative.
OperationCanceledException	The operation has been canceled.

| Edit this page View Source

CopyToAsync(PipeWriter, long?, CancellationToken)

Copies the content to the specified pipe writer.

Declaration

ValueTask CopyToAsync(PipeWriter destination, long? count = null, CancellationToken token = default)

Parameters

Type	Name	Description
PipeWriter	destination	The writer.
long?	count	The number of bytes to copy.
CancellationToken	token	The token that can be used to cancel operation.

Returns

Type	Description
ValueTask	The task representing asynchronous result.

Exceptions

Type	Condition
ArgumentOutOfRangeException	`count` is negative.
OperationCanceledException	The operation has been canceled.

| Edit this page View Source

CopyToAsync(Stream, long?, CancellationToken)

Copies the content to the specified stream.

Declaration

ValueTask CopyToAsync(Stream destination, long? count = null, CancellationToken token = default)

Parameters

Type	Name	Description
Stream	destination	The output stream receiving object content.
long?	count	The number of bytes to copy.
CancellationToken	token	The token that can be used to cancel asynchronous operation.

Returns

Type	Description
ValueTask	The task representing asynchronous result.

Exceptions

Type	Condition
ArgumentOutOfRangeException	`count` is negative.
OperationCanceledException	The operation has been canceled.

| Edit this page View Source

CopyToAsync<TConsumer>(TConsumer, long?, CancellationToken)

Reads the entire content using the specified delegate.

Declaration

ValueTask CopyToAsync<TConsumer>(TConsumer consumer, long? count = null, CancellationToken token = default) where TConsumer : ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>

Parameters

Type	Name	Description
TConsumer	consumer	The content reader.
long?	count	The number of bytes to copy.
CancellationToken	token	The token that can be used to cancel the 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.
OperationCanceledException	The operation has been canceled.

| Edit this page View Source

Create(ReadOnlySequence<byte>)

Creates default implementation of binary reader over sequence of bytes.

Declaration

public static SequenceReader Create(ReadOnlySequence<byte> sequence)

Parameters

Type	Name	Description
ReadOnlySequence<byte>	sequence	The sequence of bytes.

Returns

Type	Description
SequenceReader	The binary reader for the sequence of bytes.

| Edit this page View Source

Create(PipeReader)

Creates default implementation of binary reader for the specifed pipe reader.

Declaration

public static IAsyncBinaryReader Create(PipeReader reader)

Parameters

Type	Name	Description
PipeReader	reader	The pipe reader.

Returns

Type	Description
IAsyncBinaryReader	The binary reader.

Remarks

It is recommended to use extension methods from PipeExtensions class for decoding data from the stream. This method is intended for situation when you need an object implementing IAsyncBinaryReader interface.

Exceptions

Type	Condition
ArgumentNullException	`reader` is null.

| Edit this page View Source

Create(Stream, Memory<byte>)

Creates default implementation of binary reader for the stream.

Declaration

public static IAsyncBinaryReader Create(Stream input, Memory<byte> buffer)

Parameters

Type	Name	Description
Stream	input	The stream to be wrapped into the reader.
Memory<byte>	buffer	The buffer used for decoding data from the stream.

Returns

Type	Description
IAsyncBinaryReader	The stream reader.

Remarks

It is recommended to use extension methods from StreamExtensions class for decoding data from the stream. This method is intended for situation when you need an object implementing IAsyncBinaryReader interface.

Exceptions

Type	Condition
ArgumentNullException	`input` is null.
ArgumentException	`buffer` is empty.

| Edit this page View Source

Create(ReadOnlyMemory<byte>)

Creates default implementation of binary reader over contiguous memory block.

Declaration

public static SequenceReader Create(ReadOnlyMemory<byte> memory)

Parameters

Type	Name	Description
ReadOnlyMemory<byte>	memory	The block of memory.

Returns

Type	Description
SequenceReader	The binary reader for the memory block.

| Edit this page View Source

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

Decodes the sequence of characters.

Declaration

ValueTask<MemoryOwner<char>> DecodeAsync(DecodingContext context, LengthFormat lengthFormat, MemoryAllocator<char>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
DecodingContext	context	The decoding context containing string characters encoding.
LengthFormat	lengthFormat	The format of the string length encoded in the stream.
MemoryAllocator<char>	allocator	The allocator of the buffer of characters.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<MemoryOwner<char>>	The buffer 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.

| Edit this page View Source

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

Decodes the sequence of characters.

Declaration

IAsyncEnumerable<ReadOnlyMemory<char>> DecodeAsync(DecodingContext context, LengthFormat lengthFormat, Memory<char> buffer, CancellationToken token = default)

Parameters

Type	Name	Description
DecodingContext	context	The decoding context containing string characters encoding.
LengthFormat	lengthFormat	The format of the string length encoded in the stream.
Memory<char>	buffer	The buffer of characters.
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.

| Edit this page View Source

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

Parses the numeric value from UTF-8 encoded characters.

Declaration

ValueTask<T> ParseAsync<T>(LengthFormat lengthFormat, NumberStyles style, IFormatProvider? provider = null, CancellationToken token = default) where T : INumberBase<T>

Parameters

Type	Name	Description
LengthFormat	lengthFormat	The format of the string length (in bytes) encoded in the stream.
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.

| Edit this page View Source

ParseAsync<T>(LengthFormat, IFormatProvider?, CancellationToken)

Parses the sequence of characters encoded as UTF-8.

Declaration

ValueTask<T> ParseAsync<T>(LengthFormat lengthFormat, IFormatProvider? provider = null, CancellationToken token = default) where T : IUtf8SpanParsable<T>

Parameters

Type	Name	Description
LengthFormat	lengthFormat	The format of the string length (in bytes) encoded in the stream.
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.

| Edit this page View Source

ParseAsync<T>(DecodingContext, LengthFormat, NumberStyles, IFormatProvider?, MemoryAllocator<char>?, CancellationToken)

Parses the numeric value.

Declaration

ValueTask<T> ParseAsync<T>(DecodingContext context, LengthFormat lengthFormat, NumberStyles style, IFormatProvider? provider = null, MemoryAllocator<char>? allocator = null, CancellationToken token = default) where T : INumberBase<T>

Parameters

Type	Name	Description
DecodingContext	context	The decoding context containing string characters encoding.
LengthFormat	lengthFormat	The format of the string length (in bytes) encoded in the stream.
NumberStyles	style	A combination of number styles.
IFormatProvider	provider	Culture-specific formatting information.
MemoryAllocator<char>	allocator	The allocator of internal buffer.
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.

| Edit this page View Source

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

Parses the sequence of characters.

Declaration

ValueTask<TResult> ParseAsync<TArg, TResult>(TArg arg, ReadOnlySpanFunc<char, TArg, TResult> parser, DecodingContext context, LengthFormat lengthFormat, MemoryAllocator<char>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
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.
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.

| Edit this page View Source

ReadAsync(LengthFormat, MemoryAllocator<byte>?, CancellationToken)

Reads the memory block.

Declaration

ValueTask<MemoryOwner<byte>> ReadAsync(LengthFormat lengthFormat, MemoryAllocator<byte>? allocator = null, CancellationToken token = default)

Parameters

Type	Name	Description
LengthFormat	lengthFormat	The format of the string length encoded in the stream.
MemoryAllocator<byte>	allocator	An allocator of the resulting buffer.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<MemoryOwner<byte>>	The rented buffer containing the memory block.

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.

| Edit this page View Source

ReadAsync(Memory<byte>, CancellationToken)

Reads the block of bytes.

Declaration

ValueTask ReadAsync(Memory<byte> destination, CancellationToken token = default)

Parameters

Type	Name	Description
Memory<byte>	destination	The block of memory to fill.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing state of asynchronous execution.

Exceptions

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

| Edit this page View Source

ReadAsync<T>(CancellationToken)

Decodes the value of binary formattable type.

Declaration

ValueTask<T> ReadAsync<T>(CancellationToken token = default) where T : IBinaryFormattable<T>

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<T>	The decoded 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.

| Edit this page View Source

ReadAsync<TReader>(TReader, CancellationToken)

Consumes memory block.

Declaration

ValueTask<TReader> ReadAsync<TReader>(TReader reader, CancellationToken token = default) where TReader : struct, IBufferReader

Parameters

Type	Name	Description
TReader	reader	The reader of the memory block.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<TReader>	The copy of `reader`.

Type Parameters

Name	Description
TReader	The type of the consumer.

Exceptions

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

| Edit this page View Source

ReadBigEndianAsync<T>(CancellationToken)

Reads integer encoded in big-endian format.

Declaration

ValueTask<T> ReadBigEndianAsync<T>(CancellationToken token = default) where T : IBinaryInteger<T>

Parameters

Type	Name	Description
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.

| Edit this page View Source

ReadLittleEndianAsync<T>(CancellationToken)

Reads integer encoded in little-endian format.

Declaration

ValueTask<T> ReadLittleEndianAsync<T>(CancellationToken token = default) where T : IBinaryInteger<T>

Parameters

Type	Name	Description
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.

| Edit this page View Source

SkipAsync(long, CancellationToken)

Skips the block of bytes.

Declaration

ValueTask SkipAsync(long length, CancellationToken token = default)

Parameters

Type	Name	Description
long	length	The length of the block to skip, in bytes.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing state of asynchronous execution.

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	`length` is less than zero.

| Edit this page View Source

TryGetRemainingBytesCount(out long)

Attempts to get the number of bytes available for read.

Declaration

bool TryGetRemainingBytesCount(out long count)

Parameters

Type	Name	Description
long	count	The number of bytes available for read.

Returns

Type	Description
bool	true if the method is supported; otherwise, false.

| Edit this page View Source

TryGetSequence(out ReadOnlySequence<byte>)

Attempts to get the entire content represented by this reader.

Declaration

bool TryGetSequence(out ReadOnlySequence<byte> bytes)

Parameters

Type	Name	Description
ReadOnlySequence<byte>	bytes	The content represented by this reader.

Returns

Type	Description
bool	true if the content is available synchronously; otherwise, false.

Remarks

This method can be used for efficient synchronous decoding.

Extension Methods

BasicExtensions.As<T>(T)

BasicExtensions.GetUserData<T>(T)

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, ReadOnlySpan<T>)

ExpressionBuilder.Const<T>(T)