issue-22928 Add ImmutableArray Span-based APIs

src/libraries/System.Collections.Immutable/ref/System.Collections.Immutable.cs

@@ -90,8 +90,12 @@ public static partial class ImmutableArray
         public static System.Collections.Immutable.ImmutableArray<T> Create<T>(T item1, T item2, T item3, T item4) { throw null; }
         public static System.Collections.Immutable.ImmutableArray<T> Create<T>(params T[]? items) { throw null; }
         public static System.Collections.Immutable.ImmutableArray<T> Create<T>(T[] items, int start, int length) { throw null; }
+        public static System.Collections.Immutable.ImmutableArray<T> Create<T>(System.ReadOnlySpan<T> items) { throw null; }
+        public static System.Collections.Immutable.ImmutableArray<T> Create<T>(System.Span<T> items) { throw null; }
         public static System.Collections.Immutable.ImmutableArray<TSource> ToImmutableArray<TSource>(this System.Collections.Generic.IEnumerable<TSource> items) { throw null; }
         public static System.Collections.Immutable.ImmutableArray<TSource> ToImmutableArray<TSource>(this System.Collections.Immutable.ImmutableArray<TSource>.Builder builder) { throw null; }
+        public static System.Collections.Immutable.ImmutableArray<T> ToImmutableArray<T>(this System.ReadOnlySpan<T> items) { throw null; }
+        public static System.Collections.Immutable.ImmutableArray<T> ToImmutableArray<T>(this System.Span<T> items) { throw null; }
     }
     public readonly partial struct ImmutableArray<T> : System.Collections.Generic.ICollection<T>, System.Collections.Generic.IEnumerable<T>, System.Collections.Generic.IList<T>, System.Collections.Generic.IReadOnlyCollection<T>, System.Collections.Generic.IReadOnlyList<T>, System.Collections.ICollection, System.Collections.IEnumerable, System.Collections.IList, System.Collections.Immutable.IImmutableList<T>, System.Collections.IStructuralComparable, System.Collections.IStructuralEquatable, System.IEquatable<System.Collections.Immutable.ImmutableArray<T>>
     {
@@ -118,8 +122,11 @@ public static partial class ImmutableArray
         public System.Collections.Immutable.ImmutableArray<T> Add(T item) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> AddRange(System.Collections.Generic.IEnumerable<T> items) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> AddRange(System.Collections.Immutable.ImmutableArray<T> items) { throw null; }
+        public System.Collections.Immutable.ImmutableArray<T> AddRange(System.ReadOnlySpan<T> items) { throw null; }
+        public System.Collections.Immutable.ImmutableArray<T> AddRange(params T[] items) { throw null; }
         public System.ReadOnlyMemory<T> AsMemory() { throw null; }
         public System.ReadOnlySpan<T> AsSpan() { throw null; }
+        public System.ReadOnlySpan<T> AsSpan(int start, int length) { throw null; }
         public System.Collections.Immutable.ImmutableArray<
 #nullable disable
             TOther
@@ -140,6 +147,7 @@ public static System.Collections.Immutable.ImmutableArray<
         public void CopyTo(int sourceIndex, T[] destination, int destinationIndex, int length) { }
         public void CopyTo(T[] destination) { }
         public void CopyTo(T[] destination, int destinationIndex) { }
+        public void CopyTo(System.Span<T> destination) { }
         public bool Equals(System.Collections.Immutable.ImmutableArray<T> other) { throw null; }
         public override bool Equals([System.Diagnostics.CodeAnalysis.NotNullWhenAttribute(true)] object? obj) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T>.Enumerator GetEnumerator() { throw null; }
@@ -152,6 +160,8 @@ public void CopyTo(T[] destination, int destinationIndex) { }
         public System.Collections.Immutable.ImmutableArray<T> Insert(int index, T item) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> InsertRange(int index, System.Collections.Generic.IEnumerable<T> items) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> InsertRange(int index, System.Collections.Immutable.ImmutableArray<T> items) { throw null; }
+        public System.Collections.Immutable.ImmutableArray<T> InsertRange(int index, T[] items) { throw null; }
+        public System.Collections.Immutable.ImmutableArray<T> InsertRange(int index, System.ReadOnlySpan<T> items) { throw null; }
         public ref readonly T ItemRef(int index) { throw null; }
         public int LastIndexOf(T item) { throw null; }
         public int LastIndexOf(T item, int startIndex) { throw null; }
@@ -171,9 +181,12 @@ public void CopyTo(T[] destination, int destinationIndex) { }
         public System.Collections.Immutable.ImmutableArray<T> RemoveRange(System.Collections.Immutable.ImmutableArray<T> items) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> RemoveRange(System.Collections.Immutable.ImmutableArray<T> items, System.Collections.Generic.IEqualityComparer<T>? equalityComparer) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> RemoveRange(int index, int length) { throw null; }
+        public System.Collections.Immutable.ImmutableArray<T> RemoveRange(System.ReadOnlySpan<T> items, System.Collections.Generic.IEqualityComparer<T>? equalityComparer = null) { throw null; }
+        public System.Collections.Immutable.ImmutableArray<T> RemoveRange(T[] items, System.Collections.Generic.IEqualityComparer<T>? equalityComparer = null) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> Replace(T oldValue, T newValue) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> Replace(T oldValue, T newValue, System.Collections.Generic.IEqualityComparer<T>? equalityComparer) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> SetItem(int index, T item) { throw null; }
+        public System.Collections.Immutable.ImmutableArray<T> Slice(int start, int length) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> Sort() { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> Sort(System.Collections.Generic.IComparer<T>? comparer) { throw null; }
         public System.Collections.Immutable.ImmutableArray<T> Sort(System.Comparison<T> comparison) { throw null; }
@@ -226,9 +239,12 @@ public void AddRange(T[] items, int length) { }
             public void AddRange<TDerived>(System.Collections.Immutable.ImmutableArray<TDerived> items) where TDerived : T { }
             public void AddRange<TDerived>(System.Collections.Immutable.ImmutableArray<TDerived>.Builder items) where TDerived : T { }
             public void AddRange<TDerived>(TDerived[] items) where TDerived : T { }
+            public void AddRange(System.ReadOnlySpan<T> items) { }
+            public void AddRange<TDerived>(System.ReadOnlySpan<TDerived> items) where TDerived : T { }
             public void Clear() { }
             public bool Contains(T item) { throw null; }
             public void CopyTo(T[] array, int index) { }
+            public void CopyTo(System.Span<T> destination) { }
             public System.Collections.Generic.IEnumerator<T> GetEnumerator() { throw null; }
             public int IndexOf(T item) { throw null; }
             public int IndexOf(T item, int startIndex) { throw null; }

src/libraries/System.Collections.Immutable/ref/System.Collections.Immutable.csproj

@@ -5,6 +5,7 @@
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="System.Collections.Immutable.cs" />
+    <Compile Include="System.Collections.Immutable.netcoreapp.cs" Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'" />
   </ItemGroup>
   <ItemGroup Condition="'$(TargetFramework)' == '$(NetCoreAppCurrent)'">
     <ProjectReference Include="$(LibrariesProjectRoot)System.Collections\ref\System.Collections.csproj" />

src/libraries/System.Collections.Immutable/ref/System.Collections.Immutable.netcoreapp.cs

@@ -0,0 +1,13 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// ------------------------------------------------------------------------------
+// Changes to this file must follow the https://aka.ms/api-review process.
+// ------------------------------------------------------------------------------
+
+namespace System.Collections.Immutable
+{
+    public readonly partial struct ImmutableArray<T> : System.Collections.Generic.ICollection<T>, System.Collections.Generic.IEnumerable<T>, System.Collections.Generic.IList<T>, System.Collections.Generic.IReadOnlyCollection<T>, System.Collections.Generic.IReadOnlyList<T>, System.Collections.ICollection, System.Collections.IEnumerable, System.Collections.IList, System.Collections.Immutable.IImmutableList<T>, System.Collections.IStructuralComparable, System.Collections.IStructuralEquatable, System.IEquatable<System.Collections.Immutable.ImmutableArray<T>>
+    {
+        public System.ReadOnlySpan<T> AsSpan(System.Range range) { throw null; }
+    }
+}

src/libraries/System.Collections.Immutable/src/System.Collections.Immutable.csproj

@@ -49,6 +49,7 @@ System.Collections.Immutable.ImmutableStack&lt;T&gt;</PackageDescription>
     <Compile Include="System\Collections\Immutable\ImmutableArray_1.Builder.DebuggerProxy.cs" />
     <Compile Include="System\Collections\Immutable\ImmutableArray_1.Enumerator.cs" />
     <Compile Include="System\Collections\Immutable\ImmutableArray_1.cs" />
+    <Compile Include="System\Collections\Immutable\ImmutableArray_1.netcoreapp.cs" Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'" />
     <Compile Include="System\Collections\Immutable\ImmutableArray_1.Minimal.cs" />
     <Compile Include="System\Collections\Immutable\ImmutableDictionary.cs" />
     <Compile Include="System\Collections\Immutable\ImmutableDictionary_2.Builder.cs" />

src/libraries/System.Collections.Immutable/src/System/Collections/Immutable/ImmutableArray.cs

@@ -32,7 +32,7 @@ public static ImmutableArray<T> Create<T>()
         /// </summary>
         /// <typeparam name="T">The type of element stored in the array.</typeparam>
         /// <param name="item">The element to store in the array.</param>
-        /// <returns>A 1-element array.</returns>
+        /// <returns>A 1-element immutable array containing the specified item.</returns>
         public static ImmutableArray<T> Create<T>(T item)
         {
             T[] array = new[] { item };
@@ -45,7 +45,7 @@ public static ImmutableArray<T> Create<T>(T item)
         /// <typeparam name="T">The type of element stored in the array.</typeparam>
         /// <param name="item1">The first element to store in the array.</param>
         /// <param name="item2">The second element to store in the array.</param>
-        /// <returns>A 2-element array.</returns>
+        /// <returns>A 2-element immutable array containing the specified items.</returns>
         public static ImmutableArray<T> Create<T>(T item1, T item2)
         {
             T[] array = new[] { item1, item2 };
@@ -59,7 +59,7 @@ public static ImmutableArray<T> Create<T>(T item1, T item2)
         /// <param name="item1">The first element to store in the array.</param>
         /// <param name="item2">The second element to store in the array.</param>
         /// <param name="item3">The third element to store in the array.</param>
-        /// <returns>A 3-element array.</returns>
+        /// <returns>A 3-element immutable array containing the specified items.</returns>
         public static ImmutableArray<T> Create<T>(T item1, T item2, T item3)
         {
             T[] array = new[] { item1, item2, item3 };
@@ -74,13 +74,63 @@ public static ImmutableArray<T> Create<T>(T item1, T item2, T item3)
         /// <param name="item2">The second element to store in the array.</param>
         /// <param name="item3">The third element to store in the array.</param>
         /// <param name="item4">The fourth element to store in the array.</param>
-        /// <returns>A 4-element array.</returns>
+        /// <returns>A 4-element immutable array containing the specified items.</returns>
         public static ImmutableArray<T> Create<T>(T item1, T item2, T item3, T item4)
         {
             T[] array = new[] { item1, item2, item3, item4 };
             return new ImmutableArray<T>(array);
         }
 
+        /// <summary>
+        /// Creates an <see cref="ImmutableArray{T}"/> with the specified elements.
+        /// </summary>
+        /// <typeparam name="T">The type of element stored in the array.</typeparam>
+        /// <param name="items">The elements to store in the array.</param>
+        /// <returns>An immutable array containing the specified items.</returns>
+        public static ImmutableArray<T> Create<T>(ReadOnlySpan<T> items)
+        {
+            if (items.IsEmpty)
+            {
+                return ImmutableArray<T>.Empty;
+            }
+
+            T[] array = items.ToArray();
+            return new ImmutableArray<T>(array);
+        }
+
+        /// <summary>
+        /// Creates an <see cref="ImmutableArray{T}"/> with the specified elements.
+        /// </summary>
+        /// <typeparam name="T">The type of element stored in the array.</typeparam>
+        /// <param name="items">The elements to store in the array.</param>
+        /// <returns>An immutable array containing the specified items.</returns>
+        public static ImmutableArray<T> Create<T>(Span<T> items)
+        {
+            return Create((ReadOnlySpan<T>)items);
+        }
+
+        /// <summary>
+        /// Produce an immutable array of contents from specified elements.
+        /// </summary>
+        /// <typeparam name="T">The type of element in the list.</typeparam>
+        /// <param name="items">The elements to store in the array.</param>
+        /// <returns>An immutable array containing the specified items.</returns>
+        public static ImmutableArray<T> ToImmutableArray<T>(this ReadOnlySpan<T> items)
+        {
+            return Create(items);
+        }
+
+        /// <summary>
+        /// Produce an immutable array of contents from specified elements.
+        /// </summary>
+        /// <typeparam name="T">The type of element in the list.</typeparam>
+        /// <param name="items">The elements to store in the array.</param>
+        /// <returns>An immutable array containing the specified items.</returns>
+        public static ImmutableArray<T> ToImmutableArray<T>(this Span<T> items)
+        {
+            return Create((ReadOnlySpan<T>)items);
+        }
+
         /// <summary>
         /// Creates an <see cref="ImmutableArray{T}"/> populated with the contents of the specified sequence.
         /// </summary>
@@ -133,7 +183,7 @@ public static ImmutableArray<T> CreateRange<T>(IEnumerable<T> items)
         /// </summary>
         /// <typeparam name="T">The type of element stored in the array.</typeparam>
         /// <param name="items">The elements to store in the array.</param>
-        /// <returns>An immutable array.</returns>
+        /// <returns>An immutable array containing the specified items.</returns>
         public static ImmutableArray<T> Create<T>(params T[]? items)
         {
             if (items == null || items.Length == 0)
@@ -368,7 +418,7 @@ public static ImmutableArray<T>.Builder CreateBuilder<T>(int initialCapacity)
         /// </summary>
         /// <typeparam name="TSource">The type of element in the sequence.</typeparam>
         /// <param name="items">The sequence to enumerate.</param>
-        /// <returns>An immutable array.</returns>
+        /// <returns>An immutable array containing the specified items.</returns>
         public static ImmutableArray<TSource> ToImmutableArray<TSource>(this IEnumerable<TSource> items)
         {
             if (items is ImmutableArray<TSource>)
@@ -383,7 +433,7 @@ public static ImmutableArray<TSource> ToImmutableArray<TSource>(this IEnumerable
         /// Returns an immutable copy of the current contents of the builder's collection.
         /// </summary>
         /// <param name="builder">The builder to create the immutable array from.</param>
-        /// <returns>An immutable array.</returns>
+        /// <returns>An immutable array containing the specified items from <paramref name="builder"/>.</returns>
         public static ImmutableArray<TSource> ToImmutableArray<TSource>(this ImmutableArray<TSource>.Builder builder)
         {
             Requires.NotNull(builder, nameof(builder));

src/libraries/System.Collections.Immutable/src/System/Collections/Immutable/ImmutableArray_1.Builder.cs

@@ -348,7 +348,35 @@ public void AddRange(ImmutableArray<T> items, int length)
             /// <summary>
             /// Adds the specified items to the end of the array.
             /// </summary>
-            /// <param name="items">The items.</param>
+            /// <param name="items">The items to add at the end of the array.</param>
+            public void AddRange(ReadOnlySpan<T> items)
+            {
+                int offset = this.Count;
+                this.Count += items.Length;
+
+                items.CopyTo(new Span<T>(_elements, offset, items.Length));
+            }
+
+            /// <summary>
+            /// Adds the specified items to the end of the array.
+            /// </summary>
+            /// <param name="items">The items to add at the end of the array.</param>
+            public void AddRange<TDerived>(ReadOnlySpan<TDerived> items) where TDerived : T
+            {
+                int offset = this.Count;
+                this.Count += items.Length;
+
+                var elements = new Span<T>(_elements, offset, items.Length);
+                for (int i = 0; i < items.Length; i++)
+                {
+                    elements[i] = items[i];
+                }
+            }
+
+            /// <summary>
+            /// Adds the specified items to the end of the array.
+            /// </summary>
+            /// <param name="items">The items to add at the end of the array.</param>
             public void AddRange<TDerived>(ImmutableArray<TDerived> items) where TDerived : T
             {
                 if (items.array != null)
@@ -360,7 +388,7 @@ public void AddRange<TDerived>(ImmutableArray<TDerived> items) where TDerived :
             /// <summary>
             /// Adds the specified items to the end of the array.
             /// </summary>
-            /// <param name="items">The items.</param>
+            /// <param name="items">The items to add at the end of the array.</param>
             public void AddRange(Builder items)
             {
                 Requires.NotNull(items, nameof(items));
@@ -370,7 +398,7 @@ public void AddRange(Builder items)
             /// <summary>
             /// Adds the specified items to the end of the array.
             /// </summary>
-            /// <param name="items">The items.</param>
+            /// <param name="items">The items to add at the end of the array.</param>
             public void AddRange<TDerived>(ImmutableArray<TDerived>.Builder items) where TDerived : T
             {
                 Requires.NotNull(items, nameof(items));
@@ -705,6 +733,16 @@ public void Sort(int index, int count, IComparer<T>? comparer)
                 }
             }
 
+            /// <summary>
+            /// Copies the current contents to the specified <see cref="Span{T}"/>.
+            /// </summary>
+            /// <param name="destination">The <see cref="Span{T}"/> to copy to.</param>
+            public void CopyTo(Span<T> destination)
+            {
+                Requires.Range(this.Count <= destination.Length, nameof(destination));
+                new ReadOnlySpan<T>(_elements, 0, this.Count).CopyTo(destination);
+            }
+
             /// <summary>
             /// Returns an enumerator for the contents of the array.
             /// </summary>