Show / Hide Table of Contents

Class FileReader

Represents buffered file reader.

Inheritance
object
Disposable
FileReader
Implements
IAsyncBinaryReader
IBufferedReader
IBufferedChannel
IResettable
IDisposable
IAsyncEnumerable<ReadOnlyMemory<byte>>
IDynamicInterfaceCastable
Inherited Members
Disposable.IsDisposed
Disposable.IsDisposing
Disposable.IsDisposingOrDisposed
Disposable.CreateException()
Disposable.DisposedTask
Disposable.GetDisposedTask<T>()
Disposable.TrySetDisposedException<T>(TaskCompletionSource<T>)
Disposable.TrySetDisposedException(TaskCompletionSource)
Disposable.DisposeAsyncCore()
Disposable.DisposeAsync()
Disposable.TryBeginDispose()
Disposable.Dispose()
Disposable.Dispose(IEnumerable<IDisposable>)
Disposable.DisposeAsync(IEnumerable<IAsyncDisposable>)
Disposable.Dispose<T>(ReadOnlySpan<T>)
Disposable.DisposeAsync(params IAsyncDisposable[])
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 class FileReader : Disposable, IAsyncBinaryReader, IBufferedReader, IBufferedChannel, IResettable, IDisposable, IAsyncEnumerable<ReadOnlyMemory<byte>>, IDynamicInterfaceCastable
Remarks

This class is not thread-safe. However, it's possible to share the same file handle across multiple readers and use dedicated reader in each thread.

Constructors

| Edit this page View Source

FileReader(SafeFileHandle)

Initializes a new buffered file reader.

Declaration
public FileReader(SafeFileHandle handle)
Parameters
Type Name Description
SafeFileHandle handle

The file handle.

Exceptions
Type Condition
ArgumentNullException

handle is null.

| Edit this page View Source

FileReader(FileStream)

Initializes a new buffered file reader.

Declaration
public FileReader(FileStream source)
Parameters
Type Name Description
FileStream source

Readable file stream.

Exceptions
Type Condition
ArgumentException

source is not readable.

Fields

| Edit this page View Source

handle

Represents the file handle.

Declaration
protected readonly SafeFileHandle handle
Field Value
Type Description
SafeFileHandle

Properties

| Edit this page View Source

Allocator

Gets buffer allocator.

Declaration
public MemoryAllocator<byte>? Allocator { get; init; }
Property Value
Type Description
MemoryAllocator<byte>
| Edit this page View Source

Buffer

Gets unconsumed part of the buffer.

Declaration
public ReadOnlyMemory<byte> Buffer { get; }
Property Value
Type Description
ReadOnlyMemory<byte>
| Edit this page View Source

FilePosition

Gets or sets the cursor position within the file.

Declaration
public long FilePosition { get; set; }
Property Value
Type Description
long
Exceptions
Type Condition
ArgumentOutOfRangeException

The value is less than zero.

InvalidOperationException

There is buffered data present. Call Consume(int) or Reset() before changing the position.

| Edit this page View Source

HasBufferedData

Gets a value indicating that the read buffer is not empty.

Declaration
public bool HasBufferedData { get; }
Property Value
Type Description
bool
| Edit this page View Source

MaxBufferSize

Gets the maximum size of the internal buffer.

Declaration
public int MaxBufferSize { get; init; }
Property Value
Type Description
int
| Edit this page View Source

ReadPosition

Gets the read position within the file.

Declaration
public long ReadPosition { get; }
Property Value
Type Description
long
Remarks

The returned value may be larger than FilePosition because the reader performs buffered read.

| Edit this page View Source

ReaderSegmentLength

Limits the number of available bytes to read.

Declaration
public long? ReaderSegmentLength { set; }
Property Value
Type Description
long?

The number of available bytes to read; or null to allow read to the end of the file.

Remarks

This limit is applicable only to the methods of IAsyncBinaryReader interface implemented by this class.

Exceptions
Type Condition
ArgumentOutOfRangeException

value is negative.

Methods

| Edit this page View Source

Consume(int)

Advances read position.

Declaration
public void Consume(int count)
Parameters
Type Name Description
int count

The number of consumed bytes.

Exceptions
Type Condition
ObjectDisposedException

The reader has been disposed.

ArgumentOutOfRangeException

count is larger than the length of Buffer.

| Edit this page View Source

CopyToAsync<TConsumer>(TConsumer, long, CancellationToken)

Reads the entire content using the specified delegate.

Declaration
public ValueTask CopyToAsync<TConsumer>(TConsumer consumer, long count, 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 result.

Type Parameters
Name Description
TConsumer

The type of the consumer.

Exceptions
Type Condition
ArgumentOutOfRangeException

count is negative.

OperationCanceledException

The operation has been canceled.

EndOfStreamException

The underlying file doesn't have enough bytes to read.

| Edit this page View Source

CopyToAsync<TConsumer>(TConsumer, CancellationToken)

Reads the entire content using the specified delegate.

Declaration
public ValueTask CopyToAsync<TConsumer>(TConsumer consumer, CancellationToken token = default) where TConsumer : ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>
Parameters
Type Name Description
TConsumer consumer

The content reader.

CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask

The task representing asynchronous result.

Type Parameters
Name Description
TConsumer

The type of the consumer.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

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

Decodes the sequence of characters.

Declaration
public 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
public 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

Dispose(bool)

Releases managed and unmanaged resources associated with this object.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

true if called from Dispose(); false if called from finalizer ~Disposable().

Overrides
Disposable.Dispose(bool)
| Edit this page View Source

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

Parses the numeric value from UTF-8 encoded characters.

Declaration
public 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
public 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

Read()

Reads the data from the file to the underlying buffer.

Declaration
public bool Read()
Returns
Type Description
bool

true if the data has been copied from the file to the internal buffer; false if no more data to read.

Exceptions
Type Condition
ObjectDisposedException

The reader has been disposed.

InternalBufferOverflowException

Internal buffer has no free space.

| Edit this page View Source

Read(Span<byte>)

Reads the block of the memory.

Declaration
public int Read(Span<byte> destination)
Parameters
Type Name Description
Span<byte> destination

The output buffer.

Returns
Type Description
int

The number of bytes copied to destination.

Exceptions
Type Condition
ObjectDisposedException

The reader has been disposed.

| Edit this page View Source

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

Reads the memory block.

Declaration
public 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 the memory.

Declaration
public ValueTask<int> ReadAsync(Memory<byte> destination, CancellationToken token = default)
Parameters
Type Name Description
Memory<byte> destination

The output buffer.

CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask<int>

The number of bytes copied to destination.

Exceptions
Type Condition
ObjectDisposedException

The reader has been disposed.

OperationCanceledException

The operation has been canceled.

| Edit this page View Source

ReadAsync(CancellationToken)

Fetches the data from the underlying storage to the internal buffer.

Declaration
public ValueTask<bool> ReadAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask<bool>

true if the data has been copied from the underlying storage to the internal buffer; false if no more data to read.

Exceptions
Type Condition
ObjectDisposedException

The reader has been disposed.

InternalBufferOverflowException

Internal buffer has no free space.

OperationCanceledException

The operation has been canceled.

| Edit this page View Source

ReadAsync<T>(CancellationToken)

Decodes the value of binary formattable type.

Declaration
public 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

ReadBigEndianAsync<T>(CancellationToken)

Reads integer encoded in big-endian format.

Declaration
public 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
public 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

Reset()

Clears the read buffer.

Declaration
public void Reset()
| Edit this page View Source

Skip(long)

Skips the specified number of bytes and advances file read cursor.

Declaration
public void Skip(long count)
Parameters
Type Name Description
long count

The number of bytes to skip.

Exceptions
Type Condition
ArgumentOutOfRangeException

count is less than zero.

Implements

IAsyncBinaryReader
IBufferedReader
IBufferedChannel
IResettable
IDisposable
IAsyncEnumerable<T>
IDynamicInterfaceCastable

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)
AsyncEnumerable.CopyAsync<T>(IAsyncEnumerable<T>, int, MemoryAllocator<T>?, CancellationToken)
AsyncEnumerable.ElementAtAsync<T>(IAsyncEnumerable<T>, int, CancellationToken)
AsyncEnumerable.FirstOrNoneAsync<T>(IAsyncEnumerable<T>, Predicate<T>, CancellationToken)
AsyncEnumerable.FirstOrNoneAsync<T>(IAsyncEnumerable<T>, CancellationToken)
AsyncEnumerable.FirstOrNullAsync<T>(IAsyncEnumerable<T>, CancellationToken)
AsyncEnumerable.ForEachAsync<T>(IAsyncEnumerable<T>, Action<T>, CancellationToken)
AsyncEnumerable.ForEachAsync<T>(IAsyncEnumerable<T>, Func<T, CancellationToken, ValueTask>, CancellationToken)
AsyncEnumerable.LastOrNoneAsync<T>(IAsyncEnumerable<T>, CancellationToken)
AsyncEnumerable.LastOrNullAsync<T>(IAsyncEnumerable<T>, CancellationToken)
AsyncEnumerable.ToArrayAsync<T>(IAsyncEnumerable<T>, int, MemoryAllocator<T>?, CancellationToken)
  • Edit this page
  • View Source
☀
☾
In this article
Back to top
Supported by the .NET Foundation
☀
☾