Class FileReader

Represents buffered file reader.

Inheritance

object

Disposable

FileReader

Implements

IDisposable

IAsyncBinaryReader

IResettable

IAsyncEnumerable<ReadOnlyMemory<byte>>

IDynamicInterfaceCastable

Inherited Members

Disposable.IsDisposed

Disposable.IsDisposing

Disposable.IsDisposingOrDisposed

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(ReadOnlySpan<IDisposable>)

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, IDisposable, IAsyncBinaryReader, IResettable, 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

FileReader(SafeFileHandle, long, int, MemoryAllocator<byte>?)

Initializes a new buffered file reader.

Declaration

public FileReader(SafeFileHandle handle, long fileOffset = 0, int bufferSize = 4096, MemoryAllocator<byte>? allocator = null)

Parameters

Type	Name	Description
SafeFileHandle	handle	The file handle.
long	fileOffset	The initial offset within the file.
int	bufferSize	The buffer size.
MemoryAllocator<byte>	allocator	The buffer allocator.

Exceptions

Type	Condition
ArgumentOutOfRangeException	fileOffset is less than zero; or bufferSize is less than 16 bytes.
ArgumentNullException	handle is null.
ArgumentOutOfRangeException	fileOffset is less than zero; or bufferSize too small.

FileReader(FileStream, int, MemoryAllocator<byte>?)

Initializes a new buffered file reader.

Declaration

public FileReader(FileStream source, int bufferSize = 4096, MemoryAllocator<byte>? allocator = null)

Parameters

Type	Name	Description
FileStream	source	Readable file stream.
int	bufferSize	The buffer size.
MemoryAllocator<byte>	allocator	The buffer allocator.

Exceptions

Type	Condition
ArgumentException	source is not readable.

Fields

handle

Represents the file handle.

Declaration

protected readonly SafeFileHandle handle

Field Value

Type	Description
SafeFileHandle

Properties

Buffer

Gets unconsumed part of the buffer.

Declaration

public ReadOnlyMemory<byte> Buffer { get; }

Property Value

Type	Description
ReadOnlyMemory<byte>

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.

HasBufferedData

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

Declaration

public bool HasBufferedData { get; }

Property Value

Type	Description
bool

MaxBufferSize

Gets the maximum possible amount of data that can be placed to the buffer.

Declaration

public int MaxBufferSize { get; }

Property Value

Type	Description
int

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.

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

Consume(int)

Advances read position.

Declaration

public void Consume(int bytes)

Parameters

Type	Name	Description
int	bytes	The number of consumed bytes.

Exceptions

Type	Condition
ArgumentOutOfRangeException	bytes is larger than the length of Buffer.

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 : notnull, 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.

CopyToAsync<TConsumer>(TConsumer, CancellationToken)

Reads the entire content using the specified delegate.

Declaration

public ValueTask CopyToAsync<TConsumer>(TConsumer consumer, CancellationToken token = default) where TConsumer : notnull, 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.

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.

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.

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)

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 : notnull, 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.

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 : notnull, 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.

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.

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.

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.

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.

ReadAsync(CancellationToken)

Reads the data from the file to the underlying 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 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.
OperationCanceledException	The operation has been canceled.

ReadAsync<T>(CancellationToken)

Decodes the value of binary formattable type.

Declaration

public ValueTask<T> ReadAsync<T>(CancellationToken token = default) where T : notnull, 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.

ReadBigEndianAsync<T>(CancellationToken)

Reads integer encoded in big-endian format.

Declaration

public ValueTask<T> ReadBigEndianAsync<T>(CancellationToken token = default) where T : notnull, 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.

ReadLittleEndianAsync<T>(CancellationToken)

Reads integer encoded in little-endian format.

Declaration

public ValueTask<T> ReadLittleEndianAsync<T>(CancellationToken token = default) where T : notnull, 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.

Reset()

Clears the read buffer.

Declaration

public void Reset()

Skip(long)

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

Declaration

public void Skip(long bytes)

Parameters

Type	Name	Description
long	bytes	The number of bytes to skip.

Exceptions

Type	Condition
ArgumentOutOfRangeException	bytes is less than zero.

TryConsume(int, out ReadOnlyMemory<byte>)

Attempts to consume buffered data.

Declaration

public bool TryConsume(int bytes, out ReadOnlyMemory<byte> buffer)

Parameters

Type	Name	Description
int	bytes	The number of bytes to consume.
ReadOnlyMemory<byte>	buffer	The slice of internal buffer containing consumed bytes.

Returns

Type	Description
bool	true if the specified number of bytes is consumed successfully; otherwise, false.

Implements

IDisposable

IAsyncBinaryReader

IResettable

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)