rust ffast-math (defunct, use lower)
add a readme
| -rw-r--r-- | Cargo.toml | 1 | ||||
| -rw-r--r-- | README.md | 34 | ||||
| -rw-r--r-- | src/lib.rs | 3 |
3 files changed, 38 insertions, 0 deletions
@@ -7,3 +7,4 @@ repository = "https://github.com/bend-n/umath" authors = ["bend-n <[email protected]>"] edition = "2021" exclude = [".gitignore"] +categories = ["hardware-support", "mathematics",]
\ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..fcdbe50 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# umath: ffast-math, for rust. + + + +Want to make your math *faster*? [<sup>*t&c apply</sup>](https://simonbyrne.github.io/notes/fastmath) + +Want to *order* a float? + +You can do all of that, with `umath`! + +```rs +use umath::FFloat; +// wrap a non NAN and non INF f32/f64 (we will also *never* make this number nan). +let mut f = unsafe { FFloat::new(4.0f32) }; +f *= 3; // multiply by 3 +// this check will be removed by the optimizer! +assert!(!f.is_nan()); +# use std::collections::BinaryHeap; +// use a ORD type! this is allowed, as FFloat is not allowed to be NAN | INF. +let mut b = BinaryHeap::new(); +b.push(unsafe { FFloat::new(2.0) }); +b.push(unsafe { FFloat::new(1.0) }); +b.push(unsafe { FFloat::new(3.0) }); +b.push(f); +assert_eq!(b.pop(), Some(unsafe { FFloat::new(24.0) })); +``` + +## A note on safety + +When you make your first [`FFLoat`](https://docs.rs/umath/latest/umath/struct.FFloat.html), you must promise that you will never create a [`NAN`](https://doc.rust-lang.org/nightly/std/primitive.f32.html#associatedconstant.NAN) | [`INF`](https://doc.rust-lang.org/nightly/std/primitive.f32.html#associatedconstant.INFINITY) [`FFLoat`](https://docs.rs/umath/latest/umath/struct.FFloat.html). Hence, `*f = NAN` is (delayed) UB. + +### Nightlyness + +`umath` is nightly because it makes use of core intrinsics, like [`fadd_fast()`](https://doc.rust-lang.org/nightly/core/intrinsics/fn.fadd_fast.html), which require the [`core_intrinsics`](https://doc.rust-lang.org/nightly/unstable-book/library-features/core-intrinsics.html) feature to use.
\ No newline at end of file @@ -20,6 +20,8 @@ mod r#trait; use r#trait::FastFloat; /// Float wrapper that uses `ffast-math`. This float also implements [`Ord`], as it is not allowed to be [`NAN`](std::f32::NAN). +/// +/// `FFloat<F>` is guaranteed to have the same memory layout and ABI as F. /// ``` /// # use umath::FFloat; /// # unsafe { @@ -27,6 +29,7 @@ use r#trait::FastFloat; /// assert_eq!(*result, 1136943.0); /// # } /// ``` +#[repr(transparent)] #[derive(Copy, Clone, PartialEq)] pub struct FFloat<T>(T); |