Show / Hide Table of Contents

Class FileBufferingWriter

Represents builder of contiguous block of memory that may switch to file as its backing store.

Inheritance
object
MarshalByRefObject
Stream
FileBufferingWriter
Implements
IAsyncDisposable
IBufferWriter<byte>
IGrowableBuffer<byte>
IReadOnlySpanConsumer<byte>
ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>
IFunctional<Func<ReadOnlyMemory<byte>, CancellationToken, ValueTask>>
IDisposable
IResettable
IFlushable
IDynamicInterfaceCastable
Inherited Members
Stream.Null
Stream.Close()
Stream.CopyTo(Stream)
Stream.CopyToAsync(Stream)
Stream.CopyToAsync(Stream, int)
Stream.CopyToAsync(Stream, CancellationToken)
Stream.Dispose()
Stream.DisposeAsync()
Stream.FlushAsync()
Stream.ReadAsync(byte[], int, int)
Stream.ReadAtLeast(Span<byte>, int, bool)
Stream.ReadAtLeastAsync(Memory<byte>, int, bool, CancellationToken)
Stream.ReadExactly(byte[], int, int)
Stream.ReadExactly(Span<byte>)
Stream.ReadExactlyAsync(byte[], int, int, CancellationToken)
Stream.ReadExactlyAsync(Memory<byte>, CancellationToken)
Stream.Synchronized(Stream)
Stream.WriteAsync(byte[], int, int)
Stream.CanTimeout
Stream.ReadTimeout
Stream.WriteTimeout
MarshalByRefObject.GetLifetimeService()
MarshalByRefObject.InitializeLifetimeService()
object.Equals(object)
object.Equals(object, object)
object.GetHashCode()
object.GetType()
object.ReferenceEquals(object, object)
object.ToString()
Namespace: DotNext.IO
Assembly: DotNext.IO.dll
Syntax
public sealed class FileBufferingWriter : Stream, IAsyncDisposable, IBufferWriter<byte>, IGrowableBuffer<byte>, IReadOnlySpanConsumer<byte>, ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>, IFunctional<Func<ReadOnlyMemory<byte>, CancellationToken, ValueTask>>, IDisposable, IResettable, IFlushable, IDynamicInterfaceCastable
Remarks

This class can be used to write buffered content to a target Stream or IBufferWriter<T>. Additionally, it's possible to get buffered content as Memory<T>. If memory threshold was not reached then returned Memory<T> instance references bytes in memory. Otherwise, it references memory-mapped file.

Constructors

| Edit this page View Source

FileBufferingWriter(MemoryAllocator<byte>?, int, int, string?, bool)

Initializes a new writer.

Declaration
public FileBufferingWriter(MemoryAllocator<byte>? allocator = null, int memoryThreshold = 32768, int initialCapacity = 0, string? tempDir = null, bool asyncIO = true)
Parameters
Type Name Description
MemoryAllocator<byte> allocator

The allocator of internal buffer.

int memoryThreshold

The maximum amount of memory in bytes to allocate before switching to a file on disk.

int initialCapacity

Initial capacity of internal buffer. Should not be greater than memoryThreshold.

string tempDir

The location of the directory to write buffered contents to. When unspecified, uses the value specified by the environment variable ASPNETCORE_TEMP if available, otherwise uses the value returned by GetTempPath().

bool asyncIO

true if you will use asynchronous methods of the instance; otherwise, false.

Exceptions
Type Condition
ArgumentOutOfRangeException

memoryThreshold is less than or equal to zero; or initialCapacity is less than zero or greater than memoryThreshold.

DirectoryNotFoundException

tempDir doesn't exist.

| Edit this page View Source

FileBufferingWriter(in Options)

Initializes a new writer.

Declaration
public FileBufferingWriter(in FileBufferingWriter.Options options)
Parameters
Type Name Description
FileBufferingWriter.Options options

Buffer writer options.

Exceptions
Type Condition
DirectoryNotFoundException

Temporary directory for the backing file doesn't exist.

Properties

| Edit this page View Source

CanRead

When overridden in a derived class, gets a value indicating whether the current stream supports reading.

Declaration
public override bool CanRead { get; }
Property Value
Type Description
bool

true if the stream supports reading; otherwise, false.

Overrides
Stream.CanRead
| Edit this page View Source

CanSeek

When overridden in a derived class, gets a value indicating whether the current stream supports seeking.

Declaration
public override bool CanSeek { get; }
Property Value
Type Description
bool

true if the stream supports seeking; otherwise, false.

Overrides
Stream.CanSeek
| Edit this page View Source

CanWrite

When overridden in a derived class, gets a value indicating whether the current stream supports writing.

Declaration
public override bool CanWrite { get; }
Property Value
Type Description
bool

true if the stream supports writing; otherwise, false.

Overrides
Stream.CanWrite
| Edit this page View Source

Length

When overridden in a derived class, gets the length in bytes of the stream.

Declaration
public override long Length { get; }
Property Value
Type Description
long

A long value representing the length of the stream in bytes.

Overrides
Stream.Length
Exceptions
Type Condition
NotSupportedException

A class derived from Stream does not support seeking and the length is unknown.

ObjectDisposedException

Methods were called after the stream was closed.

| Edit this page View Source

Position

When overridden in a derived class, gets or sets the position within the current stream.

Declaration
public override long Position { get; set; }
Property Value
Type Description
long

The current position within the stream.

Overrides
Stream.Position
Exceptions
Type Condition
IOException

An I/O error occurs.

NotSupportedException

The stream does not support seeking.

ObjectDisposedException

Methods were called after the stream was closed.

Methods

| Edit this page View Source

Advance(int)

Notifies the IBufferWriter<T> that count data items were written to the output Span<T> or Memory<T>.

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

The number of data items written to the Span<T> or Memory<T>.

| Edit this page View Source

BeginRead(byte[], int, int, AsyncCallback?, object?)

Begins an asynchronous read operation. (Consider using ReadAsync(byte[], int, int) instead.)

Declaration
public override IAsyncResult BeginRead(byte[] data, int offset, int count, AsyncCallback? callback, object? state)
Parameters
Type Name Description
byte[] data
int offset

The byte offset in buffer at which to begin writing data read from the stream.

int count

The maximum number of bytes to read.

AsyncCallback callback

An optional asynchronous callback, to be called when the read is complete.

object state

A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns
Type Description
IAsyncResult

An IAsyncResult that represents the asynchronous read, which could still be pending.

Overrides
Stream.BeginRead(byte[], int, int, AsyncCallback, object)
Exceptions
Type Condition
IOException

Attempted an asynchronous read past the end of the stream, or a disk error occurs.

ArgumentException

One or more of the arguments is invalid.

ObjectDisposedException

Methods were called after the stream was closed.

NotSupportedException

The current Stream implementation does not support the read operation.

| Edit this page View Source

BeginWrite(byte[], int, int, AsyncCallback?, object?)

Begins an asynchronous write operation. (Consider using WriteAsync(byte[], int, int) instead.)

Declaration
public override IAsyncResult BeginWrite(byte[] data, int offset, int count, AsyncCallback? callback, object? state)
Parameters
Type Name Description
byte[] data
int offset

The byte offset in buffer from which to begin writing.

int count

The maximum number of bytes to write.

AsyncCallback callback

An optional asynchronous callback, to be called when the write is complete.

object state

A user-provided object that distinguishes this particular asynchronous write request from other requests.

Returns
Type Description
IAsyncResult

An IAsyncResult that represents the asynchronous write, which could still be pending.

Overrides
Stream.BeginWrite(byte[], int, int, AsyncCallback, object)
Exceptions
Type Condition
IOException

Attempted an asynchronous write past the end of the stream, or a disk error occurs.

ArgumentException

One or more of the arguments is invalid.

ObjectDisposedException

Methods were called after the stream was closed.

NotSupportedException

The current Stream implementation does not support the write operation.

| Edit this page View Source

Clear(bool)

Removes all written data.

Declaration
public void Clear(bool reuseBuffer = true)
Parameters
Type Name Description
bool reuseBuffer

true to keep internal buffer alive; otherwise, false.

Exceptions
Type Condition
InvalidOperationException

Attempt to cleanup this writer while reading.

| Edit this page View Source

CopyTo(IBufferWriter<byte>, int, CancellationToken)

Drains buffered content to the buffer synchronously.

Declaration
public void CopyTo(IBufferWriter<byte> destination, int bufferSize = 1024, CancellationToken token = default)
Parameters
Type Name Description
IBufferWriter<byte> destination

The buffer to drain buffered contents to.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

CancellationToken token

The token to monitor for cancellation requests.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

CopyTo(Stream, int)

Drains buffered content to the stream synchronously.

Declaration
public override void CopyTo(Stream destination, int bufferSize)
Parameters
Type Name Description
Stream destination

The stream to drain buffered contents to.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

Overrides
Stream.CopyTo(Stream, int)
| Edit this page View Source

CopyTo(Span<byte>)

Drains buffered content to the memory block synchronously.

Declaration
public int CopyTo(Span<byte> output)
Parameters
Type Name Description
Span<byte> output

The memory block used as a destination for copy operation.

Returns
Type Description
int

The actual number of copied elements.

| Edit this page View Source

CopyToAsync(IBufferWriter<byte>, int, CancellationToken)

Drains buffered content to the buffer asynchronously.

Declaration
public Task CopyToAsync(IBufferWriter<byte> destination, int bufferSize = 1024, CancellationToken token = default)
Parameters
Type Name Description
IBufferWriter<byte> destination

The buffer to drain buffered contents to.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

CancellationToken token

The token to monitor for cancellation requests.

Returns
Type Description
Task

The task representing asynchronous execution of this method.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

CopyToAsync(Stream, int, CancellationToken)

Drains buffered content to the stream asynchronously.

Declaration
public override Task CopyToAsync(Stream destination, int bufferSize, CancellationToken token)
Parameters
Type Name Description
Stream destination

The stream to drain buffered contents to.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

CancellationToken token

The token to monitor for cancellation requests.

Returns
Type Description
Task

A task that represents the asynchronous copy operation.

Overrides
Stream.CopyToAsync(Stream, int, CancellationToken)
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

CopyToAsync(Memory<byte>, CancellationToken)

Drains buffered content to the memory block asynchronously.

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

The memory block used as a destination for copy operation.

CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask<int>

The actual number of copied elements.

| Edit this page View Source

CopyToAsync<TArg>(ReadOnlySpanAction<byte, TArg>, TArg, int, CancellationToken)

Drains buffered content asynchronously.

Declaration
public Task CopyToAsync<TArg>(ReadOnlySpanAction<byte, TArg> reader, TArg arg, int bufferSize = 1024, CancellationToken token = default)
Parameters
Type Name Description
ReadOnlySpanAction<byte, TArg> reader

The content reader.

TArg arg

The argument to be passed to the callback.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
Task

The task representing asynchronous execution of the operation.

Type Parameters
Name Description
TArg

The type of the argument to be passed to the callback.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

CopyToAsync<TConsumer>(TConsumer, int, CancellationToken)

Drains the written content to the consumer asynchronously.

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

The consumer of the written content.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
Task

The task representing asynchronous execution of this method.

Type Parameters
Name Description
TConsumer

The type of the consumer.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

CopyTo<TArg>(ReadOnlySpanAction<byte, TArg>, TArg, int, CancellationToken)

Drains buffered content synchronously.

Declaration
public void CopyTo<TArg>(ReadOnlySpanAction<byte, TArg> reader, TArg arg, int bufferSize = 1024, CancellationToken token = default)
Parameters
Type Name Description
ReadOnlySpanAction<byte, TArg> reader

The content reader.

TArg arg

The argument to be passed to the callback.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

CancellationToken token

The token that can be used to cancel the operation.

Type Parameters
Name Description
TArg

The type of the argument to be passed to the callback.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

CopyTo<TConsumer>(TConsumer, int, CancellationToken)

Drains the written content to the consumer synchronously.

Declaration
public void CopyTo<TConsumer>(TConsumer consumer, int bufferSize, CancellationToken token) where TConsumer : IReadOnlySpanConsumer<byte>
Parameters
Type Name Description
TConsumer consumer

The consumer of the written content.

int bufferSize

The size, in bytes, of the buffer used to copy bytes.

CancellationToken token

The token that can be used to cancel the operation.

Type Parameters
Name Description
TConsumer

The type of the consumer.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

Dispose(bool)

Releases the unmanaged resources used by the Stream and optionally releases the managed resources.

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

true to release both managed and unmanaged resources; false to release only unmanaged resources.

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

EndRead(IAsyncResult)

Waits for the pending asynchronous read to complete. (Consider using ReadAsync(byte[], int, int) instead.)

Declaration
public override int EndRead(IAsyncResult asyncResult)
Parameters
Type Name Description
IAsyncResult asyncResult

The reference to the pending asynchronous request to finish.

Returns
Type Description
int

The number of bytes read from the stream, between zero (0) and the number of bytes requested. ReadAsync returns zero (0) only if zero bytes were requested or if no more bytes will be available because it's at the end of the stream; otherwise, read operations do not complete until at least one byte is available. If zero bytes are requested, read operations may complete immediately or may not complete until at least one byte is available (but without consuming any data).

Overrides
Stream.EndRead(IAsyncResult)
Exceptions
Type Condition
ArgumentNullException

asyncResult is null.

ArgumentException

A handle to the pending read operation is not available.

-or-

The pending operation does not support reading.

InvalidOperationException

asyncResult did not originate from a BeginRead(byte[], int, int, AsyncCallback, object) method on the current stream.

IOException

The stream is closed or an internal error has occurred.

| Edit this page View Source

EndWrite(IAsyncResult)

Ends an asynchronous write operation. (Consider using WriteAsync(byte[], int, int) instead.)

Declaration
public override void EndWrite(IAsyncResult ar)
Parameters
Type Name Description
IAsyncResult ar
Overrides
Stream.EndWrite(IAsyncResult)
Exceptions
Type Condition
ArgumentNullException

asyncResult is null.

ArgumentException

A handle to the pending write operation is not available.

-or-

The pending operation does not support writing.

InvalidOperationException

asyncResult did not originate from a BeginWrite(byte[], int, int, AsyncCallback, object) method on the current stream.

IOException

The stream is closed or an internal error has occurred.

| Edit this page View Source

Flush()

When overridden in a derived class, clears all buffers for this stream and causes any buffered data to be written to the underlying device.

Declaration
public override void Flush()
Overrides
Stream.Flush()
Exceptions
Type Condition
IOException

An I/O error occurs.

| Edit this page View Source

Flush(bool)

Flushes the internal buffer with the file and optionally synchronize a file's in-core state with storage device.

Declaration
public void Flush(bool flushToDisk)
Parameters
Type Name Description
bool flushToDisk

true to synchronize a file's in-core state with storage device; otherwise, false.

| Edit this page View Source

FlushAsync(bool, CancellationToken)

Flushes the internal buffer with the file and optionally synchronize a file's in-core state with storage device.

Declaration
public ValueTask FlushAsync(bool flushToDisk, CancellationToken token = default)
Parameters
Type Name Description
bool flushToDisk

true to synchronize a file's in-core state with storage device; otherwise, false.

CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask

The asynchronous result of the operation.

Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

| Edit this page View Source

FlushAsync(CancellationToken)

Asynchronously clears all buffers for this stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests.

Declaration
public override Task FlushAsync(CancellationToken token)
Parameters
Type Name Description
CancellationToken token
Returns
Type Description
Task

A task that represents the asynchronous flush operation.

Overrides
Stream.FlushAsync(CancellationToken)
Exceptions
Type Condition
ObjectDisposedException

The stream has been disposed.

| Edit this page View Source

GetMemory(int)

Returns a Memory<T> to write to that is at least the requested size (specified by sizeHint).

Declaration
public Memory<byte> GetMemory(int sizeHint = 0)
Parameters
Type Name Description
int sizeHint

The minimum length of the returned Memory<T>. If 0, a non-empty buffer is returned.

Returns
Type Description
Memory<byte>

A Memory<T> of at least the size sizeHint. If sizeHint is 0, returns a non-empty buffer.

Exceptions
Type Condition
OutOfMemoryException

The requested buffer size is not available.

| Edit this page View Source

GetSpan(int)

Returns a Span<T> to write to that is at least the requested size (specified by sizeHint).

Declaration
public Span<byte> GetSpan(int sizeHint = 0)
Parameters
Type Name Description
int sizeHint

The minimum length of the returned Span<T>. If 0, a non-empty buffer is returned.

Returns
Type Description
Span<byte>

A Span<T> of at least the size sizeHint. If sizeHint is 0, returns a non-empty buffer.

| Edit this page View Source

GetWrittenContent()

Returns the whole buffered content as a source of Memory<T> instances synchronously.

Declaration
public IMemoryOwner<byte> GetWrittenContent()
Returns
Type Description
IMemoryOwner<byte>

The memory manager providing access to buffered content.

Remarks

Use GetWrittenContent(Range) if buffered content is too large.

Exceptions
Type Condition
InvalidOperationException

The memory manager is already obtained but not disposed.

OutOfMemoryException

The size of buffered content is too large and cannot be represented by Memory<T> instance.

| Edit this page View Source

GetWrittenContent(int)

Gets written content in the form of ReadOnlySequence<T> synchronously.

Declaration
public IReadOnlySequenceSource<byte> GetWrittenContent(int segmentSize)
Parameters
Type Name Description
int segmentSize

The size of the contiguous segment of file to be mapped to memory.

Returns
Type Description
IReadOnlySequenceSource<byte>

The factory of ReadOnlySequence<T> instances.

Exceptions
Type Condition
ArgumentOutOfRangeException

segmentSize is less than or equal to zero.

InvalidOperationException

The memory manager is already obtained but not disposed.

| Edit this page View Source

GetWrittenContent(Range)

Returns buffered content as a source of Memory<T> instances synchronously.

Declaration
public IMemoryOwner<byte> GetWrittenContent(Range range)
Parameters
Type Name Description
Range range

The range of buffered content to return.

Returns
Type Description
IMemoryOwner<byte>

The memory manager providing access to buffered content.

Exceptions
Type Condition
InvalidOperationException

The memory manager is already obtained but not disposed.

ArgumentOutOfRangeException

range is invalid.

OutOfMemoryException

The size of buffered content is too large and cannot be represented by Memory<T> instance.

| Edit this page View Source

GetWrittenContentAsStream()

Gets written content as read-only stream.

Declaration
public Stream GetWrittenContentAsStream()
Returns
Type Description
Stream

Read-only stream representing the written content.

Exceptions
Type Condition
InvalidOperationException

The stream is already obtained but not disposed.

| Edit this page View Source

GetWrittenContentAsStreamAsync(CancellationToken)

Gets written content as read-only stream asynchronously.

Declaration
public ValueTask<Stream> GetWrittenContentAsStreamAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask<Stream>

Read-only stream representing the written content.

Exceptions
Type Condition
InvalidOperationException

The stream is already obtained but not disposed.

OperationCanceledException

The operation has been canceled.

| Edit this page View Source

GetWrittenContentAsync(Range, CancellationToken)

Returns buffered content as a source of Memory<T> instances asynchronously.

Declaration
public ValueTask<IMemoryOwner<byte>> GetWrittenContentAsync(Range range, CancellationToken token = default)
Parameters
Type Name Description
Range range

The range of buffered content to return.

CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask<IMemoryOwner<byte>>

The memory manager providing access to buffered content.

Exceptions
Type Condition
InvalidOperationException

The memory manager is already obtained but not disposed.

OperationCanceledException

The operation has been canceled.

ArgumentOutOfRangeException

range is invalid.

OutOfMemoryException

The size of buffered content is too large and cannot be represented by Memory<T> instance.

| Edit this page View Source

GetWrittenContentAsync(CancellationToken)

Returns the whole buffered content as a source of Memory<T> instances asynchronously.

Declaration
public ValueTask<IMemoryOwner<byte>> GetWrittenContentAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.

Returns
Type Description
ValueTask<IMemoryOwner<byte>>

The memory manager providing access to buffered content.

Remarks

Use GetWrittenContentAsync(Range, CancellationToken) if buffered content is too large.

Exceptions
Type Condition
InvalidOperationException

The memory manager is already obtained but not disposed.

OperationCanceledException

The operation has been canceled.

OutOfMemoryException

The size of buffered content is too large and cannot be represented by Memory<T> instance.

| Edit this page View Source

Read(byte[], int, int)

When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Declaration
public override int Read(byte[] data, int offset, int count)
Parameters
Type Name Description
byte[] data
int offset

The zero-based byte offset in buffer at which to begin storing the data read from the current stream.

int count

The maximum number of bytes to be read from the current stream.

Returns
Type Description
int

The total number of bytes read into the buffer. This can be less than the number of bytes requested if that many bytes are not currently available, or zero (0) if count is 0 or the end of the stream has been reached.

Overrides
Stream.Read(byte[], int, int)
Exceptions
Type Condition
ArgumentException

The sum of offset and count is larger than the buffer length.

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

offset or count is negative.

IOException

An I/O error occurs.

NotSupportedException

The stream does not support reading.

ObjectDisposedException

Methods were called after the stream was closed.

| Edit this page View Source

Read(Span<byte>)

When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Declaration
public override int Read(Span<byte> data)
Parameters
Type Name Description
Span<byte> data
Returns
Type Description
int

The total number of bytes read into the buffer. This can be less than the size of the buffer if that many bytes are not currently available, or zero (0) if the buffer's length is zero or the end of the stream has been reached.

Overrides
Stream.Read(Span<byte>)
| Edit this page View Source

ReadAsync(byte[], int, int, CancellationToken)

Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.

Declaration
public override Task<int> ReadAsync(byte[] data, int offset, int count, CancellationToken token)
Parameters
Type Name Description
byte[] data
int offset

The byte offset in buffer at which to begin writing data from the stream.

int count

The maximum number of bytes to read.

CancellationToken token
Returns
Type Description
Task<int>

A task that represents the asynchronous read operation. The value of the TResult parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if count is 0 or if the end of the stream has been reached.

Overrides
Stream.ReadAsync(byte[], int, int, CancellationToken)
Exceptions
Type Condition
ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

offset or count is negative.

ArgumentException

The sum of offset and count is larger than the buffer length.

NotSupportedException

The stream does not support reading.

ObjectDisposedException

The stream has been disposed.

InvalidOperationException

The stream is currently in use by a previous read operation.

| Edit this page View Source

ReadAsync(Memory<byte>, CancellationToken)

Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.

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

A task that represents the asynchronous read operation. The value of its Result property contains the total number of bytes read into the buffer. The result value can be less than the length of the buffer if that many bytes are not currently available, or it can be 0 (zero) if the length of the buffer is 0 or if the end of the stream has been reached.

Overrides
Stream.ReadAsync(Memory<byte>, CancellationToken)
| Edit this page View Source

ReadByte()

Reads a byte from the stream and advances the position within the stream by one byte, or returns -1 if at the end of the stream.

Declaration
public override int ReadByte()
Returns
Type Description
int

The unsigned byte cast to an int, or -1 if at the end of the stream.

Overrides
Stream.ReadByte()
Exceptions
Type Condition
NotSupportedException

The stream does not support reading.

ObjectDisposedException

Methods were called after the stream was closed.

| Edit this page View Source

Seek(long, SeekOrigin)

When overridden in a derived class, sets the position within the current stream.

Declaration
public override long Seek(long offset, SeekOrigin origin)
Parameters
Type Name Description
long offset

A byte offset relative to the origin parameter.

SeekOrigin origin

A value of type SeekOrigin indicating the reference point used to obtain the new position.

Returns
Type Description
long

The new position within the current stream.

Overrides
Stream.Seek(long, SeekOrigin)
Exceptions
Type Condition
IOException

An I/O error occurs.

NotSupportedException

The stream does not support seeking, such as if the stream is constructed from a pipe or console output.

ObjectDisposedException

Methods were called after the stream was closed.

| Edit this page View Source

SetLength(long)

When overridden in a derived class, sets the length of the current stream.

Declaration
public override void SetLength(long value)
Parameters
Type Name Description
long value

The desired length of the current stream in bytes.

Overrides
Stream.SetLength(long)
Exceptions
Type Condition
IOException

An I/O error occurs.

NotSupportedException

The stream does not support both writing and seeking, such as if the stream is constructed from a pipe or console output.

ObjectDisposedException

Methods were called after the stream was closed.

| Edit this page View Source

TryGetWrittenContent(out ReadOnlyMemory<byte>)

Attempts to get written content if it is located in memory.

Declaration
public bool TryGetWrittenContent(out ReadOnlyMemory<byte> content)
Parameters
Type Name Description
ReadOnlyMemory<byte> content

The written content.

Returns
Type Description
bool

true if whole content is in memory and available without allocation of MemoryManager<T>; otherwise, false.

Remarks

If this method returns false then use GetWrittenContent(), GetWrittenContent(Range), GetWrittenContentAsync(CancellationToken) or GetWrittenContentAsync(Range, CancellationToken) to obtain the content.

| Edit this page View Source

TryGetWrittenContent(out ReadOnlyMemory<byte>, out string?)

Attempts to get written content if it is located in memory.

Declaration
public bool TryGetWrittenContent(out ReadOnlyMemory<byte> content, out string? fileName)
Parameters
Type Name Description
ReadOnlyMemory<byte> content

The written content.

string fileName

The path to the file used as a buffer if this writer switched to the file.

Returns
Type Description
bool

true if whole content is in memory and available without allocation of MemoryManager<T>; otherwise, false.

Remarks

If this method returns false then fileName contains full path to the file containing the written content. This method is useful only if the file was not created as temporary file.

| Edit this page View Source

Write(byte[], int, int)

When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.

Declaration
public override void Write(byte[] data, int offset, int count)
Parameters
Type Name Description
byte[] data
int offset

The zero-based byte offset in buffer at which to begin copying bytes to the current stream.

int count

The number of bytes to be written to the current stream.

Overrides
Stream.Write(byte[], int, int)
Exceptions
Type Condition
ArgumentException

The sum of offset and count is greater than the buffer length.

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

offset or count is negative.

IOException

An I/O error occurred, such as the specified file cannot be found.

NotSupportedException

The stream does not support writing.

ObjectDisposedException

Write(byte[], int, int) was called after the stream was closed.

| Edit this page View Source

Write(ReadOnlySpan<byte>)

When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.

Declaration
public override void Write(ReadOnlySpan<byte> input)
Parameters
Type Name Description
ReadOnlySpan<byte> input
Overrides
Stream.Write(ReadOnlySpan<byte>)
| Edit this page View Source

WriteAsync(byte[], int, int, CancellationToken)

Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.

Declaration
public override Task WriteAsync(byte[] data, int offset, int count, CancellationToken token)
Parameters
Type Name Description
byte[] data
int offset

The zero-based byte offset in buffer from which to begin copying bytes to the stream.

int count

The maximum number of bytes to write.

CancellationToken token
Returns
Type Description
Task

A task that represents the asynchronous write operation.

Overrides
Stream.WriteAsync(byte[], int, int, CancellationToken)
Exceptions
Type Condition
ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

offset or count is negative.

ArgumentException

The sum of offset and count is larger than the buffer length.

NotSupportedException

The stream does not support writing.

ObjectDisposedException

The stream has been disposed.

InvalidOperationException

The stream is currently in use by a previous write operation.

| Edit this page View Source

WriteAsync(ReadOnlyMemory<byte>, CancellationToken)

Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.

Declaration
public override ValueTask WriteAsync(ReadOnlyMemory<byte> input, CancellationToken token = default)
Parameters
Type Name Description
ReadOnlyMemory<byte> input
CancellationToken token
Returns
Type Description
ValueTask

A task that represents the asynchronous write operation.

Overrides
Stream.WriteAsync(ReadOnlyMemory<byte>, CancellationToken)
| Edit this page View Source

WriteByte(byte)

Writes a byte to the current position in the stream and advances the position within the stream by one byte.

Declaration
public override void WriteByte(byte value)
Parameters
Type Name Description
byte value

The byte to write to the stream.

Overrides
Stream.WriteByte(byte)
Exceptions
Type Condition
IOException

An I/O error occurs.

NotSupportedException

The stream does not support writing, or the stream is already closed.

ObjectDisposedException

Methods were called after the stream was closed.

Implements

IAsyncDisposable
IBufferWriter<T>
IGrowableBuffer<T>
IReadOnlySpanConsumer<T>
ISupplier<T1, T2, TResult>
IFunctional<TDelegate>
IDisposable
IResettable
IFlushable
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>)
StreamSource.AsStream<TWriter>(TWriter, Action<TWriter>?, Func<TWriter, CancellationToken, Task>?)
TextStreamExtensions.AsTextWriter<TWriter>(TWriter, Encoding, IFormatProvider?, Action<TWriter>?, Func<TWriter, CancellationToken, Task>?)
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)
BufferWriter.Encode(IBufferWriter<byte>, ReadOnlySpan<char>, in EncodingContext, LengthFormat?)
BufferWriter.Format<T>(IBufferWriter<byte>, T, in EncodingContext, LengthFormat?, ReadOnlySpan<char>, IFormatProvider?, MemoryAllocator<char>?)
BufferWriter.Format<T>(IBufferWriter<byte>, T, LengthFormat?, ReadOnlySpan<char>, IFormatProvider?)
BufferWriter.Interpolate(IBufferWriter<byte>, in EncodingContext, Span<char>, in EncodingInterpolatedStringHandler)
BufferWriter.Interpolate(IBufferWriter<byte>, in EncodingContext, Span<char>, IFormatProvider?, in EncodingInterpolatedStringHandler)
BufferWriter.Write<T>(IBufferWriter<T>, in ReadOnlySequence<T>)
ByteBuffer.Format<T>(IBufferWriter<byte>, T, ReadOnlySpan<char>, IFormatProvider?)
ByteBuffer.Write(IBufferWriter<byte>, in BigInteger, bool, bool)
ByteBuffer.WriteBigEndian<T>(IBufferWriter<byte>, T)
ByteBuffer.WriteLittleEndian<T>(IBufferWriter<byte>, T)
ByteBuffer.Write<T>(IBufferWriter<byte>, T)
StreamExtensions.Combine(Stream, ReadOnlySpan<Stream>)
StreamExtensions.CopyToAsync(Stream, IBufferWriter<byte>, int, CancellationToken)
StreamExtensions.CopyToAsync(Stream, IBufferWriter<byte>, long, int, CancellationToken)
StreamExtensions.CopyToAsync(Stream, Stream, long, Memory<byte>, CancellationToken)
StreamExtensions.CopyToAsync(Stream, Stream, Memory<byte>, CancellationToken)
StreamExtensions.CopyToAsync<TConsumer>(Stream, TConsumer, long, Memory<byte>, CancellationToken)
StreamExtensions.CopyToAsync<TConsumer>(Stream, TConsumer, Memory<byte>, CancellationToken)
StreamExtensions.DecodeAsync(Stream, DecodingContext, LengthFormat, Memory<byte>, MemoryAllocator<char>?, CancellationToken)
StreamExtensions.DecodeAsync(Stream, DecodingContext, LengthFormat, Memory<char>, Memory<byte>, CancellationToken)
StreamExtensions.EncodeAsync(Stream, ReadOnlyMemory<char>, EncodingContext, LengthFormat?, Memory<byte>, CancellationToken)
StreamExtensions.FormatAsync<T>(Stream, T, EncodingContext, LengthFormat?, Memory<byte>, string?, IFormatProvider?, MemoryAllocator<char>?, CancellationToken)
StreamExtensions.FormatAsync<T>(Stream, T, LengthFormat?, Memory<byte>, string?, IFormatProvider?, CancellationToken)
StreamExtensions.ParseAsync<T>(Stream, LengthFormat, Memory<byte>, NumberStyles, IFormatProvider?, CancellationToken)
StreamExtensions.ParseAsync<T>(Stream, LengthFormat, Memory<byte>, IFormatProvider?, CancellationToken)
StreamExtensions.ParseAsync<TArg, TResult>(Stream, TArg, ReadOnlySpanFunc<char, TArg, TResult>, DecodingContext, LengthFormat, Memory<byte>, MemoryAllocator<char>?, CancellationToken)
StreamExtensions.ReadAllAsync(Stream, int, MemoryAllocator<byte>?, CancellationToken)
StreamExtensions.ReadAsync<T>(Stream, Memory<byte>, CancellationToken)
StreamExtensions.ReadBigEndianAsync<T>(Stream, Memory<byte>, CancellationToken)
StreamExtensions.ReadBlockAsync(Stream, LengthFormat, MemoryAllocator<byte>?, CancellationToken)
StreamExtensions.ReadExactlyAsync(Stream, long, int, MemoryAllocator<byte>?, CancellationToken)
StreamExtensions.ReadLittleEndianAsync<T>(Stream, Memory<byte>, CancellationToken)
StreamExtensions.ReadUtf8(Stream, Span<byte>, IBufferWriter<char>)
StreamExtensions.ReadUtf8Async(Stream, Memory<byte>, IBufferWriter<char>, CancellationToken)
StreamExtensions.ReadUtf8Async<TArg>(Stream, Memory<byte>, Memory<char>, Func<ReadOnlyMemory<char>, TArg, CancellationToken, ValueTask>, TArg, CancellationToken)
StreamExtensions.ReadUtf8<TArg>(Stream, Span<byte>, Span<char>, ReadOnlySpanAction<char, TArg>, TArg)
StreamExtensions.WriteAsync(Stream, ReadOnlySequence<byte>, CancellationToken)
StreamExtensions.WriteAsync(Stream, ReadOnlyMemory<byte>, LengthFormat, Memory<byte>, CancellationToken)
StreamExtensions.WriteAsync<T>(Stream, T, Memory<byte>, CancellationToken)
StreamExtensions.WriteBigEndianAsync<T>(Stream, T, Memory<byte>, CancellationToken)
StreamExtensions.WriteLittleEndianAsync<T>(Stream, T, Memory<byte>, CancellationToken)
  • Edit this page
  • View Source
☀
☾
In this article
Back to top
Supported by the .NET Foundation
☀
☾