[API Proposal]: ImmutableArray<T>.Builder.ToImmutableAndClear()

[333fred]

Background and motivation

In basically every project I use ImmutableArray in, I end up creating an extension for ToImmutableAndClear on the builder type, which takes advantage of MoveToImmutable() if the current builder has right size, and otherwise falls back to ToImmutable()/Clear() if not. I would really love it if we added this to the BCL itself.

API Proposal

namespace System.Collections.Immutable;

public struct ImmutableArray<T>
{
    public class Builder
    {
        public ImmutableArray<T> ToImmutableAndClear()
        {
            if (Capacity == Count) return MoveToImmutable();
            else
            {
                var result = ToImmutable();
                Clear();
                return result;
            }
       }
    }
}

API Usage

var builder = ImmutableArray.CreateBuilder<string>(/* max possible values */ 42);

foreach (var x in thingGettingMapped)
{
    if (x.Frob) builder.Add(x);
}

return builder.ToImmutableAndClear();

Alternative Designs

No response

Risks

No response

[ghost]

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

Issue Details

---

Background and motivation

In basically every project I use ImmutableArray in, I end up creating an extension for ToImmutableAndClear on the builder type, which takes advantage of MoveToImmutable() if the current builder has right size, and otherwise falls back to ToImmutable()/Clear() if not. I would really love it if we added this to the BCL itself.

API Proposal

namespace System.Collections.Immutable;

public struct ImmutableArray<T>
{
    public class Builder
    {
        public ImmutableArray<T> ToImmutableAndClear()
        {
            if (Capacity == Count) return MoveToImmutable();
            else
            {
                var result = ToImmutable();
                Clear();
                return result;
            }
       }
    }
}

API Usage

var builder = ImmutableArray.CreateBuilder<string>(/* max possible values */ 42);

foreach (var x in thingGettingMapped)
{
    if (x.Frob) builder.Add(x);
}

return builder.ToImmutableAndFree();

Alternative Designs

No response

Risks

No response

Author:	333fred
Assignees:	-
Labels:	api-suggestion, area-System.Collections
Milestone:	-

[Sergio0694]

I also use something like this quite often in my generators and would very much welcome this API 🙂

Nit: the proposal says ToImmutableAndClear but the example uses ToImmutableAndFree, old snippet?

[333fred]

Nit: the proposal says ToImmutableAndClear but the example uses ToImmutableAndFree, old snippet?

No, force of habit. Roslyn also pools builders.

[eiriktsarpalis]

Sounds useful enough. If we do add such a method, we might want to explicitly document that any perf benefits are predicated on Capacity == Count.

[terrajobst]

Video

The challenge is that MoveToImmutable() results in Capacity becoming 0, while ToImmutable(); Clear(); would preserve the capacity. This can result in cases where we need go through various resize cycles, making the Capacity == Count potentially more expensive.

namespace System.Collections.Immutable;

public partial struct ImmutableArray<T>
{
    public partial class Builder
    {
        public ImmutableArray<T> ToImmutableAndClear();
    }
}

[bartonjs]

Video

• ToImmutableAndClear, as proposed, has a problem where when Capacity==Count Capacity changes to 0, and otherwise it remains.
• We instead think the "do the cheapest thing possible" would be DrainToImmutable, always making Capacity 0 as a result of being called.
  • We debated many verbs (Drain, Extract, Empty) and prefix vs post-fix, but prefix matched the existing MoveToImmutable vs ToImmutable choice.

namespace System.Collections.Immutable;

public struct ImmutableArray<T>
{
    public partial class Builder
    {
        public ImmutableArray<T> DrainToImmutable();
    }
}