# 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 num, bounded, signed and floating point traits in the
popular `num_traits`

crate.
This crate can be compiled with no_std.

### 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.