assert_float_eq

Assertions to check floating-point equality within a user-defined tolerance. Works in both a std and no_std context.

Table Of Contents

Getting Started
Description
Documentation
License
Contributing

Getting Started

First, add assert_float_eq to your Cargo.toml:

[dependencies]
assert_float_eq = "1"

Next, import the macros in lib.rs:

#[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(_)

Description

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_f32_near and 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.

Documentation

assert_float_eq's documentation can be found on docs.rs.

License

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.

Contributing