`ImmutableArray<T>` cannot be passed to methods accepting `ReadOnlySpan<T>`

[rreminy]

Description

Immutable arrays are unable to be passed to methods accepting read-only spans.

Reproduction Steps

public static void Main(string[] args)
{
    // Have some ImmutableArray<T> (in this case T being byte)
    var array = "Gem was here"u8.ToImmutableArray();

    // Some method accepting ReadOnlySpan<T> (again, in this case, byte)
    SomeMethod(array);
}

public static void SomeMethod(ReadOnlySpan<byte> span)
{
    // Lets keep this quite simple
    Console.WriteLine(Encoding.UTF8.GetString(span));
}

Expected behavior

Gem was here

Actual behavior

CS1503: Argument 1: cannot convert from System.Collections.Immutable.ImmutableArray<byte> to System.ReadOnlySpan<byte>

Regression?

None that I know of

Known Workarounds

• Adding .AsSpan() on the ImmutableArray<T>, which gives a ReadOnlySpan<T>
• Using T[] instead of ImmutableArray<T>, which can be passed fine to methods accepting ReadOnlySpan<T>

Configuration

.NET 10, Windows 10, x64

Other information

https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-14.0/first-class-span-types

[dotnet-policy-service]

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

[MihuBot]

I'm a bot. Here are possible related and/or duplicate issues (I may be wrong):

• No implicit conversion from ImmutableArray<T> to ReadOnlySpan<T> ? #88019
• Add ImmutableArray Span-based APIs #22928

[teo-tsirpanis]

I wonder if implicit conversions from ImmutableArray<T> to ReadOnlySpan<T> and ReadOnlyMemory<T> should be added (T[] has both).

[dotnet-policy-service]

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

[eiriktsarpalis]

Note

This comment was generated with the assistance of GitHub Copilot.

Background and motivation

ImmutableArray<T> is semantically an immutable wrapper over T[], yet unlike T[] it cannot be implicitly converted to ReadOnlySpan<T>. This forces callers to use .AsSpan() every time they pass an ImmutableArray<T> to a span-accepting method:

ImmutableArray<byte> data = ...;
SomeMethod(data.AsSpan()); // Required today
SomeMethod(data);          // CS1503 — cannot convert

With C# 14 first-class span types, T[] now benefits from built-in language-level span conversions, widening the ergonomic gap between arrays and ImmutableArray<T>. Adding an implicit conversion operator would close this gap and make ImmutableArray<T> a first-class citizen in span-based APIs — matching the experience users already have with T[].

Related: #22928 (added AsSpan/AsMemory and other span-based APIs in .NET 7, but did not add implicit conversion operators). Note that the implicit conversion to ReadOnlySpan<T> was originally approved in the July 2017 API review but was dropped when the issue was revived with an expanded scope in 2021.

API Proposal

namespace System.Collections.Immutable;

public partial struct ImmutableArray<T>
{
    // EXISTING
    // public ReadOnlySpan<T> AsSpan();

    public static implicit operator ReadOnlySpan<T>(ImmutableArray<T> array);
}

Additionally, [OverloadResolutionPriority(1)] is applied to the string.Join(char, params ReadOnlySpan<string?>) and string.Join(string?, params ReadOnlySpan<string?>) overloads to resolve the overload ambiguity that would otherwise occur when passing ImmutableArray<string> to string.Join:

namespace System;

public partial class String
{
    // EXISTING — add [OverloadResolutionPriority(1)]
    // [OverloadResolutionPriority(1)]
    // public static string Join(char separator, params ReadOnlySpan<string?> value);
    // [OverloadResolutionPriority(1)]
    // public static string Join(string? separator, params ReadOnlySpan<string?> value);
}

Prototype: eiriktsarpalis@ba2c8e58629

API Usage

ImmutableArray<byte> data = "hello"u8.ToImmutableArray();

// Pass directly to span-accepting methods — no .AsSpan() needed
int index = data.AsSpan().IndexOf((byte)'l'); // before
int index = MemoryExtensions.IndexOf((ReadOnlySpan<byte>)data, (byte)'l'); // after (implicit conversion)

// Assign to ReadOnlySpan<T>
ReadOnlySpan<byte> span = data;

// Pass to user methods
static void ProcessData(ReadOnlySpan<byte> bytes) { /* ... */ }
ProcessData(data); // works with implicit conversion

Alternative Designs

• Status quo (AsSpan() only): Works, but introduces friction compared to T[] which converts implicitly. As span-based APIs proliferate, the .AsSpan() boilerplate becomes increasingly common.
• Include ReadOnlyMemory<T> implicit conversion: Would be consistent with T[] which has implicit conversions to both types, but ReadOnlyMemory<T> is more niche and expensive. Omitting it avoids additional ambiguity risks with overload sets that expose both ReadOnlySpan<T> and ReadOnlyMemory<T>.

Risks

Source breaking changes

Without the [OverloadResolutionPriority] change to string.Join, the new implicit operator causes overload resolution ambiguity at call sites where a method has overloads accepting both IEnumerable<T> and params ReadOnlySpan<T>. The concrete example found in dotnet/runtime is string.Join:

// Before: unambiguous — only string.Join(string?, IEnumerable<string?>) applies
string.Join(",", typeArguments) // typeArguments is ImmutableArray<string>

// Without ORP fix: CS0121 — ambiguous between string.Join(string?, IEnumerable<string?>) and string.Join(string?, params ReadOnlySpan<string?>)

Adding [OverloadResolutionPriority(1)] to the params ReadOnlySpan<string?> overloads resolves this by making the span overload preferred — which is the desired behavior anyway (more efficient, no enumeration overhead).

Default ImmutableArray<T> behavior

The implicit conversion returns an empty span for default(ImmutableArray<T>) (where the backing array is null), consistent with AsSpan(). This means uninitialized ImmutableArray<T> values silently produce empty spans rather than throwing, which could mask bugs. This is an existing behavior tradeoff inherited from AsSpan().

Usage in dotnet/runtime

A search across src/ for ImmutableArray<T>.AsSpan() call sites found very few adoption opportunities. This is expected — ImmutableArray<T> is rarely used in span-accepting contexts within the runtime itself. The primary beneficiaries are external consumers.

Updated in prototype

File	Description
src/libraries/System.Collections.Immutable/src/.../ImmutableArray_1.cs:414	items.AsSpan() → implicit conversion to InsertSpanRangeInternal(int, ReadOnlySpan<T>)
src/libraries/System.Reflection.Metadata/tests/Utilities/HashTests.cs:21	ImmutableArray.Create(...).AsSpan() → implicit conversion to Hash.GetFNVHashCode(ReadOnlySpan<byte>)

Inapplicable

File	Description	Reason
ImmutableArray_1.cs:734	items.AsSpan() in RemoveRange	Would match RemoveRange(ImmutableArray<T>) overload instead, causing infinite recursion
ImmutableArray_1.cs:918	self.AsSpan().CopyTo(destination)	CopyTo is an instance method on ReadOnlySpan<T>, not reachable through argument-position conversion

[tannergooding]

@eiriktsarpalis do you plan on updating the top comment with the proposal and marking this ready-for-review? It's a simple enough request.

The source breaking change can be resolved with [OverloadResolutionPriority] and is one we likely want the ROSpan variant picked anyways. We then probably don't want to expose an implicit cast to ReadOnlyMemory<T>, we don't really do that elsewhere either due to the expense and nicheness.

[eiriktsarpalis]

I'm on the fence. My impression is that the existence of the AsSpan() method suggests that its author wanted conversion to be explicit.

[tannergooding]

We have a lot of types that have both AsSpan methods and which are implicitly convertible to Span, so I'm guessing it's rather that we didn't have the tools to resolve the ambiguities before-hand. We can always ask the folks on the Roslyn team that helped write it, however -- CC. @333fred, @jaredpar who can help loop in the right people.

[333fred]

I'm on the fence. My impression is that the existence of the AsSpan() method suggests that its author wanted conversion to be explicit.

We can always ask the folks on the Roslyn team that helped write it, however

As your copilot said, @eiriktsarpalis, IA was originally designed to be a thin wrapper over arrays. Even to its detriment (default(IA) throwing NREs, not being silently IA.Empty). If it were redesigned today with the same principals, I suspect it would have a user-defined conversion.

[teo-tsirpanis]

We could also add AsSpan and AsMemory overloads taking offset and (offset, length).