Crate float_eq

Expand description

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;

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:

float_eq!(a, b, abs <= abs_tol, ulps <= ulps_tol)

Is equivalent to:

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.

Macros§

assert_float_eq: Asserts that two floating point expressions are equal to each other.
assert_float_ne: Asserts that two floating point expressions are not equal to each other.
debug_assert_float_eq: Asserts that two floating point expressions are equal to each other.
debug_assert_float_ne: Asserts that two floating point expressions are not equal to each other.
float_eq: Checks if two floating point expressions are equal to each other.
float_ne: Checks if two floating point expressions are not equal to each other.

Structs§

ComplexUlps: The absolute difference between two floating point num::Complex<T> instances in ULPs.

Traits§

AssertFloatEq: Debug context for when an assert fails.
AssertFloatEqAll: Debug context for when an assert using an all check fails.
FloatEq: Compare IEEE floating point values for equality using per-field tolerances.
FloatEqAll: Compare IEEE floating point values for equality using a uniform tolerance.
FloatEqDebugUlpsDiff: Per-field results of ULPs based diff calculations.
FloatEqUlpsTol: Per-field tolerances for ULPs comparisons.

Type Aliases§

ComplexUlps32: ComplexUlps<T> type matching num::Complex32.
ComplexUlps64: ComplexUlps<T> type matching num::Complex64.
DebugUlpsDiff: Per-field results of ULPs based diff calculations.
UlpsTol: Per-field tolerances for ULPs comparisons.

Attribute Macros§

derive_float_eq: Helper for deriving the various float_eq traits.

Crate float_eqCopy item path