Class FileWriter

Represents buffered file writer.

Inheritance
object
Disposable
FileWriter
Implements
Inherited Members
Namespace: DotNext.IO
Assembly: DotNext.IO.dll
Syntax
public class FileWriter : Disposable, IAsyncBinaryWriter, ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>, IFunctional<Func<ReadOnlyMemory<byte>, CancellationToken, ValueTask>>, IFlushable, IBufferedWriter, IBufferedChannel, IResettable, IDisposable, IBufferWriter<byte>, IDynamicInterfaceCastable
Remarks

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

Constructors

| Edit this page View Source

FileWriter(SafeFileHandle)

Creates a new writer backed by the file.

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

The file handle.
Exceptions
Type Condition
ArgumentNullException

handle is null.
| Edit this page View Source

FileWriter(FileStream)

Creates a new writer backed by the file.

Declaration
public FileWriter(FileStream destination)
Parameters
Type Name Description
FileStream destination

Writable file stream.
Exceptions
Type Condition
ArgumentException

destination is not writable.

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

The remaining part of the internal buffer available for write.

Declaration
public Memory<byte> Buffer { get; }
Property Value
Type Description
Memory<byte>
Remarks

The size of returned buffer may be less than or equal to MaxBufferSize.

| 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 Reset() or WriteAsync(CancellationToken) before changing the position.
| Edit this page View Source

HasBufferedData

Gets a value indicating that this writer has buffered data.

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

WritePosition

Gets write position.

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

The returned value may be larger than FilePosition because the writer performs buffered write.

| Edit this page View Source

WrittenBuffer

Gets written part of the buffer.

Declaration
public ReadOnlyMemory<byte> WrittenBuffer { get; }
Property Value
Type Description
ReadOnlyMemory<byte>

Methods

| Edit this page View Source

CopyFromAsync(Stream, long, CancellationToken)

Writes the content from the specified stream.

Declaration
public ValueTask CopyFromAsync(Stream source, long count, CancellationToken token = default)
Parameters
Type Name Description
Stream source

The stream to read from.
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 state of asynchronous execution.
Exceptions
Type Condition
ArgumentOutOfRangeException

count is negative.
OperationCanceledException

The operation has been canceled.
EndOfStreamException

source doesn't have enough data to read.
| Edit this page View Source

CopyFromAsync(Stream, CancellationToken)

Writes the content from the specified stream.

Declaration
public ValueTask CopyFromAsync(Stream input, CancellationToken token = default)
Parameters
Type Name Description
Stream input

The stream to read from.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing state of asynchronous execution.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.
| 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
| Edit this page View Source

EncodeAsync(ReadOnlyMemory<char>, EncodingContext, LengthFormat?, CancellationToken)

Encodes a block of characters using the specified encoding.

Declaration
public ValueTask<long> EncodeAsync(ReadOnlyMemory<char> chars, EncodingContext context, LengthFormat? lengthFormat, CancellationToken token = default)
Parameters
Type Name Description
ReadOnlyMemory<char> chars

The characters to encode.
EncodingContext context

The context describing encoding of characters.
LengthFormat? lengthFormat

String length encoding format; or null to prevent encoding of string length.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<long>

The number of written bytes.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.
ArgumentOutOfRangeException

lengthFormat is invalid.
| Edit this page View Source

FlushToDisk()

Flushes the operating system buffers for the given file to disk.

Declaration
public void FlushToDisk()
Exceptions
Type Condition
ObjectDisposedException

The writer has been disposed.
| Edit this page View Source

FormatAsync<T>(T, EncodingContext, LengthFormat?, string?, IFormatProvider?, MemoryAllocator<char>?, CancellationToken)

Encodes formatted value as a set of characters using the specified encoding.

Declaration
public ValueTask<long> FormatAsync<T>(T value, EncodingContext context, LengthFormat? lengthFormat, string? format = null, IFormatProvider? provider = null, MemoryAllocator<char>? allocator = null, CancellationToken token = default) where T : ISpanFormattable
Parameters
Type Name Description
T value

The type value to be written as string.
EncodingContext context

The context describing encoding of characters.
LengthFormat? lengthFormat

String length encoding format; or null to prevent encoding of string length.
string format

The format of the value.
IFormatProvider provider

The format provider.
MemoryAllocator<char> allocator

Characters buffer allocator.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<long>

The number of written bytes.
Type Parameters
Name Description
T

The type of formattable value.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.
ArgumentOutOfRangeException

lengthFormat is invalid.
| Edit this page View Source

FormatAsync<T>(T, LengthFormat?, string?, IFormatProvider?, CancellationToken)

Converts the value to UTF-8 encoded characters.

Declaration
public ValueTask<int> FormatAsync<T>(T value, LengthFormat? lengthFormat, string? format = null, IFormatProvider? provider = null, CancellationToken token = default) where T : IUtf8SpanFormattable
Parameters
Type Name Description
T value

The value to convert.
LengthFormat? lengthFormat

String length encoding format.
string format

The format of the value.
IFormatProvider provider

The format provider.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<int>

The number of written bytes.
Type Parameters
Name Description
T

The type of the value to convert.
Exceptions
Type Condition
InternalBufferOverflowException

The internal buffer cannot place all UTF-8 bytes exposed by value.
| Edit this page View Source

Produce(int)

Marks the specified number of bytes in the buffer as produced.

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

The number of produced bytes.
Exceptions
Type Condition
ArgumentOutOfRangeException

count is larger than the length of Buffer.
ObjectDisposedException

The writer has been disposed.
| Edit this page View Source

Reset()

Drops all buffered data.

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

TryWrite(ReadOnlySpan<byte>)

Tries to write the data to the internal buffer.

Declaration
public bool TryWrite(ReadOnlySpan<byte> input)
Parameters
Type Name Description
ReadOnlySpan<byte> input

The input data to be copied.
Returns
Type Description
bool

true if the internal buffer has enough space to place the data from input; otherwise, false.
| Edit this page View Source

Write()

Flushes buffered data to the file.

Declaration
public void Write()
Exceptions
Type Condition
ObjectDisposedException

The writer has been disposed.
| Edit this page View Source

Write(ReadOnlySpan<byte>)

Writes the data to the file through the buffer.

Declaration
public void Write(ReadOnlySpan<byte> input)
Parameters
Type Name Description
ReadOnlySpan<byte> input

The input data to write.
Exceptions
Type Condition
ObjectDisposedException

The object has been disposed.
| Edit this page View Source

WriteAsync(ReadOnlyMemory<byte>, LengthFormat, CancellationToken)

Encodes a block of memory, optionally prefixed with the length encoded as a sequence of bytes according to the specified format.

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

A block of memory.
LengthFormat lengthFormat

Indicates how the length of the BLOB must be encoded.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing state of asynchronous execution.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.
| Edit this page View Source

WriteAsync(ReadOnlyMemory<byte>, CancellationToken)

Writes the data to the underlying storage through the buffer.

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

The input data to write.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing asynchronous result.
Exceptions
Type Condition
ObjectDisposedException

The object has been disposed.
OperationCanceledException

The operation has been canceled.
| Edit this page View Source

WriteAsync(CancellationToken)

Flushes buffered data to the underlying storage.

Declaration
public ValueTask WriteAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing asynchronous result.
Exceptions
Type Condition
ObjectDisposedException

The writer has been disposed.
OperationCanceledException

The operation has been canceled.
| Edit this page View Source

WriteAsync<T>(T, CancellationToken)

Encodes formattable value as a set of bytes.

Declaration
public ValueTask WriteAsync<T>(T value, CancellationToken token = default) where T : IBinaryFormattable<T>
Parameters
Type Name Description
T value

The value to be written as a sequence of bytes.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing state of asynchronous execution.
Type Parameters
Name Description
T

The type of formattable value.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.
| Edit this page View Source

WriteBigEndianAsync<T>(T, CancellationToken)

Writes integer value in big-endian format.

Declaration
public ValueTask WriteBigEndianAsync<T>(T value, CancellationToken token = default) where T : IBinaryInteger<T>
Parameters
Type Name Description
T value

The value to be written in big-endian format.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing state of asynchronous execution.
Type Parameters
Name Description
T

The integer type.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.
| Edit this page View Source

WriteLittleEndianAsync<T>(T, CancellationToken)

Writes integer value in little-endian format.

Declaration
public ValueTask WriteLittleEndianAsync<T>(T value, CancellationToken token = default) where T : IBinaryInteger<T>
Parameters
Type Name Description
T value

The value to be written in little-endian format.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing state of asynchronous execution.
Type Parameters
Name Description
T

The integer type.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.

Implements

Extension Methods