Add Wrap extension for double and float

PowerKit.Tests/Extensions/DoubleExtensionsTests.cs

@@ -27,4 +27,17 @@ public void ParseOrDefault_Test()
         double.ParseOrDefault("abc", -1.0).Should().Be(-1.0);
         double.ParseOrDefault(null).Should().Be(0.0);
     }
+
+    [Fact]
+    public void Wrap_Test()
+    {
+        // Act & assert
+        5.0.Wrap(0.0, 10.0).Should().Be(5.0);
+        13.0.Wrap(0.0, 10.0).Should().Be(3.0);
+        (-3.0).Wrap(0.0, 10.0).Should().Be(7.0);
+        (-10.0).Wrap(0.0, 10.0).Should().Be(0.0);
+        0.0.Wrap(0.0, 10.0).Should().Be(0.0);
+        10.0.Wrap(0.0, 10.0).Should().Be(0.0);
+        23.0.Wrap(0.0, 10.0).Should().Be(3.0);
+    }
 }

PowerKit.Tests/Extensions/SingleExtensionsTests.cs

@@ -31,4 +31,17 @@ public void ParseOrDefault_Test()
         float.ParseOrDefault("abc", -1.0f).Should().Be(-1.0f);
         float.ParseOrDefault(null).Should().Be(0.0f);
     }
+
+    [Fact]
+    public void Wrap_Test()
+    {
+        // Act & assert
+        5.0f.Wrap(0.0f, 10.0f).Should().Be(5.0f);
+        13.0f.Wrap(0.0f, 10.0f).Should().Be(3.0f);
+        (-3.0f).Wrap(0.0f, 10.0f).Should().Be(7.0f);
+        (-10.0f).Wrap(0.0f, 10.0f).Should().Be(0.0f);
+        0.0f.Wrap(0.0f, 10.0f).Should().Be(0.0f);
+        10.0f.Wrap(0.0f, 10.0f).Should().Be(0.0f);
+        23.0f.Wrap(0.0f, 10.0f).Should().Be(3.0f);
+    }
 }

PowerKit/Extensions/DoubleExtensions.cs

@@ -66,4 +66,31 @@ public static double ParseOrDefault(
         public static double ParseOrDefault(string? str, double defaultValue = default) =>
             double.ParseOrDefault(str, CultureInfo.CurrentCulture, defaultValue);
     }
+
+    extension(double value)
+    {
+        /// <summary>
+        /// Wraps the value into the half-open range [<paramref name="min" />, <paramref name="max" />).
+        /// A value equal to <paramref name="max" /> wraps to <paramref name="min" />.
+        /// </summary>
+        /// <param name="min">The inclusive lower bound of the range.</param>
+        /// <param name="max">The exclusive upper bound of the range.</param>
+        /// <remarks>
+        /// This method requires <paramref name="max" /> to be greater than <paramref name="min" />.
+        /// If <paramref name="max" /> is less than or equal to <paramref name="min" />, the behavior is invalid.
+        /// </remarks>
+        public double Wrap(double min, double max)
+        {
+            if (max <= min)
+            {
+                throw new ArgumentOutOfRangeException(
+                    nameof(max),
+                    "The maximum value must be greater than the minimum value."
+                );
+            }
+
+            var range = max - min;
+            return min + (((value - min) % range + range) % range);
+        }
+    }
 }

PowerKit/Extensions/SingleExtensions.cs

@@ -66,4 +66,31 @@ public static float ParseOrDefault(
         public static float ParseOrDefault(string? str, float defaultValue = default) =>
             float.ParseOrDefault(str, CultureInfo.CurrentCulture, defaultValue);
     }
+
+    extension(float value)
+    {
+        /// <summary>
+        /// Wraps the value into the half-open range [<paramref name="min" />, <paramref name="max" />),
+        /// cycling it back around when it exceeds the bounds.
+        /// </summary>
+        /// <remarks>
+        /// The returned value is greater than or equal to <paramref name="min" /> and less than
+        /// <paramref name="max" /> for valid ranges. A value equal to <paramref name="max" />
+        /// wraps to <paramref name="min" />.
+        /// When <paramref name="max" /> is less than or equal to <paramref name="min" />, this
+        /// method does not throw; it follows floating-point arithmetic and may return
+        /// <see cref="float.NaN" />.
+        /// </remarks>
+        public float Wrap(float min, float max)
+        {
+            if (max <= min)
+            {
+                throw new ArgumentOutOfRangeException(nameof(max), "max must be greater than min.");
+            }
+
+            var range = max - min;
+            var normalized = ((value - min) % range + range) % range;
+            return min + normalized;
+        }
+    }
 }