Add float.compare_with_tolerance

3 files changed, 44 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6c0a1d4..96a4b31 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- The `float` module gains the `loosely_compare` function.
+
 ## v0.19.3 - 2022-01-14
 
 - Fixed a bug where `io.print` and `io.println` may print unicode characters
diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 3f5399e..2e24f0b 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -69,6 +69,26 @@ pub fn compare(a: Float, with b: Float) -> Order {
   }
 }
 
+/// Compares two `Float`s within a tolerance.
+/// Keep in mind that as this are floats the tolerance won't be exact
+/// e.g. 5.3 - 5.0 is not exactly 0.3 in a float
+///
+/// ## Examples
+///    > loosely_compare(5.0, with: 5.3, tolerating: 0.5)
+///    Eq
+///
+pub fn loosely_compare(
+  a: Float,
+  with b: Float,
+  tolerating tolerance: Float,
+) -> Order {
+  let diff = absolute_value(a -. b)
+  case diff <=. tolerance {
+    True -> order.Eq
+    False -> compare(a, b)
+  }
+}
+
 /// Compares two `Float`s, returning the smaller of the two.
 ///
 /// ## Examples
diff --git a/test/gleam/float_test.gleam b/test/gleam/float_test.gleam
index c7107d9..287dc4b 100644
--- a/test/gleam/float_test.gleam
+++ b/test/gleam/float_test.gleam
@@ -77,6 +77,26 @@ pub fn compare_test() {
   |> should.equal(order.Gt)
 }
 
+pub fn loosely_compare_test() {
+  float.loosely_compare(10.2, 10.5, tolerating: 0.)
+  |> should.equal(order.Lt)
+
+  float.loosely_compare(10.2, with: 10.5, tolerating: 0.31)
+  |> should.equal(order.Eq)
+
+  float.loosely_compare(10.5, 10.2, 0.31)
+  |> should.equal(order.Eq)
+
+  float.loosely_compare(10.2, 10.5, 0.29)
+  |> should.equal(order.Lt)
+
+  float.loosely_compare(10.5, 10.2, 0.29)
+  |> should.equal(order.Gt)
+
+  float.loosely_compare(-10.2, -10.5, 0.31)
+  |> should.equal(order.Eq)
+}
+
 pub fn ceiling_test() {
   8.1
   |> float.ceiling