[API Proposal]: Array GetValue SetValue ROS indices

[NinoFloris]

Background and motivation

This would help us to use pooled arrays or fixed size stackallocs, which may not have equal length to the array's rank.

Internally GetFlattenedIndex already uses ROS, so the work would purely be a public api addition.

API Proposal

namespace System;

public class Array
{
    public object? GetValue(params ReadOnlySpan<int> indices);
    public void SetValue(object? value, params ReadOnlySpan<int> indices);
}

API Usage

Array values = ...
var indicesArray = ArrayPool<int>.Shared.Rent(dimensions);
var indices = indicesArray.AsSpan(0, dimensions);
indices.Clear();
do
{
    var value = values.GetValue(indices);
    ...
} (/*increment indices*/);
ArrayPool<int>.Shared.Return(indicesArray);

Note: rent follows return in the same method here. In Npgsql we do have uses across methods (some are async as well), where stackalloc cannot be used.

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

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

[huoyaoyuan]

Is this really a bottleneck? The GetValue/SetValue apis are boxing, and the overhead of boxing primitive types can easily overtake the overhead of index array.

[NinoFloris]

We send plenty of reference type arrays as well. These are simple avoidable allocations, and ROS is used internally already.

[dotnet-policy-service]

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

[eiriktsarpalis]

Background and motivation

Array.GetValue(params int[]) and Array.SetValue(object?, params int[]) require allocating an int[] for the indices when iterating multi-dimensional arrays of unknown rank. This is a friction point for libraries like Npgsql that work with multi-dimensional arrays where the rank is only known at runtime -- they must either allocate an int[] per call or pool index arrays across method boundaries (including across async methods where stackalloc cannot be used).

Internally, Array.GetFlattenedIndex already accepts ReadOnlySpan<int>, so the implementation is trivially a public API surface addition.

API Proposal

namespace System;

public partial class Array
{
    // EXISTING
    // public object? GetValue(params int[] indices);
    // public void SetValue(object? value, params int[] indices);

    public object? GetValue(params ReadOnlySpan<int> indices);
    public void SetValue(object? value, params ReadOnlySpan<int> indices);
}

API Usage

// Iterating a multi-dimensional array of unknown rank without allocating per-call
Array values = ...;
int dimensions = values.Rank;
var indicesArray = ArrayPool<int>.Shared.Rent(dimensions);
var indices = indicesArray.AsSpan(0, dimensions);
indices.Clear();
do
{
    var value = values.GetValue(indices);
    // process value
} while (IncrementIndices(indices, values));
ArrayPool<int>.Shared.Return(indicesArray);

// Using stackalloc for a known-rank iteration pattern
Array values = ...;
Span<int> indices = stackalloc int[values.Rank];
indices.Clear();
do
{
    var value = values.GetValue(indices);
    // process value
} while (IncrementIndices(indices, values));

Design Decisions

• No ReadOnlySpan<long> overloads. The existing long-based overloads internally cast to int and throw ArgumentOutOfRangeException on overflow. They exist for CLS compliance from .NET Framework. New span overloads for long would serve no practical purpose since array dimensions are bounded by int.

• params modifier included. This enables the natural call syntax array.GetValue(1, 2, 3) to resolve to the span overload in C# 13+, avoiding the int[] allocation in expanded form. The existing fixed-arity overloads GetValue(int), GetValue(int, int), GetValue(int, int, int) are still preferred by overload resolution in normal form for 1-3 indices.

Alternative Designs

Generic element-typed overloads (GetValue<T>(params ReadOnlySpan<int> indices) / SetValue<T>(T value, params ReadOnlySpan<int> indices)) were explored to avoid boxing for value-type elements. This is technically feasible -- MemoryMarshal.GetArrayDataReference(Array) combined with GetFlattenedIndex and Unsafe.As<byte, T> can provide unboxed access. However:

• The use case is narrow: you must know T but not the rank at compile time. If you know the rank, you can use the strongly-typed indexer (e.g., int[,] indexer).
• Runtime type validation adds overhead (comparing typeof(T) against the array's element type).
• The non-generic SetValue supports implicit primitive widening (e.g., storing int into long[]), which a generic version would not.
• For reference types, there is no boxing, so the benefit is limited to value-type elements.

This could be a follow-up proposal if demand materializes.

Risks

Overload resolution change (source-compatible). In C# 13+, calls in expanded form like array.GetValue(i, j, k, l) (4+ args) will prefer the new params ReadOnlySpan<int> overload over params int[]. The behavior is identical -- both delegate to the same GetFlattenedIndex(ReadOnlySpan<int>) -- so this is a benign overload resolution change. Calls with 1-3 args still resolve to the existing fixed-arity overloads. Calls in normal form with an explicit int[] argument still resolve to the int[] overload.

Open Questions

• Should the GetFlattenedIndex(ReadOnlySpan<int>) method itself be made public? It would allow advanced callers to compute flat indices for use with MemoryMarshal.GetArrayDataReference, enabling zero-allocation generic access patterns. This is a more advanced API that could be proposed separately.

Related Issues

• [API Proposal]: Array GetValue SetValue ROS indices #125325 (original issue)

Prototype

eiriktsarpalis@6fa75b6c4da