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

//! Compare IEEE floating point primitives, structs and collections for equality.
//!
//! This is API reference documentation. For introductory material, guides and
//! discussion see [the float_eq guide].
//!
//! # Basic usage
//!
//! This crate provides boolean comparisons via [`float_eq!`] and [`float_ne!`]:
//!
//! ```
//! use float_eq::float_eq;
//!
//! # let y_pos = 0.000_1;
//! if (float_eq!(y_pos, 0.0, abs <= 0.000_1)) {
//!    //...
//! }
//! ```
//!
//! And asserts via [`assert_float_eq!`] and [`assert_float_ne!`]:
//!
//! ```
//! use float_eq::assert_float_eq;
//!
//! const TOL: f32 = 0.000_366_210_94;
//! assert_float_eq!(0.1f32.recip(), 10.0, r2nd <= TOL);
//! ```
//!
//! Each of which invokes a specific comparison algorithm with an explictly
//! provided toelrance. In these examples:
//!
//! - `abs <= 0.000_1` is an absolute tolerance comparison with a tolerance of `0.000_1`.
//! - `r2nd <= TOL` is a relative tolerance comparison with a tolerance of `TOL`,
//!   scaled to the precision of the second operand.
//!
//! # Comparison algorithms
//!
//! These are always of the form `CHECK <= tol`, where `CHECK` is one of:
//!
//! - `abs`: an [absolute tolerance comparison].
//! - `rmax`: a [relative tolerance comparison], scaled to the precision of the larger operand/field.
//! - `rmin`: a [relative tolerance comparison], scaled to the precision of the smaller operand/field.
//! - `r1st`: a [relative tolerance comparison], scaled to the precision of the first operand/field.
//! - `r2nd`: a [relative tolerance comparison], scaled to the precision of the second operand/field.
//! - `ulps`: an [ULPs comparison].
//!
//! When comparing homogeneous composite types that implement [`FloatEqAll`],
//! variants that use a uniform `tol` across all fields are also available:
//!
//! - `abs_all`: an [absolute tolerance comparison].
//! - `rmax_all`: a [relative tolerance comparison], scaled to the precision of the larger field.
//! - `rmin_all`: a [relative tolerance comparison], scaled to the precision of the smaller field.
//! - `r1st_all`: a [relative tolerance comparison], scaled to the precision of the first field.
//! - `r2nd_all`: a [relative tolerance comparison], scaled to the precision of the second field.
//! - `ulps_all`: an [ULPs comparison].
//!
//! *Note: `rel` and `rel_all` are legacy aliases for `rmax` and `rmax_all`, but
//! using the more precise algorithm names is recommended.*
//!
//! # Combining checks
//!
//! If multiple checks are specified in either a boolean comparison or an assert,
//! they are applied left to right and will shortcut on success. For example:
//!
//! ```
//! # use float_eq::float_eq;
//! # let a = 0.1; let b = 0.1; let abs_tol = 0.0; let ulps_tol: u64 = 0;
//! float_eq!(a, b, abs <= abs_tol, ulps <= ulps_tol)
//! # ;
//! ```
//!
//! Is equivalent to:
//!
//! ```
//! # use float_eq::float_eq;
//! # let a = 0.1; let b = 0.1; let abs_tol = 0.0; let ulps_tol: u64 = 0;
//! float_eq!(a, b, abs <= abs_tol) || float_eq!(a, b, ulps <= ulps_tol)
//! # ;
//! ```
//!
//! # Extending float_eq over custom types
//!
//! See [How to compare custom types].
//!
//! [How to compare custom types]: https://jtempest.github.io/float_eq-rs/book/how_to/compare_custom_types.html
//! [the float_eq guide]: https://jtempest.github.io/float_eq-rs/book/index.html
//! [absolute tolerance comparison]: https://jtempest.github.io/float_eq-rs/book/background/float_comparison_algorithms.html#absolute-tolerance-comparison
//! [relative tolerance comparison]: https://jtempest.github.io/float_eq-rs/book/background/float_comparison_algorithms.html#relative-tolerance-comparison
//! [ULPs comparison]: https://jtempest.github.io/float_eq-rs/book/background/float_comparison_algorithms.html#units-in-the-last-place-ulps-comparison

#![warn(missing_docs)]
#![cfg_attr(not(feature = "std"), no_std)]

#[macro_use]
mod macros;
pub use crate::macros::*;

mod traits;
pub use crate::traits::*;

mod trait_impls;
pub use crate::trait_impls::*;

#[cfg(feature = "float_eq_derive")]
pub use float_eq_derive::*;