chore: Added methods ThrowIfEqual and ThrowIfNotEqual (#128)

* chore: Added methods `ThrowIfEqual` and `ThrowIfNotEqual`

* docs: Updated README

* chore(tests): Tests for newly introduced methods added

* chore(tests): Tests for newly introduced method `ThrowIfNull(void*, string?)` added

* docs: Updated README

Author: samtrion

README.md

@@ -5,23 +5,32 @@ Especially intended for projects with multiple `TargetFrameworks`, for usage, st
 ## Method Overview
 The following methods are currently provided.
 
-### ThrowIfGreaterThan
-Compatibility method to [`ArgumentOutOfRangeException.ThrowIfGreaterThan<T>(T, T, String)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwifgreaterthan), which was introduced with .NET 8
+### `Argument.ThrowIfEqual<T>(T, T, string?)`
+Throws an `ArgumentOutOfRangeException` if the first argument is equal to the second argument. Inplace replacement for [`ArgumentOutOfRangeException.ThrowIfEqual<T>(T, T, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwifequal), which was introduced with **.NET 8**.
 
-### ThrowIfGreaterThanOrEqual
-Compatibility method to [`ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual<T>(T, T, String)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwifgreaterthanorequal), which is part of the framework since .NET 8.
+### `Argument.ThrowIfGreaterThan<T>(T, T, string?)`
+Throws an `ArgumentOutOfRangeException` if the first argument is greater than the second argument. Inplace replacement for [`ArgumentOutOfRangeException.ThrowIfGreaterThan<T>(T, T, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwifgreaterthan), which was introduced with **.NET 8**.
 
-### ThrowIfLessThan
-Compatibility method to [`ArgumentOutOfRangeException.ThrowIfLessThan<T>(T, T, String)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwiflessthan), which is part of the framework since .NET 8.
+### `Argument.ThrowIfGreaterThanOrEqual<T>(T, T, string?)`
+Throws an `ArgumentOutOfRangeException` if the first argument is greater than or equal to the second argument. Inplace replacement for [`ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual<T>(T, T, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwifgreaterthanorequal), which was introduced with **.NET 8**.
 
-### ThrowIfLessThanOrEqual
-Compatibility method to [`ArgumentOutOfRangeException.ThrowIfLessThanOrEqual<T>(T, T, String)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwiflessthanorequal), which is part of the framework since .NET 8.
+### `Argument.ThrowIfLessThan<T>(T, T, string?)`
+Throws an `ArgumentOutOfRangeException` if the first argument is less than the second argument. Inplace replacement for [`ArgumentOutOfRangeException.ThrowIfLessThan<T>(T, T, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwiflessthan), which was introduced with **.NET 8**.
 
-### ThrowIfNull
-Compatibility method to [`ArgumentNullException.ThrowIfNull(Object, String)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentnullexception.throwifnull#system-argumentnullexception-throwifnull(system-object-system-string)), which is part of the framework since .NET 8.
+### `Argument.ThrowIfLessThanOrEqual<T>(T, T, string?)`
+Throws an `ArgumentOutOfRangeException` if the first argument is less than or equal to the second argument. Inplace replacement for [`ArgumentOutOfRangeException.ThrowIfLessThanOrEqual<T>(T, T, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwiflessthanorequal), which was introduced with **.NET 8**.
 
-### ThrowIfNullOrEmpty
-Compatibility method to [`ArgumentException.ThrowIfNullOrEmpty(String, String)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentexception.throwifnullorempty), which is part of the framework since .NET 8.
+### `Argument.ThrowIfNotEqual<T>(T, T, string?)`
+Throws an `ArgumentOutOfRangeException` if the first argument is not equal to the second argument. Inplace replacement for [`ArgumentOutOfRangeException.ThrowIfNotEqual<T>(T, T, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentoutofrangeexception.throwifnotequal), which was introduced with **.NET 8**.
 
-### ThrowIfNullOrWhiteSpace
-Compatibility method to [`ArgumentException.ThrowIfNullOrWhiteSpace(String, String)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentexception.throwifnullorwhitespace), which is part of the framework since .NET 8.
+### `Argument.ThrowIfNull(object?, string?)`
+Throws an `ArgumentNullException` if the argument is `null`. Inplace replacement for [`ArgumentNullException.ThrowIfNull(object, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentnullexception.throwifnull), which was introduced with **.NET 6**.
+
+### `Argument.ThrowIfNull(void*, string?)`
+Throws an `ArgumentNullException` if the argument is `null`. Inplace replacement for [`ArgumentNullException.ThrowIfNull(void*, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentnullexception.throwifnull?view=net-8.0#system-argumentnullexception-throwifnull(system-void*-system-string), which was introduced with **.NET 7**.
+
+### `Argument.ThrowIfNullOrEmpty(string?, string?)`
+Throws an `ArgumentNullException` if the argument is `null` or throws an `ArgumentException` if the argument is empty. Inplace replacement for [`ArgumentException.ThrowIfNullOrEmpty(string, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentexception.throwifnullorempty), which was introduced with **.NET 7**.
+
+### `Argument.ThrowIfNullOrWhiteSpace(string?, string?)`
+Throws an `ArgumentNullException` if the argument is `null` or throws an `ArgumentException` if the argument is empty or contains only white-space characters. Inplace replacement for [`ArgumentException.ThrowIfNullOrWhiteSpace(string, string)`](https://learn.microsoft.com/en-us/dotnet/api/system.argumentexception.throwifnullorwhitespace), which was introduced with **.NET 8**.

src/NetEvolve.Arguments/Argument_ThrowArgumentException.cs

@@ -12,9 +12,9 @@ public static partial class Argument
     [DoesNotReturn]
     [MethodImpl(MethodImplOptions.NoInlining)]
     [StackTraceHidden]
-    private static void ThrowArgumentException(string? paramName)
+    private static void ThrowArgumentException(string? paramName, string? message = null)
     {
-        throw new ArgumentException(null, paramName);
+        throw new ArgumentException(message, paramName);
     }
 }
 #endif

src/NetEvolve.Arguments/Argument_ThrowArgumentNullException.cs

@@ -12,9 +12,9 @@ public static partial class Argument
     [DoesNotReturn]
     [MethodImpl(MethodImplOptions.NoInlining)]
     [StackTraceHidden]
-    private static void ThrowArgumentNullException(string? paramName)
+    private static void ThrowArgumentNullException(string? paramName, string? message = null)
     {
-        throw new ArgumentNullException(paramName);
+        throw new ArgumentNullException(paramName, message);
     }
 }
 #endif

src/NetEvolve.Arguments/Argument_ThrowArgumentOutOfRangeException.cs

@@ -12,10 +12,13 @@ public static partial class Argument
     [DoesNotReturn]
     [MethodImpl(MethodImplOptions.NoInlining)]
     [StackTraceHidden]
-    private static void ThrowArgumentOutOfRangeException<T>(string? paramName, T value)
-        where T : IComparable<T>
+    private static void ThrowArgumentOutOfRangeException<T>(
+        string? paramName,
+        T value,
+        string? message = null
+    )
     {
-        throw new ArgumentOutOfRangeException(paramName, value, null);
+        throw new ArgumentOutOfRangeException(paramName, value, message);
     }
 }
 #endif

src/NetEvolve.Arguments/Argument_ThrowIfEqual.cs

@@ -0,0 +1,41 @@
+namespace NetEvolve.Arguments;
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+public static partial class Argument
+{
+    /// <summary>Throws an <see cref="ArgumentOutOfRangeException"/> if <paramref name="value"/> is equal to <paramref name="other"/>.</summary>
+    /// <param name="value">The argument to validate as not equal to <paramref name="other"/>.</param>
+    /// <param name="other">The value to compare with <paramref name="value"/>.</param>
+    /// <param name="paramName">The name of the parameter with which <paramref name="value"/> corresponds.</param>
+    [DebuggerStepThrough]
+    [StackTraceHidden]
+#if NET8_0_OR_GREATER
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#else
+    [MethodImpl(MethodImplOptions.NoInlining)]
+#endif
+    public static void ThrowIfEqual<T>(
+        T value,
+        T other,
+        [CallerArgumentExpression(nameof(value))] string? paramName = null
+    )
+        where T : IEquatable<T>
+    {
+#if NET8_0_OR_GREATER
+        ArgumentOutOfRangeException.ThrowIfEqual(value, other, paramName);
+#else
+        if (EqualityComparer<T>.Default.Equals(value, other))
+        {
+            ThrowArgumentOutOfRangeException(
+                paramName,
+                value,
+                $"{paramName} ('{value}') must not be equal to '{other}'."
+            );
+        }
+#endif
+    }
+}

src/NetEvolve.Arguments/Argument_ThrowIfGreaterThan.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
 using System.Runtime.CompilerServices;
 
 public static partial class Argument
@@ -30,7 +31,11 @@ public static void ThrowIfGreaterThan<T>(
 #else
         if (value.CompareTo(other) > 0)
         {
-            ThrowArgumentOutOfRangeException(paramName, value);
+            ThrowArgumentOutOfRangeException(
+                paramName,
+                value,
+                $"{paramName} ('{value}') must be less than or equal to '{other}'."
+            );
         }
 #endif
     }

src/NetEvolve.Arguments/Argument_ThrowIfGreaterThanOrEqual.cs

@@ -29,7 +29,11 @@ public static void ThrowIfGreaterThanOrEqual<T>(
 #else
         if (value.CompareTo(other) >= 0)
         {
-            ThrowArgumentOutOfRangeException(paramName, value);
+            ThrowArgumentOutOfRangeException(
+                paramName,
+                value,
+                $"{paramName} ('{value}') must be less than '{other}'."
+            );
         }
 #endif
     }

src/NetEvolve.Arguments/Argument_ThrowIfLessThan.cs

@@ -29,7 +29,11 @@ public static void ThrowIfLessThan<T>(
 #else
         if (value.CompareTo(other) < 0)
         {
-            ThrowArgumentOutOfRangeException(paramName, value);
+            ThrowArgumentOutOfRangeException(
+                paramName,
+                value,
+                $"{paramName} ('{value}') must be greater than '{other}'."
+            );
         }
 #endif
     }

src/NetEvolve.Arguments/Argument_ThrowIfLessThanOrEqual.cs

@@ -29,7 +29,11 @@ public static void ThrowIfLessThanOrEqual<T>(
 #else
         if (value.CompareTo(other) <= 0)
         {
-            ThrowArgumentOutOfRangeException(paramName, value);
+            ThrowArgumentOutOfRangeException(
+                paramName,
+                value,
+                $"{paramName} ('{value}') must be greater than or equal to '{other}'."
+            );
         }
 #endif
     }

src/NetEvolve.Arguments/Argument_ThrowIfNotEqual.cs

@@ -0,0 +1,41 @@
+namespace NetEvolve.Arguments;
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+public static partial class Argument
+{
+    /// <summary>Throws an <see cref="ArgumentOutOfRangeException"/> if <paramref name="value"/> is not equal to <paramref name="other"/>.</summary>
+    /// <param name="value">The argument to validate as equal to <paramref name="other"/>.</param>
+    /// <param name="other">The value to compare with <paramref name="value"/>.</param>
+    /// <param name="paramName">The name of the parameter with which <paramref name="value"/> corresponds.</param>
+    [DebuggerStepThrough]
+    [StackTraceHidden]
+#if NET8_0_OR_GREATER
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#else
+    [MethodImpl(MethodImplOptions.NoInlining)]
+#endif
+    public static void ThrowIfNotEqual<T>(
+        T value,
+        T other,
+        [CallerArgumentExpression(nameof(value))] string? paramName = null
+    )
+        where T : IEquatable<T>
+    {
+#if NET8_0_OR_GREATER
+        ArgumentOutOfRangeException.ThrowIfNotEqual(value, other, paramName);
+#else
+        if (!EqualityComparer<T>.Default.Equals(value, other))
+        {
+            ThrowArgumentOutOfRangeException(
+                paramName,
+                value,
+                $"{paramName} ('{value}') must be equal to '{other}'."
+            );
+        }
+#endif
+    }
+}