[API Proposal]: Get a Read-only view of a StringBuilder body and clear the StringBuilder.

[jkoritzinsky]

Background and motivation

The Roslyn and runtime teams are looking at improving the experience of writing formatted text, primarily around source generators. An important feature for Roslyn is a mechanism to, without a copy, get a read-only view of any text that no one else can write to. The lack of an API to provide this has been blocking dotnet/roslyn#61326.

The Roslyn team has mentioned recently that they are okay with a non-optimal copy-based API for downlevel scenarios as long as there is a no-copy API on the horizon. This proposal provides such an API.

API Proposal

namespace System.Text;

public class StringBuilder
{
    public System.Buffers.ReadOnlySequence<char> ToReadOnlySequenceAndClear();
}

This API will create a read-only sequence over the chunks in the StringBuilder's content, reset the internal buffer of the builder to a new backing array, and remove references to previous chuncks.

This clearing behavior is in contrast to the behavior when Clear is called, where the internal array is not thrown away.

API Usage

ReadOnlySequence<char> GetReadOnlyView(StringBuilder builder)
{
    return builder.ToReadOnlySequenceAndClear();
}

Alternative Designs

Instead of enhancing StringBuilder as-is, we could make a type that wraps StringBuilder and provides a more fully-featured API set for the formatted text writing and provides this sort of API (built on top of StringBuilder.GetChunks() and the fact that it would own the StringBuilder instance).

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-runtime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

The Roslyn and runtime teams are looking at improving the experience of writing formatted text, primarily around source generators. An important feature for Roslyn is a mechanism to, without a copy, get a read-only view of any text that no one else can write to. The lack of an API to provide this has been blocking dotnet/roslyn#61326.

The Roslyn team has mentioned recently that they are okay with a non-optimal copy-based API for downlevel scenarios as long as there is a no-copy API on the horizon. This proposal provides such an API.

API Proposal

namespace System.Text;

public class StringBuilder
{
    public System.Buffers.ReadOnlySequence<char> ToReadOnlySequenceAndClear();
}

This API will create a read-only sequence over the chunks in the StringBuilder's content, reset the internal buffer of the builder to a new backing array, and remove references to previous chuncks.

This clearing behavior is in contrast to the behavior when Clear is called, where the internal array is not thrown away.

API Usage

ReadOnlySequence<char> GetReadOnlyView(StringBuilder builder)
{
    return builder.ToReadOnlySequenceAndClear();
}

Alternative Designs

Instead of enhancing StringBuilder as-is, we could make a type that wraps StringBuilder and provides a more fully-featured API set for the formatted text writing and provides this sort of API (built on top of StringBuilder.GetChunks() and the fact that it would own the StringBuilder instance).

Risks

No response

Author:	jkoritzinsky
Assignees:	-
Labels:	api-suggestion, area-System.Runtime
Milestone:	-

[jkoritzinsky]

cc: @CyrusNajmabadi @stephentoub

[stephentoub]

Related to #87362

(As with that one, this would necessitate moving ReadOnlySequence into corelib.)

[MichalPetryka]

I don't see how the Clear behaviour here makes sense, seems like you effectively want it to alloc a new StringBuilder instead.

[CyrusNajmabadi]

I don't see how the Clear behaviour here makes sense, seems like you effectively want it to alloc a new StringBuilder instead.

We want to transfer ownership of hte underlying data. That's only safe if after the operation the SB itself doesn't point at the data (hence, it is "cleared").

[lambdageek]

I don't see how the Clear behaviour here makes sense, seems like you effectively want it to alloc a new StringBuilder instead.

We want to transfer ownership of hte underlying data. That's only safe if after the operation the SB itself doesn't point at the data (hence, it is "cleared").

I'm still unclear on the scenario. Either there's a single reference to the string builder instance - in which case it's ok to have 2 separate operations - one that gives a view of the underlying chunks and a separate clear operation (different from the existing Clear which mutates the internal array).

Or there are multiple references - in which case don't they already need some kind of coordination mechanism? Otherwise how could they possibly call Append twice and have any confidence that they're still writing to the same buffer.

It seems the "and clear" part can be separate.

[jkoritzinsky]

I don't see how the Clear behaviour here makes sense, seems like you effectively want it to alloc a new StringBuilder instead.

We want to transfer ownership of hte underlying data. That's only safe if after the operation the SB itself doesn't point at the data (hence, it is "cleared").

I'm still unclear on the scenario. Either there's a single reference to the string builder instance - in which case it's ok to have 2 separate operations - one that gives a view of the underlying chunks and a separate clear operation (different from the existing Clear which mutates the internal array).

This is the expected scenario. In the Roslyn source generator scenario, the user would build up the source in the StringBuilder and then pass the resulting sequence between phases (so the StringBuilder would be single-use or a pooled instance, never saved in a field for later usage based on previous state).

Or there are multiple references - in which case don't they already need some kind of coordination mechanism? Otherwise how could they possibly call Append twice and have any confidence that they're still writing to the same buffer.

Today, there's not a good mechanism for coordination when using the GetChunks method while also clearing the buffer, which is what this API effectively enables.

It seems the "and clear" part can be separate.

We could just introduce a ResetBuffers() that would release all the internal buffers instead of what "Clear" does and then Roslyn could provide the "create a ReadOnlySequence and reset" mechanism on top (possibly internally).

[reflectronic]

A similar API #72625 went from "ToImmutableAndClear" to "DrainToImmutable" in API review, perhaps this 'drain' naming pattern should be used here as well--DrainToReadOnlySequence?

[jkoritzinsky]

I didn't realize there was precident for that naming in dotnet/runtime. I'd be fine with DrainToReadOnlySequence or the like.

[hamarb123]

+1 for this, except I want an unsafe version that doesn't clear it to use.

namespace System.Text
{
    public class StringBuilder
    {
        public System.Buffers.ReadOnlySequence<char> DrainToReadOnlySequence(); //new
    }
}

namespace System.Runtime.InteropServices
{
    public class SequenceMarshal
    {
        public System.Buffers.ReadOnlySequence<char> FromStringBuilder(StringBuilder sb); //new
    }
}