2 stable releases
|1.0.1||Oct 31, 2018|
#31 in #float
2 downloads per month
Assertions to check floating-point equality within a user-defined tolerance. Works in both a
Table Of Contents
First, add assert_float_eq to your
[dependencies] assert_float_eq = "1"
Next, import the macros in
#[macro_use] extern crate assert_float_eq;
Finally, use the assertions like any other rust assertions:
assert_float_absolute_eq!(3.0, 4.0, 1.0); // 4.0-3.0 <= 1.0 assert_float_relative_eq!(4.0, 3.9, 0.03); // (4.0-3.0) / 4.0 <= 0.3 assert_f32_near!(1.0e-45, 7.0e-45, 4); // exactly 4 steps away assert_f64_near!(5.0e-324, 2.5e-323, 4); // exactly 4 steps away
When softer error handling is desired, assert_float_eq also includes "expectations", which return a
Result<(), T: Display>, indicating whether the comparison was successful:
expect_float_absolute_eq!(3.0, 4.0, 1.0); // Ok(_) expect_float_absolute_eq!(3.0, 4.0, 0.9); // Err(_) expect_float_relative_eq!(4.0, 3.9, 0.03); // Ok(_) expect_float_relative_eq!(4.0, 3.9, 0.02); // Err(_) expect_f32_near!(1.0e-45, 7.0e-45, 4); // Ok(_) expect_f32_near!(1.0e-45, 7.0e-45, 3); // Err(_) expect_f64_near!(5.0e-324, 2.5e-323, 4); // Ok(_) expect_f64_near!(5.0e-324, 2.5e-323, 3); // Err(_)
assert_float_eq exports 4 macros, each of which provides a different heuristic for comparing floating-point numbers.
assert_float_absolute_eq compares to values such that the absolute value of the difference between the floats is less than epsilon (default 1e-6), or
| a - b | < epsilon. This is the easiest-to-understand macro, since it ensures the difference between two floats is below some fixed threshold. However, for very small or large floats, absolute comparisons can lead to faulty comparisons, since the error tolerance does not scale with float precision.
assert_float_relative_eq compares to values such that the relative value of the difference between the floats is less than epsilon (default 1e-6), or
(| a - b | / max(|a|, |b|) < epsilon`. This is another easy-to-understand macro, and works well with large floats, however, it fails for small (denormal) floats, especially 0. For example, the relative error between 1e-45 and 3e-45 is ~67%, despite there being no 32-bit representation between them.
assert_f64_near ensure two floats are within a number of steps of each other, by default, 4. A stepwise comparison scales for all floating-point values, despite being counter-intuitive initially. A step corresponds to a direct increment/decrement of the underlying bits of the float, as if they were a signed integer. For example, for a 32-bit float, it takes ~1e9 steps to go from 0.0 to 1e-6, however, each step for a float with a value of 3e37 increments the float by ~3e30.
Each of the
assert_* macros also comes in an
expect_* variant, which returns a Result indicating if the comparison was successful.
assert_float_eq's documentation can be found on docs.rs.
assert_float_eq is dual licensed under the Apache 2.0 license as well as the MIT license. See the LICENCE-MIT and the LICENCE-APACHE files for the licenses.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in assert_float_eq by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.