1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143

# floatcmp
[![Build Status](https://travisci.org/mikedilger/floatcmp.svg?branch=master)](https://travisci.org/mikedilger/floatcmp)
[![MIT licensed](https://img.shields.io/badge/licenseMITblue.svg)](./LICENSE)
Documentation is available at https://docs.rs/floatcmp
floatcmp defines and implements traits for approximate comparison of floating point types
which have fallen away from exact equality due to the limited precision available within
floating point representations. Implementations of these traits are provided for `f32`
and `f64` types.
When I was a kid in the '80s, the programming rule was "Never compare floating point
numbers". If you can follow that rule and still get the outcome you desire, then more
power to you. However, if you really do need to compare them, this crate provides a
reasonable way to do so.
Another crate `efloat` offers another solution by providing a floating point type that
tracks its error bounds as operations are performed on it, and thus can implement the
`ApproxEq` trait in this crate more accurately, without specifying a `Margin`.
The recommended goto solution (although it may not be appropriate in all cases) is the
`approx_eq()` function in the `ApproxEq` trait (or better yet, the macros). For `f32`
and `f64`, the `F32Margin` and `F64Margin` types are provided for specifying margins as
both an epsilon value and an ULPs value, and defaults are provided via `Default`
(although there is no perfect default value that is always appropriate, so beware).
Several other traits are provided including `Ulps`, `ApproxEqUlps`, `ApproxOrdUlps`, and
`ApproxEqRatio`.
## The problem
Floating point operations must round answers to the nearest representable number. Multiple
operations may result in an answer different from what you expect. In the following example,
the assert will fail, even though the printed output says "0.45 == 0.45":
```rust
let a: f32 = 0.15 + 0.15 + 0.15;
let b: f32 = 0.1 + 0.1 + 0.25;
println!("{} == {}", a, b);
assert!(a==b) // Fails, because they are not exactly equal
```
This fails because the correct answer to most operations isn't exactly representable, and so
your computer's processor chooses to represent the answer with the closest value it has
available. This introduces error, and this error can accumulate as multiple operations are
performed.
## The solution
With `ApproxEq`, we can get the answer we intend:
```rust
let a: f32 = 0.15 + 0.15 + 0.15;
let b: f32 = 0.1 + 0.1 + 0.25;
println!("{} == {}", a, b);
assert!( approx_eq!(f32, a, b, ulps = 2) );
```
## Some explanation
We use the term ULP (units of least precision, or units in the last place) to mean the
difference between two adjacent floating point representations (adjacent meaning that there is
no floating point number between them). This term is borrowed from prior work (personally I
would have chosen "quanta"). The size of an ULP (measured as a float) varies
depending on the exponents of the floating point numbers in question. That is a good thing,
because as numbers fall away from equality due to the imprecise nature of their representation,
they fall away in ULPs terms, not in absolute terms. Pure epsilonbased comparisons are
absolute and thus don't map well to the nature of the additive error issue. They work fine
for many ranges of numbers, but not for others (consider comparing 0.0000000028
to +0.00000097).
## Using this crate
You can use the `ApproxEq` trait directly like so:
```rust
assert!( a.approx_eq(b, F32Margin { ulps: 2, epsilon: 0.0 }) );
```
We have implemented `From<(f32,i32)>` for `F32Margin` (and similarly for `F64Margin`)
so you can use this shorthand:
```rust
assert!( a.approx_eq(b, (0.0, 2)) );
```
With macros, it is easier to be explicit about which type of margin you wish to set,
without mentioning the other one (the other one will be zero). But the downside is
that you have to specify the type you are dealing with:
```rust
assert!( approx_eq!(f32, a, b, ulps = 2) );
assert!( approx_eq!(f32, a, b, epsilon = 0.00000003) );
assert!( approx_eq!(f32, a, b, epsilon = 0.00000003, ulps = 2) );
assert!( approx_eq!(f32, a, b, (0.0, 2)) );
assert!( approx_eq!(f32, a, b, F32Margin { epsilon: 0.0, ulps: 2 }) );
assert!( approx_eq!(f32, a, b, F32Margin::default()) );
assert!( approx_eq!(f32, a, b) ); // uses the default
```
For most cases, I recommend you use a smallish integer for the `ulps` parameter (1 to 5
or so), and a similar small multiple of the floating point's EPSILON constant (1.0 to 5.0
or so), but there are *plenty* of cases where this is insufficient.
## Implementing these traits
You can implement `ApproxEq` for your own complex types like shown below.
The floating point type `F` must be `Copy`, but for large types you can implement
it for references to your type as shown.
```rust
use float_cmp::ApproxEq;
pub struct Vec2<F> {
pub x: F,
pub y: F,
}
impl<'a, M: Copy, F: Copy + ApproxEq<Margin=M>> ApproxEq for &'a Vec2<F> {
type Margin = M;
fn approx_eq<T: Into<Self::Margin>>(self, other: Self, margin: T) > bool {
let margin = margin.into();
self.x.approx_eq(other.x, margin)
&& self.y.approx_eq(other.y, margin)
}
}
```
## Non floatingpoint types
`ApproxEq` can be implemented for non floatingpoint types as well, since `Margin` is
an associated type.
The `efloat` crate implements (or soon will implement) `ApproxEq` for a compound type
that tracks floating point error bounds by checking if the error bounds overlap.
In that case `type Margin = ()`.
## Inspiration
This crate was inspired by this Random ASCII blog post:
[https://randomascii.wordpress.com/2012/02/25/comparingfloatingpointnumbers2012edition/](https://randomascii.wordpress.com/2012/02/25/comparingfloatingpointnumbers2012edition/)
