Show / Hide Table of Contents

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)
AsyncLockAcquisition.AcquireLockAsync<T>(T, CancellationToken)
AsyncLockAcquisition.AcquireLockAsync<T>(T, TimeSpan, CancellationToken)
AsyncLockAcquisition.AcquireReadLockAsync<T>(T, CancellationToken)
AsyncLockAcquisition.AcquireReadLockAsync<T>(T, TimeSpan, CancellationToken)
AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, CancellationToken)
AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, TimeSpan, CancellationToken)
AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, CancellationToken)
AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, TimeSpan, CancellationToken)
LockAcquisition.AcquireReadLock<T>(T)
LockAcquisition.AcquireReadLock<T>(T, TimeSpan)
LockAcquisition.AcquireUpgradeableReadLock<T>(T)
LockAcquisition.AcquireUpgradeableReadLock<T>(T, TimeSpan)
LockAcquisition.AcquireWriteLock<T>(T)
LockAcquisition.AcquireWriteLock<T>(T, TimeSpan)

See Also

IAsyncBinaryWriter
  • Edit this page
  • View Source
☀
☾
In this article
Back to top
Supported by the .NET Foundation
☀
☾