API Proposal: BufferWriter<T>

[KrzysztofCwalina]

The prototype of this type is in https://github.com/dotnet/corefxlab/tree/master/src/System.Buffers.ReaderWriter/System/Buffers/Writer

namespace System.Buffers.Writer {
    public ref struct BufferWriter<T> where T : IBufferWriter<byte> {

        public BufferWriter(T output);
        public ReadOnlySpan<byte> NewLine; 

        public Span<byte> Buffer { get; }
        public void Advance(int count);
        public void Ensure(int count=1);
        public void Flush();

        // primitive APIs will be available for:
        // byte, sbyte, ushort, short, uint, int, ulong, long, float, double, char, Utf8Char
        // DateTime, DateTimeOffset, TimeSpan, Guid, Uri, BigInteger, Decimal
        public void Write(int value);
        public void WriteLine(int value);
        public void Write(int value, StandardFormat format=default);
        public void WriteLine(int value, StandardFormat format=default);
        public void Write(int value, TransformationFormat format);
        public void WriteLine(int value, TransformationFormat format);

        // string APIs
        public void Write(string value);
        public void WriteLine(string value);
        public void Write(string value, TransformationFormat format);
        public void WriteLine(string value, TransformationFormat format);

        public void Write(ReadOnlySpan<char> value);
        public void WriteLine(ReadOnlySpan<char>  value);
        public void Write(ReadOnlySpan<char> value, TransformationFormat format);
        public void WriteLine(ReadOnlySpan<char> value, TransformationFormat format);

        public void Write(Utf8String value);
        public void WriteLine(Utf8String value);
        public void Write(Utf8String value, TransformationFormat format);
        public void WriteLine(Utf8String value, TransformationFormat format);

        public void Write(ReadOnlySpan<Utf8Char> value);
        public void WriteLine(ReadOnlySpan<Utf8Char>  value);
        public void Write(ReadOnlySpan<Utf8Char> value, TransformationFormat format);
        public void WriteLine(ReadOnlySpan<Utf8Char> value, TransformationFormat format);

        // writables
        public void Write<TWritable>(TWritable value) where TWritable : IWritable;
        public void WriteLine<TWritable>(TWritable value) where TWritable : IWritable;

        public void Write<TWritable>(TWritable value, StandardFormat format) where TWritable : IWritable;
        public void WriteLine<TWritable>(TWritable value, StandardFormat format) where TWritable : IWritable;

        public void Write<TWritable>(TWritable value, TransformationFormat format) where TWritable : IWritable;
        public void WriteLine<TWritable>(TWritable value, TransformationFormat format) where TWritable : IWritable;

        // buffers
        public void WriteBytes(ReadOnlySpan<byte> value);
        public void WriteBytes(ReadOnlySpan<byte> value, TransformationFormat format);

        // Binary write APIs will be available for:
        // byte, sbyte, ushort, short, uint, int, ulong, long, float, double
        // binary. format is L for Little Endian, and B for Big Endian.
        public void WriteBytes(int value, StandardFormat format=default);
        public void WriteBytes(int value, TransformationFormat format);
    }

    public struct TransformationFormat {
        public TransformationFormat(IBufferTransformation transformation);
        public TransformationFormat(params IBufferTransformation[] transformations);
        public StandardFormat Format { get; }
        public bool TryTransform(Span<byte> buffer, ref int written);
    }
}
namespace System.Buffers {
    public interface IWritable {
        bool TryWrite(Span<byte> buffer, out int written, StandardFormat format=default(StandardFormat));
    }
}
namespace System.Buffers.Operations {
    public interface IBufferOperation {
        OperationStatus Execute(ReadOnlySpan<byte> input, Span<byte> output, out int consumed, out int written);
    }
    public interface IBufferTransformation : IBufferOperation {
        OperationStatus Transform(Span<byte> buffer, int dataLength, out int written);
    }
}

cc: @davidfowl, @pakrym, @GrabYourPitchforks, @ahsonkhan, @joshfree, @terrajobst

[pakrym]

Do we need to have all these Write methods on BufferWriter<T>? Can they be implemented as extension methods?

[KrzysztofCwalina]

What's the upside to making them extension methods?

[pakrym]

What about Commit? We decided that calling interface method (Advance) per write is too expensive and added Commit to the BufferWriter we use.

[pakrym]

What's the upside to making them extension methods?

Same reason we did it for spans and sequence - fewer methods to JIT when type gets used with different Ts

[pakrym]

I see, Commit is Flush in your prototype.

[pakrym]

BufferWriter -> ByteBufferWriter?

[KrzysztofCwalina]

Same reason we did it for spans and sequence - fewer methods to JIT when type gets used with different Ts

I think it might make sense for very low level types like Span. I don't think we should be unnaturally moving members that belong to a type out in general.

[pakrym]

Does IWritable represent conversion to binary form or to textual form? What if type want's to have both?

Can you please include other types used in the proposal to API listing (like TransformationFormat, IWritable, etc.)

[KrzysztofCwalina]

StandardFormat controls whether its binary or text.

[pakrym]

StandardFormat controls whether its binary or text.

Why do we need two sets of methods for int then?

    public void Write(int value, StandardFormat format=default);
    public void WriteBytes(int value, StandardFormat format=default);

[KrzysztofCwalina]

Why do we need two sets of methods for int then?

Yeah, I was thinking about it. We could remove WriteBytes. We need to measure perf impact and see if we have consistent format chars that could mean "BE" and "LE" and not be already taken by existing text formats.