Add ieee_float.clamp

src/ieee_float.gleam

@@ -70,8 +70,8 @@ pub fn is_nan(f: IEEEFloat) -> Bool {
   f == NaN
 }
 
-/// Converts the `IEEEFloat` to a finite value of the native `Float` type. If
-/// the IEEE float is infinite or `NaN` then `fallback` is returned.
+/// Converts an `IEEEFloat` to a finite value of the native `Float` type. If
+/// the `IEEEFloat` is infinite or `NaN` then `fallback` is returned.
 ///
 @external(javascript, "./ieee_float_js.mjs", "to_finite")
 pub fn to_finite(f: IEEEFloat, fallback: Float) -> Float {
@@ -284,6 +284,18 @@ pub fn ceiling(f: IEEEFloat) -> IEEEFloat {
   }
 }
 
+/// Restricts an `IEEEFloat` between a lower and upper bound.
+///
+pub fn clamp(
+  f: IEEEFloat,
+  min min_bound: IEEEFloat,
+  max max_bound: IEEEFloat,
+) -> IEEEFloat {
+  f
+  |> min(max_bound)
+  |> max(min_bound)
+}
+
 /// Compares two `IEEEFloats`, returning an `Order`: `Lt` for lower than, `Eq`
 /// for equals, or `Gt` for greater than. If either value is `NaN` then
 /// `Error(Nil)` is returned.

test/ieee_float_test.gleam

@@ -327,6 +327,39 @@ pub fn ceiling_test() {
   |> expect.to_equal(negative_infinity())
 }
 
+pub fn clamp_test() {
+  ieee_float.clamp(finite(1.4), min: finite(1.3), max: finite(1.5))
+  |> expect.to_equal(finite(1.4))
+
+  ieee_float.clamp(finite(1.2), min: finite(1.3), max: finite(1.5))
+  |> expect.to_equal(finite(1.3))
+
+  ieee_float.clamp(finite(1.6), min: finite(1.3), max: finite(1.5))
+  |> expect.to_equal(finite(1.5))
+
+  ieee_float.clamp(
+    finite(1.6),
+    min: positive_infinity(),
+    max: positive_infinity(),
+  )
+  |> expect.to_equal(positive_infinity())
+
+  ieee_float.clamp(
+    finite(1.6),
+    min: negative_infinity(),
+    max: negative_infinity(),
+  )
+  |> expect.to_equal(negative_infinity())
+
+  ieee_float.clamp(nan(), min: finite(0.0), max: finite(0.0))
+  |> ieee_float.is_nan
+  |> expect.to_be_true
+
+  ieee_float.clamp(finite(0.0), min: nan(), max: finite(100.0))
+  |> ieee_float.is_nan
+  |> expect.to_be_true
+}
+
 pub fn compare_test() {
   ieee_float.compare(finite(1.0), finite(1.0))
   |> expect.to_equal(Ok(order.Eq))