Why does ImmutableList throw IndexOutOfRangeException instead of ArgumentOutOfRangeException when getting the element of the set at the given index?

[PonchoPowers]

Why does ImmutableList throw IndexOutOfRangeException instead of ArgumentOutOfRangeException when getting the element of the set at the given index, but List throws an ArgumentOutOfRangeException exception?

ImmutableList

/// <exception cref="IndexOutOfRangeException">Thrown from getter when <paramref name="index"/> is negative or not less than <see cref="Count"/>.</exception>
        public T this[int index] => _root.ItemRef(index);

List

        public T this[int index] {
            get {
                // Following trick can reduce the range check by one
                if ((uint) index >= (uint)_size) {
                    ThrowHelper.ThrowArgumentOutOfRangeException();
                }
                Contract.EndContractBlock();
                return _items[index]; 
            }

[dotnet-policy-service[bot]]

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

[huoyaoyuan]

It's probably for consistency with ImmutableArray, which must depends on IndexOutOfRangeException on array access for performance reason.

[PonchoPowers]

I can't understand how using IndexOutOfRangeException over ArgumentOutOfRangeException can be any more performant?

I spent more time looking at this and now think List is throwing the wrong exception and ImmutableList is actually throwing the correct exception, because any range exceptions with indexers are supposed to throw an IndexOutOfRangeException instead of an ArgumentOutOfRangeException according to the docs.

[huoyaoyuan]

ImmutableArray is a slim wrapper of array. To be performant, it must act as an array without anything extra and array uses IndexOutOfRangeException.

[AustinWise]

It appears the documentation does not agree with the code. That is, the docs say IndexOutOfRangeException is thrown but the code throws a ArgumentOutOfRangeException. When I run this small program:

using System.Collections.Immutable;

ImmutableList<int> list = ImmutableList.Create<int>([]);
Console.WriteLine(list[0]);

It prints:

Unhandled exception. System.ArgumentOutOfRangeException: Specified argument was out of the range of valid values. (Parameter 'index')
   at System.Collections.Immutable.Requires.FailRange(String parameterName, String message)
   at System.Collections.Immutable.Requires.Range(Boolean condition, String parameterName, String message)
   at System.Collections.Immutable.ImmutableList`1.Node.ItemRef(Int32 index)
   at System.Collections.Immutable.ImmutableList`1.get_Item(Int32 index)
   at Program.<Main>$(String[] args)

You can see the source for FailRange here.

Godbolt

[AustinWise]

This will be fixed by #108896 and dotnet/dotnet-api-docs#10573.