microtransactionsmattertoo / noisy_float-rs

A rust library for checked floating point operations

noisy_float-rs

This is a Rust library containing floating point types that panic if they are set to an illegal value, such as NaN.

Crate

The Rust crate for this library can be found here.

Documentation

The documentation for this library can be found here.

Description

The name "Noisy Float" comes from the terms "quiet NaN" and "signaling NaN"; "signaling" was too long to put in a struct/crate name, so "noisy" is used instead, being the opposite of "quiet."

The standard types defined in noisy_float::types follow the principle demonstrated by Rust's handling of integer overflow: a bad arithmetic operation is considered an error, but it is too costly to check everywhere in optimized builds. For each floating point number that is created, a debug_assert! invocation is used to check if it is valid or not. This way, there are guarantees when developing code that floating point numbers have valid values, but during a release run there is no overhead for using these floating point types compared to using f32 or f64 directly.

This crate makes use of the floating point and number traits in the popular num_traits crate.

Examples

An example using the R64 type, which corresponds to finite f64 values.

use noisy_float::prelude::*;

fn geometric_mean(a: R64, b: R64) -> R64 {
    (a * b).sqrt() //used just like regular floating-point numbers
}

println!("geometric_mean(10.0, 20.0) = {}", geometric_mean(r64(10.0), r64(20.0)));
//prints 14.142...

An example using the N32 type, which corresponds to non-NaN f32 values. The float types in this crate are able to implement Eq and Ord properly, since NaN is not allowed.

use noisy_float::prelude::*;

let values = vec![n32(3.0), n32(-1.5), n32(71.3), N32::infinity()];
assert!(values.iter().cloned().min() == Some(n32(-1.5)));
assert!(values.iter().cloned().max() == Some(N32::infinity()));

License

Noisy_float is licensed under the Apache 2.0 License.