[API Proposal]: Remove IEquatable<T>? constraint on ArgumentOutOfRangeException ThrowIfEqual/ThrowIfNotEqual

[bill-poole]

Background and motivation

The ThrowIfEqual and ThrowIfNotEqual methods on the ArgumentOutOfRangeException class both have a where T : IEquatable<T>? constraint. However, the implementations of these methods do not seem to rely on this constraint, using EqualityComparer<T>.Default.Equals(T?, T?), which does not require T to implement IEquatable<T>.

The IEquatable<T> constraint prevents us from using the ThrowIfEqual and ThrowIfNotEqual methods on nullable value types (e.g., int?).

However, we can circumvent this constraint by wrapping the parameters in a ValueTuple<T> struct because ValueTuple<T> implements IEquatable<ValueTuple<T>>, but does not require T : IEquatable<T>. For example:

int? x = 10;
ArgumentOutOfRangeException.ThrowIfNotEqual(new ValueTuple<int?>(x), new ValueTuple<int?>(20));

Therefore it seems that the IEquatable<T> constraint should be removed from the ThrowIfEqual and ThrowIfNotEqual methods given that the ThrowIfEqual method is basically performing the same function as ValueTuple<T>.Equals(ValueTuple<T>), which does not have this constraint.

API Proposal

namespace System;

public class ArgumentOutOfRangeException : ArgumentException
{
    public static void ThrowIfEqual<T>(T value, T other, 
        [CallerArgumentExpression(nameof(value))] string? paramName = null);

    public static void ThrowIfNotEqual<T>(T value, T other, 
        [CallerArgumentExpression(nameof(value))] string? paramName = null);
}

API Usage

int? x = 10;
ArgumentOutOfRangeException.ThrowIfNotEqual(x, 20);

Alternative Designs

No response

Risks

No response

[bill-poole]

This change would also allow us to use the ThrowIfEqual and ThrowIfNotEqual methods to validate enum arguments:

var now = DateTime.Now;
ArgumentOutOfRangeException.ThrowIfNotEqual(now.Kind, DateTimeKind.Utc);

[dotnet-policy-service]

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

[IDisposable]

How does widening the acceptable types affect binary compatibility (it can't break source compatibility because this was not previously expressible)?

[jeffhandley]

Marked as api-ready-for-review API is ready for review, it is NOT ready for implementation . Looks like a valuable proposal, and we can discuss any concerns (compatibility or otherwise) in API Review if they don't get discussed here first.

[hez2010]

How does widening the acceptable types affect binary compatibility

There's nothing to be concerned about when widening a generic constraint.

[colejohnson66]

How does widening the acceptable types affect binary compatibility

There's nothing to be concerned about when widening a generic constraint.

To be more specific: Generic constraints do not affect the method signature (to the chagrin of some C# developers). Therefore, relaxing ("widening") them does not cause issues.

--

As for the actual API, my only concern here is that someone might do:

// SomeOtherObject is a class that *doesn't* implement IEquatable<SomeOtherObject>
public SomeObject(SomeOtherObject arg)
{
    ArgumentOutOfRangeException.ThrowIfNotEqual(arg, ...);
}

And then that does reference equality, not "IEquatable" equality.

Tangent: I'm also of the opinion that ArgumentOutOfRangeException.ThrowIfNotEqual is a bit of a bad API. If you need an argument to be a specific value, just don't ask for it — use the expected value directly.