feat: add Saturate for floating point types (#60)

CHANGELOG.md

@@ -59,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - X10D: Added `ReadOnlySpan<T>.Split(T)`.
 - X10D: Added `ReadOnlySpan<T>.Split(ReadOnlySpan<T>)`.
 - X10D: Added `RoundUpToPowerOf2()` for built-in integer types.
+- X10D: Added `Saturate()` for built-in floating-point types.
 - X10D: Added `Size.ToPoint()`.
 - X10D: Added `Size.ToPointF()`.
 - X10D: Added `Size.ToVector2()`.

X10D.Tests/src/Math/DecimalTests.cs

@@ -82,6 +82,24 @@ public class DecimalTests
         Assert.AreEqual(10.0m, 7.5m.Round(5));
     }
 
+    [TestMethod]
+    public void Saturate_ShouldClampValueTo1_GivenGreaterThan1()
+    {
+        Assert.AreEqual(1.0m, 1.5m.Saturate(), 1e-6m);
+    }
+
+    [TestMethod]
+    public void Saturate_ShouldClampValueTo0_GivenLessThan0()
+    {
+        Assert.AreEqual(0.0m, (-0.5m).Saturate(), 1e-6m);
+    }
+
+    [TestMethod]
+    public void Saturate_ShouldReturnValue_GivenValueBetween0And1()
+    {
+        Assert.AreEqual(0.5m, 0.5m.Saturate(), 1e-6m);
+    }
+
     [TestMethod]
     public void Sign_ShouldBeMinus1_GivenNegative()
     {

X10D.Tests/src/Math/DoubleTests.cs

@@ -117,6 +117,24 @@ public class DoubleTests
         Assert.AreEqual(10.0, 7.5.Round(5), 1e-6);
     }
 
+    [TestMethod]
+    public void Saturate_ShouldClampValueTo1_GivenGreaterThan1()
+    {
+        Assert.AreEqual(1.0, 1.5.Saturate(), 1e-6);
+    }
+
+    [TestMethod]
+    public void Saturate_ShouldClampValueTo0_GivenLessThan0()
+    {
+        Assert.AreEqual(0.0, (-0.5).Saturate(), 1e-6);
+    }
+
+    [TestMethod]
+    public void Saturate_ShouldReturnValue_GivenValueBetween0And1()
+    {
+        Assert.AreEqual(0.5, 0.5.Saturate(), 1e-6);
+    }
+
     [TestMethod]
     public void Sign_ShouldBeMinus1_GivenNegative()
     {

X10D.Tests/src/Math/SingleTests.cs

@@ -117,6 +117,24 @@ public class SingleTests
         Assert.AreEqual(10.0f, 7.5f.Round(5), 1e-6f);
     }
 
+    [TestMethod]
+    public void Saturate_ShouldClampValueTo1_GivenGreaterThan1()
+    {
+        Assert.AreEqual(1.0f, 1.5f.Saturate(), 1e-6f);
+    }
+
+    [TestMethod]
+    public void Saturate_ShouldClampValueTo0_GivenLessThan0()
+    {
+        Assert.AreEqual(0.0f, (-0.5f).Saturate(), 1e-6f);
+    }
+
+    [TestMethod]
+    public void Saturate_ShouldReturnValue_GivenValueBetween0And1()
+    {
+        Assert.AreEqual(0.5f, 0.5f.Saturate(), 1e-6f);
+    }
+
     [TestMethod]
     public void Sign_ShouldBeMinus1_GivenNegative()
     {

X10D/src/Math/DecimalExtensions.cs

@@ -94,6 +94,23 @@ public static class DecimalExtensions
         return System.Math.Round(value / nearest) * nearest;
     }
 
+    /// <summary>
+    ///     Saturates this decimal number.
+    /// </summary>
+    /// <param name="value">The value to saturate.</param>
+    /// <returns>The saturated value.</returns>
+    /// <remarks>This method clamps <paramref name="value" /> between 0 and 1.</remarks>
+    [Pure]
+#if NETSTANDARD2_1
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#else
+    [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
+#endif
+    public static decimal Saturate(this decimal value)
+    {
+        return System.Math.Clamp(value, 0.0m, 1.0m);
+    }
+
     /// <summary>
     ///     Returns an integer that indicates the sign of this decimal number.
     /// </summary>

X10D/src/Math/DoubleExtensions.cs

@@ -312,6 +312,23 @@ public static class DoubleExtensions
         return System.Math.Round(value / nearest) * nearest;
     }
 
+    /// <summary>
+    ///     Saturates this double-precision floating-point number.
+    /// </summary>
+    /// <param name="value">The value to saturate.</param>
+    /// <returns>The saturated value.</returns>
+    /// <remarks>This method clamps <paramref name="value" /> between 0 and 1.</remarks>
+    [Pure]
+#if NETSTANDARD2_1
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#else
+    [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
+#endif
+    public static double Saturate(this double value)
+    {
+        return System.Math.Clamp(value, 0.0, 1.0);
+    }
+
     /// <summary>
     ///     Returns the sine of the specified angle.
     /// </summary>

X10D/src/Math/SingleExtensions.cs

@@ -312,6 +312,23 @@ public static class SingleExtensions
         return MathF.Round(value / nearest) * nearest;
     }
 
+    /// <summary>
+    ///     Saturates this single-precision floating-point number.
+    /// </summary>
+    /// <param name="value">The value to saturate.</param>
+    /// <returns>The saturated value.</returns>
+    /// <remarks>This method clamps <paramref name="value" /> between 0 and 1.</remarks>
+    [Pure]
+#if NETSTANDARD2_1
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#else
+    [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
+#endif
+    public static float Saturate(this float value)
+    {
+        return System.Math.Clamp(value, 0.0f, 1.0f);
+    }
+
     /// <summary>
     ///     Returns an integer that indicates the sign of this single-precision floating-point number.
     /// </summary>