API Proposal: Add a ValueStringBuilder

[JeremyKuhne]

We should consider making a value based StringBuilder to allow low allocation building of strings. While Span allows you to provide a writable buffer, in many scenarios we have a need to get or build strings and we don't know precisely how much space will be needed ahead of time. Having an abstraction that can grow beyond a given initial buffer is particularly useful as it doesn't require looping with Try* APIs- which can be both complicated and have negative performance implications.

We currently use ValueStringBuilder for this purpose internally. It starts with an optional initial buffer (which we often stackalloc) and will grow using ArrayPool if needed.

Design Goals

1. Allow safe usage of stack memory
2. Use pooled memory when needed to reduce GC pressure
3. Allow dynamic and explicit capacity growth
4. Facilitate interop scenarios (i.e. passing as char* szValue)
5. Follow API semantics of StringBuilder & string where possible
6. Be stack allocated

API

Here is the proposed API:

namespace System.Text
{
    public ref struct ValueStringBuilder
    {
        public ValueStringBuilder(Span<char> initialBuffer);

        // The logical length of the builder (end of the "string")
        public int Length { get; set; }

        // Available space in chars
        public int Capacity { get; }

        // Ensure there is at least this amount of space
        public void EnsureCapacity(int capacity);

        // Get a pinnable reference to the builder. "terminate" ensures the builder has a null char after Length in the buffer.
        public ref char GetPinnableReference(bool terminate = false);

        // Indexer, allows setting/getting individual chars
        public ref char this[int index] { get; }

        // Returns a string based off of the current position
        public override string ToString();

        // Returns a span around the contents of the builder. "terminate" ensures the builder has a null char after Length in the buffer.
        public ReadOnlySpan<char> AsSpan(bool terminate);

        // To ensure inlining perf, we have a separate overload for terminate
        public ReadOnlySpan<char> AsSpan();

        public bool TryCopyTo(Span<char> destination, out int charsWritten);

        public void Insert(int index, char value, int count = 1);
        public void Insert(int index, ReadOnlySpan<char> value, int count = 1);

        public void Append(char c, int count = 1);
        public void Append(ReadOnlySpan<char> value);

        // This gives you an appended span that you can write to
        public Span<char> AppendSpan(int length);

        // Returns any ArrayPool buffer that may have been rented
        public void Dispose()
    }
}

This is the current shape of our internal ValueStringBuilder:

namespace System.Text
{
    internal ref struct ValueStringBuilder
    {
        public ValueStringBuilder(Span<char> initialBuffer);
        public int Length { get; set; }
        public int Capacity { get; }
        public void EnsureCapacity(int capacity);

        /// <summary>
        /// Get a pinnable reference to the builder.
        /// </summary>
        /// <param name="terminate">Ensures that the builder has a null char after <see cref="Length"/></param>
        public ref char GetPinnableReference(bool terminate = false);
        public ref char this[int index] { get; }

        // Returns a string based off of the current position
        public override string ToString();

        /// <summary>
        /// Returns a span around the contents of the builder.
        /// </summary>
        /// <param name="terminate">Ensures that the builder has a null char after <see cref="Length"/></param>
        public ReadOnlySpan<char> AsSpan(bool terminate);

        // To ensure inlining perf, we have a separate overload for terminate
        public ReadOnlySpan<char> AsSpan();

        public bool TryCopyTo(Span<char> destination, out int charsWritten);
        public void Insert(int index, char value, int count);
        public void Append(char c);
        public void Append(string s);
        public void Append(char c, int count);
        public unsafe void Append(char* value, int length);
        public void Append(ReadOnlySpan<char> value);

        // This gives you an appended span that you can write to
        public Span<char> AppendSpan(int length);

        // Returns any ArrayPool buffer that may have been rented
        public void Dispose()
    }
}

Sample Code

Here is a common pattern on an API that could theoretically be made public if ValueStringBuilder was public:
(Although we would call this one GetFullUserName or something like that.)

https://github.com/dotnet/corefx/blob/050bc33738887d9d8fcc9bc5965b7d9ca65bc7f4/src/System.Runtime.Extensions/src/System/Environment.Win32.cs#L40-L56

The caller is above this method:

https://github.com/dotnet/corefx/blob/050bc33738887d9d8fcc9bc5965b7d9ca65bc7f4/src/System.Runtime.Extensions/src/System/Environment.Win32.cs#L13-L38

Usage of AppendSpan:

https://github.com/dotnet/corefx/blob/3538128fa1fb2b77a81026934d61cd370a0fd7f5/src/System.Runtime.Numerics/src/System/Numerics/BigNumber.cs#L550-L560

I'll add more usage details and possible API surface area.

Notes

• Does using this remove the need for having a bool TryGet*(Span) overload? (see https://github.com/dotnet/coreclr/pull/17097/files#r176560435)
• Should we allow you to make it non-growable? (So we can avoid TryGet above?)
• Can we get C# to allow using ref structs that have a Dispose() in a using statement? (Proposal: Allow Dispose by Convention csharplang#93)
• Do we care about AppendFormat overloads?
• AppendSpan() is a little tricky to grok- is there a better term/pattern?

[JeremyKuhne]

@jkotas, @stephentoub, @KrzysztofCwalina, @danmosemsft, @ahsonkhan

[stephentoub]

bool terminate

I didn't see that we'd added these arguments. I don't think we should have them. If you want to null terminate, you can call Append('\0').

[JeremyKuhne]

I didn't see that we'd added these arguments. I don't think we should have them. If you want to null terminate, you can call Append('\0').

Discussed this one at length with @jkotas in dotnet/coreclr#16921. The problem with appending a null is that it changes the Length and breaks the convention on what Length means for strings & StringBuilder (i.e. doesn't include the terminator). It is incredibly error prone as a result (as my need for the mentioned pull demonstrates).

StringBuilder always terminates, but doing this comes at a cost. It is only really needed in interop calls that take a sz (most Win32).

[stephentoub]

The problem with appending a null is that it changes the Length and breaks the convention on what Length means for strings & StringBuilder (i.e. doesn't include the terminator).

The bool terminate is also changing the Length.

[JeremyKuhne]

The bool terminate is also changing the Length.

No, it leaves Length as is. It might increase Capacity.

[stephentoub]

Hmm, I see, ok.

[omariom]

Are they needed if there is an overload taking ROSpan?

public void Append(string s);
public unsafe void Append(char* value, int length);

[JeremyKuhne]

Are they needed if there is an overload taking ROSpan?

No, they aren't. I'll add a proposed section.

[omariom]

Can we get C# to allow using ref structs that have a Dispose() in a using statement?

There is a proposal dotnet/csharplang#93
It would be even better with this one dotnet/csharplang#114

[KrzysztofCwalina]

There are several related efforts in corfxlab. We should try to unify (or make them consistent). See:
https://github.com/dotnet/corefxlab/blob/master/src/System.Buffers.ReaderWriter/System/Buffers/Writer/BufferWriter.cs
https://github.com/dotnet/corefxlab/blob/master/src/System.Buffers.ReaderWriter/System/Buffers/Writer/BufferWriterT_ints.cs
https://github.com/dotnet/corefxlab/blob/master/src/System.Buffers.ReaderWriter/System/Buffers/Writer/BufferWriter_strings.cs
And here support for non-allocating composite formats: https://github.com/dotnet/corefxlab/blob/master/src/System.Text.Formatting/System/Text/Formatting/CompositeFormat.cs

This ValueStringBuilder is a specialized BufferWriter. And so if we add it, we need to rationalize it with BufferWriter, i.e. we should not have both BufferWriter and ValueStringBuilder in .NET.

BufferWriter (the non-generic one) is a byref struct that allows writing (and resizing) to a span buffer. Today, it writes Utf8, but you could imagine writing either Utf8 or utf16 based on some setting. After the buffer is written, tere could be ToString or something like that to produce string result.

[JeremyKuhne]

@KrzysztofCwalina thanks for the links! I've updated the text with design goals and will review the other efforts.

[MarcoRossignoli]

Should we allow you to make it non-growable? (So we can avoid TryGet above?)

// some reason it isn't, we'll grow the buffer.

In case of growable could be useful to have a boolean properties to know if VSB has grown? In a hot path could be useful avoid to add pressure to underlying ArrayPool.Shared(today) and improve performance by choosing the right size of initial buffer.

[Joe4evr]

Some questions, I guess...

public void Insert(int index, char value, int count = 1);
public void Insert(int index, ReadOnlySpan<char> value, int count = 1);
public void Append(char c, int count = 1);
public void Append(ReadOnlySpan<char> value);

• Are these the only methods to build with, or will there be more parity with the existing StringBuilder API (AppendLine, string parameter, et al.) and those are omitted from the post for brevity?
• Is there a reason these don't return the this instance to enable fluent building?

[khellang]

Speaking of related efforts... There's also the InplaceStringBuilder from Microsoft.Extensions.Primitives, which is used in MVC and the HTTP abstractions. Might want to sync up with them as well.

// @pakrym @Tratcher

[JeremyKuhne]

In case of growable could be useful to have a boolean properties to know if VSB has grown?

Perhaps we should add an EventSource log for this?