[API Proposal]: List<T>.Create<TState>(int, TState, SpanAction<T, TState>)

[neon-sunset]

Background and motivation

As of today, we do not have an API that would allow to safely initialize a List<T>'s underlying buffer directly.

While working on #80633 and investigating available ways to avoid using for (...) { list.Add(element); } in IListProvider<T>.ToList() implementations, there seemed to be a couple of viable options:

• Waiting for and subsequently using [API Proposal]: CollectionsMarshal.CreateList<T>(T[]) #80311
• Implementing an ICollection<T> stub that would wrap an IListProvider<T> instance in order to get passed to new List<T>(collection) which would subsequently call CopyTo(...), achieving the goal

However, it appears we do already have an example of similar use case that solves the same issue: string.Create.
Re-using this pattern for List<T> would achieve safety (span cannot escape) and performance (no extra .Add() calls with state mutation, elided bounds check) at the same time without having to be hidden in CollectionsMarshal class.

API Proposal

namespace System.Collections.Generic;

public partial class List<T>
{
    public static List<T> Create<TState>(int count, TState state, SpanAction<T, TState> action);
}

API Usage

partial class SelectArrayIterator<TSource, TResult>
{
    public List<TResult> ToList()
    {
        return List<TResult>.Create(_source.Length, this, (span, instance) =>
        {
            TSource[] source = instance._source;
            Func<TSource, TResult> selector = instance._selector;
            
            // Assert .Length equality between span and source to elide bounds check
            for (int i = 0; i < span.Length; i++)
            {
                span[i] = _selector(source[i]);
            }
        }
    }
}

Alternative Designs

• [API Proposal]: CollectionsMarshal.CreateList<T>(T[]) #80311
• Add CollectionsMarshal.SetCount API for List<T> #55217

Risks

• Possible inconvenience when using it same as with string.Create
• Expanding a widely used type which increases code size and compilation time?

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[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

As of today, we do not have an API that would allow to safely initialize a List<T>'s underlying buffer directly.

While working on #80633 and investigating available ways to avoid using for (...) { list.Add(element); } in IListProvider<T>.ToList() implementations, there seemed to be a couple of viable options:

• Waiting for and subsequently using [API Proposal]: CollectionsMarshal.CreateList<T>(T[]) #80311
• Implementing an ICollection<T> stub that would wrap an IListProvider<T> instance in order to get passed to new List<T>(collection) which would subsequently call CopyTo(...), achieving the goal

However, it appears we do already have an example of similar use case that solves the same issue: string.Create.
Re-using this pattern for List<T> would achieve safety (span cannot escape) and performance (no extra .Add() calls with state mutation, elided bounds check) at the same time without having to be hidden in CollectionsMarshal class.

API Proposal

namespace System.Collections.Generic;

public partial class List<T>
{
    public static List<T> Create<TState>(int count, TState state, SpanAction<T, TState> action);
}

API Usage

partial class SelectArrayIterator<TSource, TResult>
{
    public List<TResult> ToList()
    {
        return List<TResult>.Create(_source.Length, this, (span, instance) =>
        {
            TSource[] source = instance._source;
            Func<TSource, TResult> selector = instance._selector;
            
            // Assert .Length equality between span and source to elide bounds check
            for (int i = 0; i < span.Length; i++)
            {
                span[i] = _selector(source[i]);
            }
        }
    }
}

Alternative Designs

• [API Proposal]: CollectionsMarshal.CreateList<T>(T[]) #80311
• Add CollectionsMarshal.SetCount API for List<T> #55217

Risks

• Possible inconvenience when using it same as with string.Create
• Expanding a widely used type which increases code size and compilation time?

Author:	neon-sunset
Assignees:	-
Labels:	api-suggestion, area-System.Collections, untriaged
Milestone:	-

[MichalPetryka]

I don't see a point in this API, #55217 will make this fully possible with SetCount + AsSpan and reduced allocation scenarios in general target more advanced users.

[neon-sunset]

@MichalPetryka Generally speaking I agree, was simply concerned regarding the fate of your proposal due to some discussion in PR so submitted an alternative design just in case. I'm happy as long as your or any of the alternatives get into BCL 🙂

[eiriktsarpalis]

I'd be inclined to close this in favor #55217. We generally avoid adding new members to the List<T> type directly out of static footprint concerns unless they are absolutely necessary and/or widely used. Using SpanAction to populate a List<T> seems a bit baroque to me, unlike string this type is mutable.