Crate float_eq

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 Definitions

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.