# float_eq
Compare IEEE floating point primitives, structs and collections for equality.
This crate provides an API with a focus on making the choices of comparison
algorithm(s) and tolerances intuitive to implementers and maintainers, and of
providing clear output for debugging and development iteration.
This readme is a quick tour of the crate. For introductory material, guides and
discussion see [the float_eq guide].
## Usage
Add this to your cargo.toml:
```
[dependencies]
float_eq = "1"
```
And, if you're using the 2015 edition, this to your crate root:
```rust
extern crate float_eq;
```
Then, you can import items with `use`:
```rust
use float_eq::{assert_float_eq, float_eq};
```
## Comparisons
This crate provides boolean comparison operations:
```rust
if (float_eq!(y_pos, 0.0, abs <= 0.000_1)) {
//...
}
```
And asserts:
```rust
const RECIP_REL_TOL: f32 = 0.000_366_210_94;
assert_float_eq!(x.recip(), 10.0, r2nd <= RECIP_REL_TOL);
```
Using absolute tolerance, relative tolerance or ULPs based [comparison
algorithms].
## Composite types
Composite types may implement the provided extension traits to be compared on a
field-by-field basis:
```rust
let a = Complex32 { re: 2.0, im: 4.000_002 };
let b = Complex32 { re: 2.000_000_5, im: 4.0 };
assert_float_eq!(a, b, ulps <= ComplexUlps32 { re: 2, im: 4 });
```
...and if they are homogeneous, with a uniformly applied tolerance across all
fields:
```rust
assert_float_eq!(a, b, ulps_all <= 4);
```
Arrays of any size are supported:
```rust
let a = [1.0, -2.0, 3.0];
let b = [-1.0, 2.0, 3.5];
assert_float_eq!(a, b, abs <= [2.0, 4.0, 0.5]);
assert_float_eq!(a, b, abs_all <= 4.0);
```
As are tuples up to size 12 (inclusive):
```rust
let a = (1.0f32, 2.0f64);
let b = (1.5f32, -2.0f64);
assert_float_eq!(a, b, r2nd <= (0.5, 2.0));
```
Many standard and core types like `Vec` are supported:
```rust
let a = vec![1.0, -2.0, 3.0];
let b = vec![-1.0, 2.0, 3.5];
assert_float_eq!(a, b, rmax <= vec![2.0, 2.0, 0.25]);
assert_float_eq!(a, b, rmax_all <= 2.0);
```
There are blanket trait impls for comparing mutable and immutable reference
types, the contents of `Cell`, `RefCell`, `Rc`, `Arc` and `Box` instances, as
well as for slices, `Option`, `Vec`, `VecDeque`, `LinkedList`, `BTreeMap` and
`HashMap`.
## Derivable
The extension traits may be derived for non-generic structs and tuple structs:
```rust
#[derive_float_eq(
ulps_tol = "PointUlps",
ulps_tol_derive = "Clone, Copy, Debug, PartialEq",
debug_ulps_diff = "PointUlpsDebugUlpsDiff",
debug_ulps_diff_derive = "Clone, Copy, Debug, PartialEq",
all_tol = "f64"
)]
#[derive(Debug, PartialEq, Clone, Copy)]
pub struct Point {
pub x: f64,
pub y: f64,
}
let a = Point { x: 1.0, y: -2.0 };
let c = Point {
x: 1.000_000_000_000_000_9,
y: -2.000_000_000_000_001_3
};
assert_float_eq!(a, c, ulps <= PointUlps { x: 4, y: 3 });
assert_float_eq!(a, c, ulps_all <= 4);
```
## Error messages
Asserts provide additional useful context information. For example:
```rust
assert_float_eq!(4.0f32, 4.000_008, rmax <= 0.000_001);
```
Panics with this error message:
```
thread 'main' panicked at 'assertion failed: `float_eq!(left, right, rmax <= t)`
left: `4.0`,
right: `4.000008`,
abs_diff: `0.000008106232`,
ulps_diff: `Some(17)`,
[rmax] t: `0.000004000008`', assert_failure.rs:15:5
```
Where `[rmax] t` shows the tolerance value that the absolute difference was
compared against after being appropriately scaled.
## Optional features
This crate can be used without the standard library (`#![no_std]`) by disabling
the default `std` feature. Use this in `Cargo.toml`:
```
[dependencies.float_eq]
version = "1"
default-features = false
```
Other optional features:
- **derive** — provides custom derive macros for all traits.
- **num** — blanket trait impls for `num::Complex` where it is instanced with a
compatible type.
## Related efforts
The [`approx`], [`float-cmp`], [`assert_float_eq`] and [`is_close`] crates provide
similar floating point comparison capabilities to `float_eq`. The [`almost`] crate
divides its API into comparison of floats against zero and non-zero values. The
[`efloat`] crate provides an `f32` equivalent type that tracks the maximum
possible error bounds that may have occured due to rounding.
The [`ieee754`] crate is not a comparison library, but provides useful
functionality for decomposing floats into their component parts, iterating over
representable values and working with ULPs directly, amoung other things.
## Contributing
Constructive feedback, suggestions and contributions welcomed, please
[open an issue].
## Changelog
Release information is available in [CHANGELOG.md](CHANGELOG.md).
[comparison algorithms]: https://jtempest.github.io/float_eq-rs/book/background/float_comparison_algorithms.html
[open an issue]: https://github.com/jtempest/float_eq-rs/issues/
[the float_eq guide]: https://jtempest.github.io/float_eq-rs/book/introduction.html
[`almost`]: https://crates.io/crates/almost
[`approx`]: https://crates.io/crates/approx
[`assert_float_eq`]: https://crates.io/crates/assert_float_eq
[`efloat`]: https://crates.io/crates/efloat
[`float-cmp`]: https://crates.io/crates/float-cmp
[`ieee754`]: https://crates.io/crates/ieee754
[`is_close`]: https://docs.rs/is_close/latest/is_close/