[API Proposal]: Add `ArgumentOutOfRangeException.ThrowIfNotZero`

[xtqqczze]

Background and motivation

We already have ArgumentOutOfRangeException.ThrowIfZero.

API Proposal

public class ArgumentOutOfRangeException : ArgumentException
{
  public static void ThrowIfZero<T>(T value, [CallerArgumentExpression(nameof(value))] string? paramName = null)
    where T : INumberBase<T>
  {
    if (!T.IsZero(value))
      ThrowNotZero(paramName, value);
  }
}

API Usage

internal sealed class SingleItemReadOnlyList : IList
{
  private readonly object? _item;
  
  public SingleItemReadOnlyList(object? item) => _item = item;
  
  public object? this[int index]
  {
    get
    {
      ArgumentOutOfRangeException.ThrowIfNotZero(index);
      return _item;
    }
  }
}

Alternative Designs

No response

Risks

No response

[stephentoub]

Is this really common enough that ThrowIfEqual(..., 0) is insufficient?

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

We already have ArgumentOutOfRangeException.ThrowIfZero.

API Proposal

public class ArgumentOutOfRangeException : ArgumentException
{
  public static void ThrowIfZero<T>(T value, [CallerArgumentExpression(nameof(value))] string? paramName = null)
    where T : INumberBase<T>
  {
    if (!T.IsZero(value))
      ThrowNotZero(paramName, value);
  }
}

API Usage

internal sealed class SingleItemReadOnlyList : IList
{
  private readonly object? _item;
  
  public SingleItemReadOnlyList(object? item) => _item = item;
  
  public object? this[int index]
  {
    get
    {
      ArgumentOutOfRangeException.ThrowIfNotZero(index);
      return _item;
    }
  }
}

Alternative Designs

No response

Risks

No response

Author:	xtqqczze
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged, needs-area-label
Milestone:	-

[RenderMichael]

If the parameter cannot be anything other than INumberBase<TSelf>.Zero, why would you need to pass it in? Sounds like a const value

[xtqqczze]

cc: @tannergooding
terrafx/terrafx#84bb30f13981d19a824d69f0db320fb02810fbb3/sources/Core/Utilities/ExceptionUtilities.ThrowIf.cs#L380

cc: @Sergio0694
Sergio0694/ComputeSharp#78c5ae0e6ce8acfa6c5760ade8aee997fe7089f8/src/ComputeSharp.Core/Polyfills/ArgumentOutOfRangeExceptionExtensions.cs#L18

[tannergooding]

I use it in TerraFX for 4 places. Those specifically involve cases like public UnmanagedSpan(UnmanagedArray<T> array, nuint start) where if array is "null", then start must be 0. Any other input for start is likely a developer error.

This is a very niche scenario and easily covered by ThrowIfNotEqual(x, 0)

[Sergio0694]

Same for me, I only use it in very few cases. For me it's just 2 cases in all of ComputeSharp (specifically in two custom MemoryManager<T> implementations that require the elementIndex parameter passed to Pin to always be 0.

I agree this it's a critical feature to add (plus people can easily add this by using a static extension in C# 12).
Not saying we necessarily shouldn't add it, just that I agree its use cases would be pretty limited.

[stephentoub]

Closing for the reasons cited.