1 //! [![github]](https://github.com/dtolnay/ryu) [![crates-io]](https://crates.io/crates/ryu) [![docs-rs]](https://docs.rs/ryu) 2 //! 3 //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github 4 //! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust 5 //! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K 6 //! 7 //! <br> 8 //! 9 //! Pure Rust implementation of Ryū, an algorithm to quickly convert floating 10 //! point numbers to decimal strings. 11 //! 12 //! The PLDI'18 paper [*Ryū: fast float-to-string conversion*][paper] by Ulf 13 //! Adams includes a complete correctness proof of the algorithm. The paper is 14 //! available under the creative commons CC-BY-SA license. 15 //! 16 //! This Rust implementation is a line-by-line port of Ulf Adams' implementation 17 //! in C, [https://github.com/ulfjack/ryu][upstream]. 18 //! 19 //! [paper]: https://dl.acm.org/citation.cfm?id=3192369 20 //! [upstream]: https://github.com/ulfjack/ryu 21 //! 22 //! # Example 23 //! 24 //! ``` 25 //! fn main() { 26 //! let mut buffer = ryu::Buffer::new(); 27 //! let printed = buffer.format(1.234); 28 //! assert_eq!(printed, "1.234"); 29 //! } 30 //! ``` 31 //! 32 //! ## Performance 33 //! 34 //! You can run upstream's benchmarks with: 35 //! 36 //! ```console 37 //! $ git clone https://github.com/ulfjack/ryu c-ryu 38 //! $ cd c-ryu 39 //! $ bazel run -c opt //ryu/benchmark 40 //! ``` 41 //! 42 //! And the same benchmark against our implementation with: 43 //! 44 //! ```console 45 //! $ git clone https://github.com/dtolnay/ryu rust-ryu 46 //! $ cd rust-ryu 47 //! $ cargo run --example upstream_benchmark --release 48 //! ``` 49 //! 50 //! These benchmarks measure the average time to print a 32-bit float and average 51 //! time to print a 64-bit float, where the inputs are distributed as uniform random 52 //! bit patterns 32 and 64 bits wide. 53 //! 54 //! The upstream C code, the unsafe direct Rust port, and the safe pretty Rust API 55 //! all perform the same, taking around 21 nanoseconds to format a 32-bit float and 56 //! 31 nanoseconds to format a 64-bit float. 57 //! 58 //! There is also a Rust-specific benchmark comparing this implementation to the 59 //! standard library which you can run with: 60 //! 61 //! ```console 62 //! $ cargo bench 63 //! ``` 64 //! 65 //! The benchmark shows Ryū approximately 4-10x faster than the standard library 66 //! across a range of f32 and f64 inputs. Measurements are in nanoseconds per 67 //! iteration; smaller is better. 68 //! 69 //! | type=f32 | 0.0 | 0.1234 | 2.718281828459045 | f32::MAX | 70 //! |:--------:|:----:|:------:|:-----------------:|:--------:| 71 //! | RYU | 3ns | 28ns | 23ns | 22ns | 72 //! | STD | 40ns | 106ns | 128ns | 110ns | 73 //! 74 //! | type=f64 | 0.0 | 0.1234 | 2.718281828459045 | f64::MAX | 75 //! |:--------:|:----:|:------:|:-----------------:|:--------:| 76 //! | RYU | 3ns | 50ns | 35ns | 32ns | 77 //! | STD | 39ns | 105ns | 128ns | 202ns | 78 //! 79 //! ## Formatting 80 //! 81 //! This library tends to produce more human-readable output than the standard 82 //! library's to\_string, which never uses scientific notation. Here are two 83 //! examples: 84 //! 85 //! - *ryu:* 1.23e40, *std:* 12300000000000000000000000000000000000000 86 //! - *ryu:* 1.23e-40, *std:* 0.000000000000000000000000000000000000000123 87 //! 88 //! Both libraries print short decimals such as 0.0000123 without scientific 89 //! notation. 90 91 #![no_std] 92 #![doc(html_root_url = "https://docs.rs/ryu/1.0.5")] 93 #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))] 94 #![cfg_attr( 95 feature = "cargo-clippy", 96 allow(cast_lossless, many_single_char_names, unreadable_literal,) 97 )] 98 99 mod buffer; 100 mod common; 101 mod d2s; 102 #[cfg(not(feature = "small"))] 103 mod d2s_full_table; 104 mod d2s_intrinsics; 105 #[cfg(feature = "small")] 106 mod d2s_small_table; 107 mod digit_table; 108 mod f2s; 109 mod f2s_intrinsics; 110 mod pretty; 111 112 pub use crate::buffer::{Buffer, Float}; 113 114 /// Unsafe functions that mirror the API of the C implementation of Ryū. 115 pub mod raw { 116 pub use crate::pretty::{format32, format64}; 117 } 118