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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
// Copyright 2014-2018 Optimal Computing (NZ) Ltd.
// Licensed under the MIT license. See LICENSE for details.
//! # float-cmp
//!
//! float-cmp 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 go-to 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":
//!
//! ```should_panic
//! # extern crate float_cmp;
//! # use float_cmp::ApproxEq;
//! # fn main() {
//! 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:
//!
//! ```
//! # #[macro_use]
//! # extern crate float_cmp;
//! # use float_cmp::{ApproxEq, F32Margin};
//! # fn main() {
//! let a: f32 = 0.15 + 0.15 + 0.15;
//! let b: f32 = 0.1 + 0.1 + 0.25;
//! println!("{} == {}", a, b);
//! // They are equal, within 2 ulps
//! 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 epsilon-based 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:
//!
//! ```
//! # extern crate float_cmp;
//! # use float_cmp::{ApproxEq, F32Margin};
//! # fn main() {
//! # let a: f32 = 0.15 + 0.15 + 0.15;
//! # let b: f32 = 0.1 + 0.1 + 0.25;
//! 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:
//!
//! ```
//! # extern crate float_cmp;
//! # use float_cmp::{ApproxEq, F32Margin};
//! # fn main() {
//! # let a: f32 = 0.15 + 0.15 + 0.15;
//! # let b: f32 = 0.1 + 0.1 + 0.25;
//! 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:
//!
//! ```
//! # #[macro_use]
//! # extern crate float_cmp;
//! # use float_cmp::{ApproxEq, F32Margin};
//! # fn main() {
//! # let a: f32 = 0.15 + 0.15 + 0.15;
//! # let b: f32 = 0.1 + 0.1 + 0.25;
//! 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.
//!
//! ```
//! use float_cmp::ApproxEq;
//!
//! pub struct Vec2<F> {
//! pub x: F,
//! pub y: F,
//! }
//!
//! impl<'a, M: Copy + Default, 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 floating-point types
//!
//! `ApproxEq` can be implemented for non floating-point 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/comparing-floating-point-numbers-2012-edition/](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/)
#[cfg(feature="num-traits")]
extern crate num_traits;
#[macro_use]
mod macros;
pub fn trials() {
println!("are they approximately equal?: {:?}",
approx_eq!(f32, 1.0, 1.0000001));
}
mod ulps;
pub use self::ulps::Ulps;
mod ulps_eq;
pub use self::ulps_eq::ApproxEqUlps;
mod eq;
pub use self::eq::{ApproxEq, F32Margin, F64Margin};
#[cfg(feature="num-traits")]
mod ratio;
#[cfg(feature="num-traits")]
pub use self::ratio::ApproxEqRatio;
|
