Add ImmutableArray Span-based APIs

[jamesqo]

EDIT see #22928 (comment) for the full API proposal.

@stephentoub You did not open a tracking issue for this in https://github.com/dotnet/corefx/issues/21281, although from the notes at dotnet/apireviews#40 it seems like this was approved (:tada:). So I took the liberty of moving the proposal here:

namespace System.Collections.Immutable
{
    public struct ImmutableArray<T>
    {
        public static implicit operator ReadOnlySpan<T>(ImmutableArray<T> array);
    }
}

Since the API seems to have been approved, this is intended to be a tracking issue for work towards implementing it.

[jamesqo]

@stephentoub I also wanted to open this issue since I noticed you wanted to add the following API to String:

namespace System
{
    public delegate void StringCreateAction<TState>(TState state, Span<char> destination);

    public class String
    {
        public static string Create<TState>(int length, TState state, StringCreateAction action);
        …
    }
}

Would it be worthwhile to add a similar method to create ImmutableArrays without copying as well?

[stephentoub]

You did not open a tracking issue for this in #22387

That's because I thought we said we weren't going to add anything related to collections right now. @terrajobst, did I miss that part of the discussion?

[airbreather]

Would it be worthwhile to add a similar method to create ImmutableArrays without copying as well?

If I understand this part of your suggestion properly, unlike with string, you can already build an ImmutableArray<T> of an initially known size reasonably efficiently with minimal copying:

ImmutableArray<int>.Builder builder = ImmutableArray.CreateBuilder<int>(17);
for (int i = 0; i < 17; i++)
{
    builder.Add(i);
}

ImmutableArray<int> built = builder.MoveToImmutable();

It does require allocating an ImmutableArray<T>.Builder, but otherwise it just holds the exact instance of T[] that is destined to back the final ImmutableArray<T> during MoveToImmutable().

Also, if someone really needed a ReadOnlySpan<T> and only had ImmutableArray<T>, they could bridge the gap themselves fairly easily, using a seemingly (to me) reasonable assumption that ImmutableArray<T> is going to have the underlying T[] as its first (edit: and only) field for a really long time:

using System;
using System.Collections.Immutable;
using System.Runtime.CompilerServices;

static class Program
{
    static void Main()
    {
        var array = CreateImmutableArray();
        UseSpan(array.AsSpan());
    }

    static ImmutableArray<int> CreateImmutableArray()
    {
        return new int[] { 1, 2, 3 }.ToImmutableArray();
    }

    static ReadOnlySpan<T> AsSpan<T>(this ImmutableArray<T> array)
    {
        return Unsafe.As<ImmutableArray<T>, T[]>(ref array);
    }

    static void UseSpan(ReadOnlySpan<int> span)
    {
        for (int i = 0; i < span.Length; i++)
        {
            Console.WriteLine(span[i]);
        }
    }
}

[NickStrupat]

I think something like immutability deserves a place in the BCL. Having developers roll their own is not a great solution given that immutability should impose the strongest guarantee.

I've implemented ImmutableMemory<T> and ImmutableSpan<T> as counterparts to their ReadOnly...<T> friends in System.Memory and there are a couple of edges that weren't super obvious.

Another thing to consider is that without these types in the BCL, developers may forget that ReadOnly...<T> types do not imply immutability of the underlying values. In other words, their existence makes the properties of ReadOnly...<T> more obvious.

[NickStrupat]

The nice thing is that they basically just wrap their counterparts with a couple of careful API choices.

public readonly struct ImmutableMemory<T>
{
	public ReadOnlyMemory<T> Memory { get; }
	public ImmutableMemory(ReadOnlySpan<T> source) => Memory = source.IsEmpty ? ReadOnlyMemory<T>.Empty : source.ToArray();
	private ImmutableMemory(ReadOnlyMemory<T> memory) => Memory = memory;

	public ImmutableSpan<T> ImmutableSpan => new ImmutableSpan<T>(this);

	public static ImmutableMemory<T> Empty { get; } = new ImmutableMemory<T>(ReadOnlySpan<T>.Empty);

	public Int32 Length => Memory.Length;
	public Boolean IsEmpty => Memory.IsEmpty;

	public void CopyTo(Memory<T> destination) => Memory.CopyTo(destination);
	[EditorBrowsable(EditorBrowsableState.Never)]
	public override Boolean Equals(Object obj) => obj is ImmutableMemory<T> im && Memory.Equals(im);
	public Boolean Equals(ImmutableMemory<T> other) => Memory.Equals(other.Memory);
	[EditorBrowsable(EditorBrowsableState.Never)]
	public override Int32 GetHashCode() => Memory.GetHashCode();
	public MemoryHandle Pin() => Memory.Pin();
	public ImmutableMemory<T> Slice(Int32 start, Int32 length) => new ImmutableMemory<T>(Memory.Slice(start, length));
	public ImmutableMemory<T> Slice(Int32 start) => new ImmutableMemory<T>(Memory.Slice(start));
	public T[] ToArray() => Memory.ToArray();
	public override String ToString() => Memory.ToString();
	public Boolean TryCopyTo(Memory<T> destination) => Memory.TryCopyTo(destination);

	public static implicit operator ImmutableMemory<T>(ArraySegment<T> segment) => new ImmutableMemory<T>(segment.AsSpan());
	public static implicit operator ImmutableMemory<T>(T[] array) => new ImmutableMemory<T>((ReadOnlySpan<T>) array);
}

public readonly ref struct ImmutableSpan<T>
{
	public ReadOnlySpan<T> Span { get; }
	public ImmutableSpan(ImmutableMemory<T> immutableMemory) => Span = immutableMemory.Memory.Span;
	private ImmutableSpan(ReadOnlySpan<T> span) => Span = span;
	public static ImmutableSpan<T> Empty => new ImmutableSpan<T>(ImmutableMemory<T>.Empty);

	public ref readonly T this[Int32 index] => ref Span[index];

	public Int32 Length => Span.Length;
	public Boolean IsEmpty => Span.IsEmpty;

	public void CopyTo(Span<T> destination) => Span.CopyTo(destination);

	[EditorBrowsable(EditorBrowsableState.Never)]
	[Obsolete("Equals() on ReadOnlySpan will always throw an exception. Use == instead.")]
	public override Boolean Equals(Object obj) => throw new NotSupportedException();

	public Enumerator GetEnumerator() => new Enumerator(this);

	[EditorBrowsable(EditorBrowsableState.Never)]
	[Obsolete("GetHashCode() on ReadOnlySpan will always throw an exception.")]
	public override Int32 GetHashCode() => throw new NotSupportedException();

	[EditorBrowsable(EditorBrowsableState.Never)]
	public ref readonly T GetPinnableReference() => ref Span.GetPinnableReference();
	public ImmutableSpan<T> Slice(Int32 start) => new ImmutableSpan<T>(Span.Slice(start));
	public ImmutableSpan<T> Slice(Int32 start, Int32 length) => new ImmutableSpan<T>(Span.Slice(start, length));
		
	public T[] ToArray() => Span.ToArray();
	public override String ToString() => Span.ToString();
	public Boolean TryCopyTo(Span<T> destination) => Span.TryCopyTo(destination);
		
	public static Boolean operator ==(ImmutableSpan<T> left, ImmutableSpan<T> right) => left.Span == right.Span;
	public static Boolean operator !=(ImmutableSpan<T> left, ImmutableSpan<T> right) => left.Span == right.Span;

	public static implicit operator ImmutableSpan<T>(T[] array) => new ImmutableSpan<T>((ImmutableMemory<T>) array);
	public static implicit operator ImmutableSpan<T>(ArraySegment<T> segment) => new ImmutableSpan<T>((ImmutableMemory<T>) segment);

	public ref struct Enumerator
	{
		private readonly ImmutableSpan<T> span;
		private int index;

		[MethodImpl(MethodImplOptions.AggressiveInlining)]
		internal Enumerator(ImmutableSpan<T> span)
		{
			this.span = span;
			index = -1;
		}

		[MethodImpl(MethodImplOptions.AggressiveInlining)]
		public bool MoveNext()
		{
			int index = this.index + 1;
			if (index < span.Length)
			{
				this.index = index;
				return true;
			}

			return false;
		}

		public ref readonly T Current {
			[MethodImpl(MethodImplOptions.AggressiveInlining)]
			get => ref span[index];
		}
	}
}

[mikernet]

ImmutableArray<T> ImmutableArray.Create<T>(ReadOnlySpan<T> span) would be rather handy to have to avoid the ceremony and overhead of allocating a builder and such.

[mikernet]

As well as a Builder.AddRange(ReadOnlySpan<T> span) method.

[333fred]

Just ran into another case where Builder.AddRange(ROS<T>) would be very nice. There has not been any movement on this for a couple years: @layomia what do we need to kick off design review? More concrete API proposals?