/// <summary>
/// NOTICE: this method ALWAYS updates the <see cref="IoResult.BytesReadOrWritten"/> property by the buffer's
/// length if the stream does not support seeking. This writes a fixed-size buffer to the sink
/// <see cref="Stream"/>. If the stream can seek, the write must write all bytes in the given buffer's length;
/// or else the <see cref="IoResult.Result"/> is <see cref="IoResultState.BadData"/>. Note that this
/// method catches all exceptions and will <see cref="IoResult.Fault"/> the result. If the stream supports
/// seeking, This method updates the <see cref="IoResult.BytesReadOrWritten"/> property based on the change in
/// the stream's Position. Otherwise the value is always explicitly updated by the buffer's length: you must
/// test the stream to know. If there is an incoming value, it is incremented. Otherwise, if the stream cannot
/// seek, then one <see cref="Stream.WriteAsync(byte[],int,int,CancellationToken)"/> is invoked with the
/// arguments; AND in this case, the <see cref="IoResult.Result"/> is never
/// <see cref="IoResultState.BadData"/>.
/// </summary>
/// <param name="ioResult">Not null.</param>
/// <param name="sinkStream">Not null.</param>
/// <param name="fixedBuffer">Not null.</param>
/// <returns>Completes when the write completes.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentOutOfRangeException"></exception>
public static Task <IoResult> WriteAllAsync(
this IoResult ioResult,
Stream sinkStream,
byte[] fixedBuffer)
{
if (ioResult == null)
{
throw new ArgumentNullException(nameof(ioResult));
}
return(IoHelper.WriteAllAsync(sinkStream, fixedBuffer, ioResult));
}
/// <summary>
/// NOTICE: this method ALWAYS updates the <see cref="IoResult.BytesReadOrWritten"/> property by the buffer's
/// length if the stream does not support seeking. This writes a fixed-size buffer to the sink
/// <see cref="Stream"/>. If the stream can seek, the write must write all bytes in the given buffer's length;
/// or else the <see cref="IoResult.Result"/> is <see cref="IoResultState.BadData"/>. Note that this
/// method catches all exceptions and will <see cref="IoResult.Fault"/> the result. If the stream supports
/// seeking, This method updates the <see cref="IoResult.BytesReadOrWritten"/> property based on the change in
/// the stream's Position. Otherwise the value is always explicitly updated by the buffer's length: you must
/// test the stream to know. If there is an incoming value, it is incremented. Otherwise, if the stream cannot
/// seek, then one <see cref="Stream.WriteAsync(byte[],int,int,CancellationToken)"/> is invoked with the
/// arguments; AND in this case, the <see cref="IoResult.Result"/> is never
/// <see cref="IoResultState.BadData"/>.
/// </summary>
/// <param name="sinkStream">Not null.</param>
/// <param name="fixedBuffer">Not null.</param>
/// <param name="ioResult">Optional. If null, a new instance is created; with any given
/// <see cref="CancellationToken"/>.</param>
/// <param name="cancellationToken">Optional.</param>
/// <returns>Not null. If you provided an argument, the same object is returned.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentOutOfRangeException"></exception>
public static async Task <IoResult> WriteAllAsync(
Stream sinkStream,
byte[] fixedBuffer,
IoResult ioResult = null,
CancellationToken cancellationToken = default)
=> await IoHelper.WriteAllAsync(
sinkStream,
fixedBuffer,
0,
fixedBuffer.Length,
ioResult,
cancellationToken);
/// <summary>
/// NOTICE: this method ALWAYS updates the <see cref="IoResult.BytesReadOrWritten"/> property by the given
/// length if the stream does not support seeking. This writes a specified <c>length</c> from a buffer to the
/// sink <see cref="Stream"/>. If the stream can seek, the write must write all bytes in the given length;
/// or else the <see cref="IoResult.Result"/> is <see cref="IoResultState.BadData"/>. Note that this
/// method catches all exceptions and will <see cref="IoResult.Fault"/> the result. If the stream supports
/// seeking, This method updates the <see cref="IoResult.BytesReadOrWritten"/> property based on the change in
/// the stream's Position. Otherwise the value is always explicitly updated by the given length: you must
/// test the stream to know. If there is an incoming value, it is incremented. Otherwise, if the stream cannot
/// seek, then one <see cref="Stream.WriteAsync(byte[],int,int,CancellationToken)"/> is invoked with the
/// arguments; AND in this case, the <see cref="IoResult.Result"/> is never
/// <see cref="IoResultState.BadData"/>.
/// </summary>
/// <param name="ioResult">Not null.</param>
/// <param name="sinkStream">Not null.</param>
/// <param name="buffer">Not null.</param>
/// <param name="offset">Offset within <c>buffer</c> to begin writing.</param>
/// <param name="length">Length within <c>buffer</c> to write.</param>
/// <returns>Completes when the write completes.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentOutOfRangeException"></exception>
public static Task <IoResult> WriteAllAsync(
this IoResult ioResult,
Stream sinkStream,
byte[] buffer,
int offset,
int length)
{
if (ioResult == null)
{
throw new ArgumentNullException(nameof(ioResult));
}
return(IoHelper.WriteAllAsync(sinkStream, buffer, offset, length, ioResult));
}
