Merge remote-tracking branch 'upstream/master'

Author: P1n3appl3

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased]
+
+## v0.1.0 - 2018-07-13
+
+- Initial release
+
+[Unreleased]: https://github.com/japaric/libm/compare/v0.1.0...HEAD

CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# How to contribute
+
+- Pick your favorite math function from the [issue tracker].
+- Look for the C implementation of the function in the [MUSL source code][src].
+- Copy paste the C code into a Rust file in the `src/math` directory and adjust `src/math/mod.rs`
+  accordingly. Also, uncomment the corresponding trait method in `src/lib.rs`.
+- Run `cargo watch check` and fix the compiler errors.
+- Tweak the bottom of `test-generator/src/main.rs` to add your function to the test suite.
+- If you can, run the full test suite locally (see the [testing](#testing) section below). If you
+  can't, no problem! Your PR will be fully tested automatically. Though you may still want to add
+  and run some unit tests. See the bottom of [`src/math/truncf.rs`] for an example of such tests;
+  you can run unit tests with the `cargo test --lib` command.
+- Send us a pull request!
+- :tada:
+
+[issue tracker]: https://github.com/japaric/libm/issues
+[src]: https://git.musl-libc.org/cgit/musl/tree/src/math
+[`src/math/truncf.rs`]: https://github.com/japaric/libm/blob/master/src/math/truncf.rs
+
+Check [PR #65] for an example.
+
+[PR #65]: https://github.com/japaric/libm/pull/65
+
+## Tips and tricks
+
+- *IMPORTANT* The code in this crate will end up being used in the `core` crate so it can **not**
+  have any external dependencies (other than `core` itself).
+
+- Only use relative imports within the `math` directory / module, e.g. `use self::fabs::fabs` or
+`use super::isnanf`. Absolute imports from core are OK, e.g. `use core::u64`.
+
+- To reinterpret a float as an integer use the `to_bits` method. The MUSL code uses the
+  `GET_FLOAT_WORD` macro, or a union, to do this operation.
+
+- To reinterpret an integer as a float use the `f32::from_bits` constructor. The MUSL code uses the
+  `SET_FLOAT_WORD` macro, or a union, to do this operation.
+
+- You may encounter weird literals like `0x1p127f` in the MUSL code. These are hexadecimal floating
+  point literals. Rust (the language) doesn't support these kind of literals. The best way I have
+  found to deal with these literals is to turn them into their integer representation using the
+  [`hexf!`] macro and then turn them back into floats. See below:
+
+[`hexf!`]: https://crates.io/crates/hexf
+
+``` rust
+// Step 1: write a program to convert the float into its integer representation
+#[macro_use]
+extern crate hexf;
+
+fn main() {
+    println!("{:#x}", hexf32!("0x1.0p127").to_bits());
+}
+```
+
+``` console
+$ # Step 2: run the program
+$ cargo run
+0x7f000000
+```
+
+``` rust
+// Step 3: copy paste the output into libm
+let x1p127 = f32::from_bits(0x7f000000); // 0x1p127f === 2 ^ 12
+```
+
+- Rust code panics on arithmetic overflows when not optimized. You may need to use the [`Wrapping`]
+  newtype to avoid this problem.
+
+[`Wrapping`]: https://doc.rust-lang.org/std/num/struct.Wrapping.html
+
+## Testing
+
+The test suite of this crate can only be run on x86_64 Linux systems using the following commands:
+
+``` console
+$ # The test suite depends on the `cross` tool so install it if you don't have it
+$ cargo install cross
+
+$ # and the `cross` tool requires docker to be running
+$ systemctl start docker
+
+$ # execute the test suite for the x86_64 target
+$ TARGET=x86_64-unknown-linux-gnu bash ci/script.sh
+
+$ # execute the test suite for the ARMv7 target
+$ TARGET=armv7-unknown-linux-gnueabihf bash ci/script.sh
+```

Cargo.toml

@@ -1,7 +1,13 @@
 [package]
+authors = ["Jorge Aparicio <[email protected]>"]
+categories = ["no-std"]
+description = "libm in pure Rust"
+documentation = "https://docs.rs/libm"
+keywords = ["libm", "math"]
+license = "MIT OR Apache-2.0"
 name = "libm"
+repository = "https://github.com/japaric/libm"
 version = "0.1.0"
-authors = ["Jorge Aparicio <[email protected]>"]
 
 [workspace]
 members = ["cb", "test-generator"]

README.md

@@ -6,62 +6,41 @@ A port of [MUSL]'s libm to Rust.
 
 ## Goals
 
-The short term goal of this library is to enable math support (e.g. `sin`, `atan2`) for the
-`wasm32-unknown-unknown` target. The longer term goal is to enable math support in the `core` crate.
+The short term goal of this library is to [enable math support (e.g. `sin`, `atan2`) for the
+`wasm32-unknown-unknown` target][wasm] (cf. [rust-lang-nursery/compiler-builtins][pr]). The longer
+term goal is to enable [math support in the `core` crate][core].
 
-## Testing
+[wasm]: https://github.com/japaric/libm/milestone/1
+[pr]: https://github.com/rust-lang-nursery/compiler-builtins/pull/248
+[core]: https://github.com/japaric/libm/milestone/2
 
-The test suite of this crate can only be run on x86_64 Linux systems.
+## Already usable
 
-```
-$ # The test suite depends on the `cross` tool so install it if you don't have it
-$ cargo install cross
-
-$ # and the `cross` tool requires docker to be running
-$ systemctl start docker
-
-$ # execute the test suite for the x86_64 target
-$ TARGET=x86_64-unknown-linux-gnu bash ci/script.sh
-
-$ # execute the test suite for the ARMv7 target
-$ TARGET=armv7-unknown-linux-gnueabihf bash ci/script.sh
-```
+This crate is [on crates.io] and can be used today in stable `#![no_std]` programs like this:
 
-## Contributing
-
-- Pick your favorite math function from the [issue tracker].
-- Look for the C implementation of the function in the [MUSL source code][src].
-- Copy paste the C code into a Rust file in the `src/math` directory and adjust `src/math/mod.rs`
-  accordingly. Also, uncomment the corresponding trait method in `src/lib.rs`.
-- Run `cargo watch check` and fix the compiler errors.
-- Tweak the bottom of `test-generator/src/main.rs` to add your function to the test suite.
-- If you can, run the test suite locally. If you can't, no problem! Your PR will be tested
-  automatically.
-- Send us a pull request!
-- :tada:
-
-[issue tracker]: https://github.com/japaric/libm/issues
-[src]: https://git.musl-libc.org/cgit/musl/tree/src/math
+[on crates.io]: https://crates.io/crates/libm
 
-Check [PR #2] for an example.
+``` rust
+#![no_std]
 
-[PR #2]: https://github.com/japaric/libm/pull/2
+extern crate libm;
 
-### Notes
+use libm::F32Ext; // adds methods to `f32`
 
-- Only use relative imports within the `math` directory / module, e.g. `use self::fabs::fabs` or
-`use super::isnanf`. Absolute imports from core are OK, e.g. `use core::u64`.
+fn foo(x: f32) {
+    let y = x.sqrt();
+    let z = libm::truncf(x);
+}
+```
 
-- To reinterpret a float as an integer use the `to_bits` method. The MUSL code uses the
-  `GET_FLOAT_WORD` macro, or a union, to do this operation.
+Not all the math functions are available at the moment. Check the [API docs] to learn what's
+currently supported.
 
-- To reinterpret an integer as a float use the `f32::from_bits` constructor. The MUSL code uses the
-  `SET_FLOAT_WORD` macro, or a union, to do this operation.
+[API docs]: https://docs.rs/libm
 
-- Rust code panics on arithmetic overflows when not optimized. You may need to use the [`Wrapping`]
-  newtype to avoid this problem.
+## Contributing
 
-[`Wrapping`]: https://doc.rust-lang.org/std/num/struct.Wrapping.html
+Please check [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 

src/lib.rs

@@ -32,9 +32,8 @@ pub fn _eq(a: u64, b: u64) -> bool {
 
 /// Math support for `f32`
 ///
-/// NOTE this meant to be a closed extension trait. The only stable way to use this trait is to
-/// import it to access its methods.
-pub trait F32Ext {
+/// This trait is sealed and cannot be implemented outside of `libm`.
+pub trait F32Ext: private::Sealed {
     #[cfg(todo)]
     fn floor(self) -> Self;
 
@@ -43,7 +42,6 @@ pub trait F32Ext {
 
     fn round(self) -> Self;
 
-    #[cfg(todo)]
     fn trunc(self) -> Self;
 
     #[cfg(todo)]
@@ -70,16 +68,13 @@ pub trait F32Ext {
 
     fn sqrt(self) -> Self;
 
-    #[cfg(todo)]
     fn exp(self) -> Self;
 
     #[cfg(todo)]
     fn exp2(self) -> Self;
 
-    #[cfg(todo)]
     fn ln(self) -> Self;
 
-    #[cfg(todo)]
     fn log(self, base: Self) -> Self;
 
     #[cfg(todo)]
@@ -91,7 +86,6 @@ pub trait F32Ext {
     #[cfg(todo)]
     fn cbrt(self) -> Self;
 
-    #[cfg(todo)]
     fn hypot(self, other: Self) -> Self;
 
     #[cfg(todo)]
@@ -164,7 +158,6 @@ impl F32Ext for f32 {
         roundf(self)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn trunc(self) -> Self {
         truncf(self)
@@ -218,7 +211,6 @@ impl F32Ext for f32 {
         sqrtf(self)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn exp(self) -> Self {
         expf(self)
@@ -230,13 +222,11 @@ impl F32Ext for f32 {
         exp2f(self)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn ln(self) -> Self {
         logf(self)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn log(self, base: Self) -> Self {
         self.ln() / base.ln()
@@ -260,7 +250,6 @@ impl F32Ext for f32 {
         cbrtf(self)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn hypot(self, other: Self) -> Self {
         hypotf(self, other)
@@ -364,20 +353,17 @@ impl F32Ext for f32 {
     }
 }
 
-/// Math support for `f32`
+/// Math support for `f64`
 ///
-/// NOTE this meant to be a closed extension trait. The only stable way to use this trait is to
-/// import it to access its methods.
-pub trait F64Ext {
-    #[cfg(todo)]
+/// This trait is sealed and cannot be implemented outside of `libm`.
+pub trait F64Ext: private::Sealed {
     fn floor(self) -> Self;
 
     #[cfg(todo)]
     fn ceil(self) -> Self;
 
     fn round(self) -> Self;
 
-    #[cfg(todo)]
     fn trunc(self) -> Self;
 
     #[cfg(todo)]
@@ -403,7 +389,6 @@ pub trait F64Ext {
     #[cfg(todo)]
     fn powf(self, n: Self) -> Self;
 
-    #[cfg(todo)]
     fn sqrt(self) -> Self;
 
     #[cfg(todo)]
@@ -427,7 +412,6 @@ pub trait F64Ext {
     #[cfg(todo)]
     fn cbrt(self) -> Self;
 
-    #[cfg(todo)]
     fn hypot(self, other: Self) -> Self;
 
     #[cfg(todo)]
@@ -483,7 +467,6 @@ pub trait F64Ext {
 }
 
 impl F64Ext for f64 {
-    #[cfg(todo)]
     #[inline]
     fn floor(self) -> Self {
         floor(self)
@@ -500,7 +483,6 @@ impl F64Ext for f64 {
         round(self)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn trunc(self) -> Self {
         trunc(self)
@@ -550,7 +532,6 @@ impl F64Ext for f64 {
         pow(self, n)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn sqrt(self) -> Self {
         sqrt(self)
@@ -598,7 +579,6 @@ impl F64Ext for f64 {
         cbrt(self)
     }
 
-    #[cfg(todo)]
     #[inline]
     fn hypot(self, other: Self) -> Self {
         hypot(self, other)
@@ -701,3 +681,10 @@ impl F64Ext for f64 {
         0.5 * ((2.0 * self) / (1.0 - self)).ln_1p()
     }
 }
+
+mod private {
+    pub trait Sealed {}
+
+    impl Sealed for f32 {}
+    impl Sealed for f64 {}
+}