Added math.clamp for slice clamping (#17246)

* Added math.clamp for slice clamping

* Added inline to math.clamp

* Cleaned up math.clamp + test

changelog.md

@@ -22,6 +22,8 @@
 
 - Added `almostEqual` in `math` for comparing two float values using a machine epsilon.
 
+- Added `clamp` in `math` which allows using a `Slice` to clamp to a value.
+
 - The JSON module can now handle integer literals and floating point literals of
   arbitrary length and precision.
   Numbers that do not fit the underlying `BiggestInt` or `BiggestFloat` fields are

lib/pure/math.nim

@@ -1182,6 +1182,16 @@ func lcm*[T](x, y: T): T =
 
   x div gcd(x, y) * y
 
+func clamp*[T](val: T, bounds: Slice[T]): T {.since: (1, 5), inline.} =
+  ## Like `system.clamp`, but takes a slice, so you can easily clamp within a range.
+  runnableExamples:
+    assert clamp(10, 1 .. 5) == 5
+    assert clamp(1, 1 .. 3) == 1
+    type A = enum a0, a1, a2, a3, a4, a5
+    assert a1.clamp(a2..a4) == a2
+    assert clamp((3, 0), (1, 0) .. (2, 9)) == (2, 9)
+  clamp(val, bounds.a, bounds.b)
+
 func lcm*[T](x: openArray[T]): T {.since: (1, 1).} =
   ## Computes the least common multiple of the elements of `x`.
   ##

tests/stdlib/tmath.nim

@@ -358,6 +358,17 @@ template main() =
     doAssert almostEqual(prod([1.5, 3.4]), 5.1)
     let x: seq[float] = @[]
     doAssert prod(x) == 1.0
+  
+  block: # clamp range
+    doAssert clamp(10, 1..5) == 5
+    doAssert clamp(3, 1..5) == 3
+    doAssert clamp(5, 1..5) == 5
+    doAssert clamp(42.0, 1.0 .. 3.1415926535) == 3.1415926535
+    doAssert clamp(NaN, 1.0 .. 2.0).isNaN
+    doAssert clamp(-Inf, -Inf .. -1.0) == -Inf
+    type A = enum a0, a1, a2, a3, a4, a5
+    doAssert a1.clamp(a2..a4) == a2
+    doAssert clamp((3, 0), (1, 0) .. (2, 9)) == (2, 9)
 
   when not defined(windows): # xxx pending bug #17017
     doAssert sqrt(-1.0).isNaN