Class FileReader

Represents buffered file reader.

Inheritance

object

Disposable

FileReader

Implements

IDisposable

IAsyncBinaryReader

IAsyncEnumerable<ReadOnlyMemory<byte>>

IDynamicInterfaceCastable

Inherited Members

Disposable.CreateException()

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(params IEnumerable<IAsyncDisposable>)

Disposable.Dispose<TDisposable>(params ReadOnlySpan<TDisposable>)

Disposable.IsDisposed

Disposable.IsDisposing

Disposable.IsDisposingOrDisposed

Disposable.DisposedTask

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 class FileReader : Disposable, IDisposable, IAsyncBinaryReader, 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

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.

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

View Source

handle

Represents the file handle.

Declaration

protected readonly SafeFileHandle handle

Field Value

Type	Description
SafeFileHandle

Properties

View Source

Allocator

Gets buffer allocator.

Declaration

public MemoryAllocator<byte> Allocator { get; init; }

Property Value

Type	Description
MemoryAllocator<byte>

View Source

Buffer

Gets unconsumed part of the buffer.

Declaration

public ReadOnlyMemory<byte> Buffer { get; }

Property Value

Type	Description
ReadOnlyMemory<byte>

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.

View Source

HasBufferedData

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

Declaration

public bool HasBufferedData { get; }

Property Value

Type	Description
bool

View Source

MaxBufferSize

Gets the maximum size of the internal buffer.

Declaration

public int MaxBufferSize { get; init; }

Property Value

Type	Description
int

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.

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

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.

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.

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.

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.

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.

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)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.