Added Guard.IsCloseTo and Guard.IsNotCloseTo APIs

Microsoft.Toolkit/Diagnostics/Guard.Comparable.Numeric.cs

@@ -0,0 +1,127 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Runtime.CompilerServices;
+
+#nullable enable
+
+namespace Microsoft.Toolkit.Diagnostics
+{
+    /// <summary>
+    /// Helper methods to verify conditions when running code.
+    /// </summary>
+    public static partial class Guard
+    {
+        /// <summary>
+        /// Asserts that the input value must be within a given distance from a specified value.
+        /// </summary>
+        /// <param name="value">The input <see cref="int"/> value to test.</param>
+        /// <param name="target">The target <see cref="int"/> value to test for.</param>
+        /// <param name="delta">The maximum distance to allow between <paramref name="value"/> and <paramref name="target"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if (<paramref name="value"/> - <paramref name="target"/>) > <paramref name="delta"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsCloseTo(int value, int target, int delta, string name)
+        {
+            /* Cast to long before calculating the difference to avoid overflows
+             * when the values are at the two extremes of the supported range.
+             * Then cast to double to calculate the absolute value: this allows
+             * the JIT compiler to use AVX instructions on X64 CPUs instead of
+             * conditional jumps, which results in more efficient assembly code.
+             * The IEEE 754 specs guarantees that a 32 bit integer value can
+             * be stored within a double precision floating point value with
+             * no loss of precision, so the result will always be correct here. */
+            if (Math.Abs((double)((long)value - target)) > delta)
+            {
+                ThrowHelper.ThrowArgumentExceptionForIsCloseTo(value, target, delta, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the input value must not be within a given distance from a specified value.
+        /// </summary>
+        /// <param name="value">The input <see cref="int"/> value to test.</param>
+        /// <param name="target">The target <see cref="int"/> value to test for.</param>
+        /// <param name="delta">The maximum distance to allow between <paramref name="value"/> and <paramref name="target"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if (<paramref name="value"/> - <paramref name="target"/>) &lt;= <paramref name="delta"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsNotCloseTo(int value, int target, int delta, string name)
+        {
+            if (Math.Abs((double)((long)value - target)) <= delta)
+            {
+                ThrowHelper.ThrowArgumentExceptionForIsNotCloseTo(value, target, delta, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the input value must be within a given distance from a specified value.
+        /// </summary>
+        /// <param name="value">The input <see cref="float"/> value to test.</param>
+        /// <param name="target">The target <see cref="float"/> value to test for.</param>
+        /// <param name="delta">The maximum distance to allow between <paramref name="value"/> and <paramref name="target"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if (<paramref name="value"/> - <paramref name="target"/>) > <paramref name="delta"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsCloseTo(float value, float target, float delta, string name)
+        {
+            if (Math.Abs(value - target) > delta)
+            {
+                ThrowHelper.ThrowArgumentExceptionForIsCloseTo(value, target, delta, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the input value must not be within a given distance from a specified value.
+        /// </summary>
+        /// <param name="value">The input <see cref="float"/> value to test.</param>
+        /// <param name="target">The target <see cref="float"/> value to test for.</param>
+        /// <param name="delta">The maximum distance to allow between <paramref name="value"/> and <paramref name="target"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if (<paramref name="value"/> - <paramref name="target"/>) &lt;= <paramref name="delta"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsNotCloseTo(float value, float target, float delta, string name)
+        {
+            if (Math.Abs(value - target) <= delta)
+            {
+                ThrowHelper.ThrowArgumentExceptionForIsNotCloseTo(value, target, delta, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the input value must be within a given distance from a specified value.
+        /// </summary>
+        /// <param name="value">The input <see cref="double"/> value to test.</param>
+        /// <param name="target">The target <see cref="double"/> value to test for.</param>
+        /// <param name="delta">The maximum distance to allow between <paramref name="value"/> and <paramref name="target"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if (<paramref name="value"/> - <paramref name="target"/>) > <paramref name="delta"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsCloseTo(double value, double target, double delta, string name)
+        {
+            if (Math.Abs(value - target) > delta)
+            {
+                ThrowHelper.ThrowArgumentExceptionForIsCloseTo(value, target, delta, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the input value must not be within a given distance from a specified value.
+        /// </summary>
+        /// <param name="value">The input <see cref="double"/> value to test.</param>
+        /// <param name="target">The target <see cref="double"/> value to test for.</param>
+        /// <param name="delta">The maximum distance to allow between <paramref name="value"/> and <paramref name="target"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if (<paramref name="value"/> - <paramref name="target"/>) &lt;= <paramref name="delta"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsNotCloseTo(double value, double target, double delta, string name)
+        {
+            if (Math.Abs(value - target) <= delta)
+            {
+                ThrowHelper.ThrowArgumentExceptionForIsNotCloseTo(value, target, delta, name);
+            }
+        }
+    }
+}

Microsoft.Toolkit/Diagnostics/ThrowHelper.Comparable.Numeric.cs

@@ -0,0 +1,74 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using Microsoft.Toolkit.Extensions;
+
+#nullable enable
+
+namespace Microsoft.Toolkit.Diagnostics
+{
+    /// <summary>
+    /// Helper methods to throw exceptions
+    /// </summary>
+    [SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1618", Justification = "Internal helper methods")]
+    internal static partial class ThrowHelper
+    {
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.IsCloseTo(int,int,int,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForIsCloseTo(int value, int target, int delta, string name)
+        {
+            ThrowArgumentException(name, $"Parameter {name.ToAssertString()} ({typeof(int).ToTypeString()}) must be within a distance of {delta.ToAssertString()} from {target.ToAssertString()}, was {value.ToAssertString()} and had a distance of {Math.Abs((double)((long)value - target)).ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.IsNotCloseTo(int,int,int,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForIsNotCloseTo(int value, int target, int delta, string name)
+        {
+            ThrowArgumentException(name, $"Parameter {name.ToAssertString()} ({typeof(int).ToTypeString()}) must not be within a distance of {delta.ToAssertString()} from {target.ToAssertString()}, was {value.ToAssertString()} and had a distance of {Math.Abs((double)((long)value - target)).ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.IsCloseTo(float,float,float,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForIsCloseTo(float value, float target, float delta, string name)
+        {
+            ThrowArgumentException(name, $"Parameter {name.ToAssertString()} ({typeof(float).ToTypeString()}) must be within a distance of {delta.ToAssertString()} from {target.ToAssertString()}, was {value.ToAssertString()} and had a distance of {Math.Abs(value - target).ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.IsNotCloseTo(float,float,float,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForIsNotCloseTo(float value, float target, float delta, string name)
+        {
+            ThrowArgumentException(name, $"Parameter {name.ToAssertString()} ({typeof(float).ToTypeString()}) must not be within a distance of {delta.ToAssertString()} from {target.ToAssertString()}, was {value.ToAssertString()} and had a distance of {Math.Abs(value - target).ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.IsCloseTo(double,double,double,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForIsCloseTo(double value, double target, double delta, string name)
+        {
+            ThrowArgumentException(name, $"Parameter {name.ToAssertString()} ({typeof(double).ToTypeString()}) must be within a distance of {delta.ToAssertString()} from {target.ToAssertString()}, was {value.ToAssertString()} and had a distance of {Math.Abs(value - target).ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.IsNotCloseTo(double,double,double,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForIsNotCloseTo(double value, double target, double delta, string name)
+        {
+            ThrowArgumentException(name, $"Parameter {name.ToAssertString()} ({typeof(double).ToTypeString()}) must not be within a distance of {delta.ToAssertString()} from {target.ToAssertString()}, was {value.ToAssertString()} and had a distance of {Math.Abs(value - target).ToAssertString()}");
+        }
+    }
+}