[API Proposal]: ArgumentOutOfRangeException.ThrowIfEqual and ThrowIfNotEqual

[Sergio0694]

Background and motivation

As #69590 added new throw helpers for ArgumentOutOfRangeException, I've started playing around with them trying to move an existing codebase to these new APIs, and one thing that quickly became apparent was how the "equal/not equal" case was currently missing. This proposal is about adding such APIs as well, so that these scenarios can also be supported.

API Proposal

namespace System;

public class ArgumentOutOfRangeException
{
    public static void ThrowIfEqual<T>(T value, T other, [CallerArgumentExpression("value")] string? paramName = null) where T : IEquatable<T>;
    public static void ThrowIfNotEqual<T>(T value, T other, [CallerArgumentExpression("value")] string? paramName = null) where T : IEquatable<T>;
}

I've tried to mirror the design of existing APIs such as ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual, which also take a non-nullable generic, constrained to an interface (in that case it's IComparable<T>).

API Usage

Eg. in ComputeSharp I have a bunch of methods to copy to/from MD textures. Consider this one, using this API:

public static void CopyTo<T>(this Texture2D<T> source, T[,] destination)
    where T : unmanaged
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentNullException.ThrowIfNull(destination);
    ArgumentOutOfRangeException.ThrowIfNotEqual(destination.GetLength(0), source.Height, nameof(destination));
    ArgumentOutOfRangeException.ThrowIfNotEqual(destination.GetLength(1), source.Width, nameof(destination));

    source.CopyTo(ref destination[0, 0], destination.Length, 0, 0, source.Width, source.Height);
}

In general this would be useful whenever people need to explicitly check against a single value (same as eg. ThrowIfZero).

Open questions

The IComparable<T> constraint means Enum values can't use this API. Should we not use the constraint and instead just have the API call EqualityComparer<T>.Default.Equals instead? Are there performance considerations in that case?

[stephentoub]

Why ArgumentException rather than ArgumentOutOfRangeException? I don't think we'd use this in runtime in most of the places we otherwise could if it didn't throw AOORE. It is a range, just a trivial one.

[Sergio0694]

@stephentoub No particular reason other than it just didn't feel like a range, being just a direct comparison. Also the fact the constraint here was just IEquatable<T> and not IComparable<T> implied that there might just not be a total ordering of values in the domain of that type, in which case an ArgumentOutOfRangeException would feel weird, since you can't really have a range if you don't have a total order in that domain 🤔

I was also thinking of cases where you're not using this with a numeric value, eg. say you were comparing against a given string value or some Enum value (assuming we decided to drop the constraint to make that possible), in that case it wouldn't be a range either. In general this to me just felt like something that would mostly be equivalent to E_INVALIDARG as a general error (ie. just "the argument is not valid in some way"). That said, I don't feel too strongly about it 🙂

[stephentoub]

We have ThrowIfZero. It'd be strange if that threw a different type than ThrowIfEqual(..., 0). AOORE is thrown when the argument "contains an invalid value that is not a member of the set of values expected for the argument"... they don't need to be contiguous or ordered.

[Sergio0694]

Ah, gotcha, yeah that makes perfect sense then, didn't think of ThrowIfZero for reference 🙂
Should I update the proposed API shape to use OOORE instead as the containing type?

[stephentoub]

please :-)

[MichalPetryka]

Personally, I use ArgumentOutOfRangeException only with arguments that are numbers, having equals throw it feels weird to me.

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

Issue Details

---

Background and motivation

As #69590 added new throw helpers for ArgumentOutOfRangeException, I've started playing around with them trying to move an existing codebase to these new APIs, and one thing that quickly became apparent was how the "equal/not equal" case was currently missing. This proposal is about adding such APIs as well, so that these scenarios can also be supported.

API Proposal

namespace System;

public class ArgumentOutOfRangeException
{
    public static void ThrowIfEqual<T>(T value, T other, [CallerArgumentExpression("value")] string? paramName = null) where T : IEquatable<T>;
    public static void ThrowIfNotEqual<T>(T value, T other, [CallerArgumentExpression("value")] string? paramName = null) where T : IEquatable<T>;
}

I've tried to mirror the design of existing APIs such as ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual, which also take a non-nullable generic, constrained to an interface (in that case it's IComparable<T>).

API Usage

Eg. in ComputeSharp I have a bunch of methods to copy to/from MD textures. Consider this one, using this API:

public static void CopyTo<T>(this Texture2D<T> source, T[,] destination)
    where T : unmanaged
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentNullException.ThrowIfNull(destination);
    ArgumentOutOfRangeException.ThrowIfNotEqual(destination.GetLength(0), source.Height, nameof(destination));
    ArgumentOutOfRangeException.ThrowIfNotEqual(destination.GetLength(1), source.Width, nameof(destination));

    source.CopyTo(ref destination[0, 0], destination.Length, 0, 0, source.Width, source.Height);
}

In general this would be useful whenever people need to explicitly check against a single value (same as eg. ThrowIfZero).

Open questions

The IComparable<T> constraint means Enum values can't use this API. Should we not use the constraint and instead just have the API call EqualityComparer<T>.Default.Equals instead? Are there performance considerations in that case?

Author:	Sergio0694
Assignees:	-
Labels:	area-System.Runtime, api-ready-for-review
Milestone:	8.0.0