Add UnitMath.Clamp(value, min, max) (#1157)

* Add UnitMath.Clamp(value, min, max)

* Change Clamp to convert min/max to the unit of value, following the principle of least surprise.

* Update UnitMath.cs

Co-authored-by: Marnix <[email protected]>
Co-authored-by: Andreas Gullberg Larsen <[email protected]>

Author: 3 people

UnitsNet.Tests/UnitMathTests.cs

@@ -318,5 +318,40 @@ public void SumOfLengthsWithSelectorCalculatesCorrectly()
             Assert.Equal(150, sum.Value);
             Assert.Equal(LengthUnit.Centimeter, sum.Unit);
         }
+
+        [Fact]
+        public void ClampCalculatesCorrectly()
+        {
+            var min = Length.FromMeters(-1);
+            var max = Length.FromCentimeters(150);
+
+            var value1 = Length.FromMillimeters(33);
+
+            Length clampedValue = UnitMath.Clamp(value1, min, max);
+            Assert.Equal(33, clampedValue.Value);
+            Assert.Equal(LengthUnit.Millimeter, clampedValue.Unit);
+
+            var value2 = Length.FromMillimeters(-1500);
+
+            Length clampedMin = UnitMath.Clamp(value2, min, max);
+            Assert.Equal(-1000, clampedMin.Value);
+            Assert.Equal(LengthUnit.Millimeter, clampedMin.Unit);
+
+            var value3 = Length.FromMillimeters(2000);
+
+            Length clampedMax = UnitMath.Clamp(value3, min, max);
+            Assert.Equal(1500, clampedMax.Value);
+            Assert.Equal(LengthUnit.Millimeter, clampedMax.Unit);
+        }
+
+        [Fact]
+        public void ClampMinGreaterThanMaxThrowsException()
+        {
+            var min = Length.FromMeters(2);
+            var max = Length.FromCentimeters(150);
+            var value = Length.FromMillimeters(33);
+
+            Assert.Throws<ArgumentException>(() => UnitMath.Clamp(value, min, max));
+        }
     }
 }

UnitsNet/UnitMath.cs

@@ -198,6 +198,47 @@ public static TQuantity Average<TSource, TQuantity>(this IEnumerable<TSource> so
             return source.Select(selector).Average(unitType);
         }
 
+        /// <summary>Returns <paramref name="value" /> clamped to the inclusive range of <paramref name="min" /> and <paramref name="max" />.</summary>
+        /// <param name="value">The value to be clamped.</param>
+        /// <param name="min">The lower bound of the result.</param>
+        /// <param name="max">The upper bound of the result.</param>
+        /// <returns>
+        ///   <paramref name="value" /> if <paramref name="min" /> ≤ <paramref name="value" /> ≤ <paramref name="max" />.
+        ///
+        ///   -or-
+        ///
+        ///   <paramref name="min" /> (converted to value.Unit) if <paramref name="value" /> &lt; <paramref name="min" />.
+        ///
+        ///   -or-
+        ///
+        ///   <paramref name="max" /> (converted to value.Unit) if <paramref name="max" /> &lt; <paramref name="value" />.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        ///     <paramref name="min" /> cannot be greater than <paramref name="max" />.
+        /// </exception>
+        public static TQuantity Clamp<TQuantity>(TQuantity value, TQuantity min, TQuantity max) where TQuantity : IComparable, IQuantity
+        {
+            var minValue = (TQuantity)min.ToUnit(value.Unit);
+            var maxValue = (TQuantity)max.ToUnit(value.Unit);
+            
+            if (minValue.CompareTo(maxValue) > 0)
+            {
+                throw new ArgumentException($"min ({min}) cannot be greater than max ({max})", nameof(min));
+            }
+
+            if (value.CompareTo(minValue) < 0)
+            {
+                return minValue;
+            }
+
+            if (value.CompareTo(maxValue) > 0)
+            {
+                return maxValue;
+            }
+
+            return value;
+        }
+
         /// <summary>
         /// Explicitly create a <see cref="QuantityValue"/> instance from a double
         /// </summary>