[API Proposal]: ArgumentException helper methods #77749
Description
EDIT 5/1/2023 by @stephentoub
The proposal suggested four methods:
- ThrowIfNullOrWhitespace(string, ...)
- ThrowIfNullOrEmpty(string, ...)
- ThrowIfNullOrEmpty(IEnumerable, ...)
- ThrowIfBufferTooSmall(int, int, ...)
The second already exists, the third is too expensive in its proposed form, and more validation would be needed on the fourth to conclude exactly what form it would take (e.g. someone trying it across .NET runtime and seeing what issues we might hit).
As such, I'm narrowing this down to just the first (which we've previously considered and rejected, but we've since received enough +1s that it's worth reconsidering):
public class ArgumentException
{
// existing
public static void ThrowIfNullOrEmpty([NotNull] string? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null);
+ public static void ThrowIfNullOrWhiteSpace([NotNull] string? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null);
}To discuss:
- The proposal recommended returning the string argument. We've not done that in the other helpers we added. It didn't make sense for the non-generic ThrowIfNull, but it could be done in the other helpers we've added new in this release. Folks ask for it in order to save a line of code, using the method as part of an expression.
Background and motivation
#69590 describes adding helper methods to ArgumentOutOfRangeException, which is terrific. But there are a few more common helper methods that we use our source base which would be generally useful.
API Proposal
namespace System.;
public class ArgumentException
{
/// <summary>
/// Throws either an <see cref="System.ArgumentNullException"/> or an <see cref="System.ArgumentException"/>
/// if the specified string is <see langword="null"/> or whitespace respectively.
/// </summary>
/// <param name="argument">String to be checked for <see langword="null"/> or whitespace.</param>
/// <param name="paramName">The name of the parameter being checked.</param>
/// <returns>The original value of <paramref name="argument"/>.</returns>
[return: NotNull]
public static string ThrowIfNullOrWhitespace([NotNull] string? argument, [CallerArgumentExpression("argument")] string paramName = "");
/// <summary>
/// Throws an <see cref="System.ArgumentNullException"/> if the string is <see langword="null"/>,
/// or <see cref="System.ArgumentException"/> if it is empty.
/// </summary>
/// <param name="argument">String to be checked for <see langword="null"/> or empty.</param>
/// <param name="paramName">The name of the parameter being checked.</param>
/// <returns>The original value of <paramref name="argument"/>.</returns>
[return: NotNull]
public static string ThrowIfNullOrEmpty([NotNull] string? argument, [CallerArgumentExpression("argument")] string paramName = "");
/// <summary>
/// Throws an <see cref="System.ArgumentNullException"/> if the collection is <see langword="null"/>,
/// or <see cref="System.ArgumentException"/> if it is empty.
/// </summary>
/// <param name="argument">The collection to evaluate.</param>
/// <param name="paramName">The name of the parameter being checked.</param>
/// <typeparam name="T">The type of objects in the collection.</typeparam>
/// <returns>The original value of <paramref name="argument"/>.</returns>
[return: NotNull]
public static IEnumerable<T> ThrowIfNullOrEmpty<T>([NotNull] IEnumerable<T>? argument, [CallerArgumentExpression("argument")] string paramName = "");
/// <summary>
/// Throws an <see cref="System.ArgumentException"/> if the argument's buffer size is less than the required buffer size.
/// </summary>
/// <param name="bufferSize">The actual buffer size.</param>
/// <param name="requiredSize">The required buffer size.</param>
/// <param name="paramName">The name of the parameter to be checked.</param>
public static void ThrowIfBufferTooSmall(int bufferSize, int requiredSize, string paramName = "");
}API Usage
ArgumentException.ThrowIfBufferTooSmall(destination.Length, source.Length);Alternative Designs
No response
Risks
No response