]>
Commit | Line | Data |
---|---|---|
f035d41b XL |
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 | //! | |
b7449926 XL |
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 | |
416331ca | 17 | //! in C, [https://github.com/ulfjack/ryu][upstream]. |
b7449926 XL |
18 | //! |
19 | //! [paper]: https://dl.acm.org/citation.cfm?id=3192369 | |
20 | //! [upstream]: https://github.com/ulfjack/ryu | |
b7449926 | 21 | //! |
416331ca | 22 | //! # Example |
b7449926 | 23 | //! |
f035d41b | 24 | //! ``` |
b7449926 XL |
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 | //! ``` | |
416331ca XL |
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 | //! | |
f035d41b | 65 | //! The benchmark shows Ryū approximately 4-10x faster than the standard library |
416331ca XL |
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. | |
b7449926 XL |
90 | |
91 | #![no_std] | |
f035d41b | 92 | #![doc(html_root_url = "https://docs.rs/ryu/1.0.5")] |
416331ca | 93 | #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))] |
b7449926 XL |
94 | #![cfg_attr( |
95 | feature = "cargo-clippy", | |
416331ca | 96 | allow(cast_lossless, many_single_char_names, unreadable_literal,) |
b7449926 XL |
97 | )] |
98 | ||
b7449926 XL |
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; | |
f035d41b | 109 | mod f2s_intrinsics; |
b7449926 XL |
110 | mod pretty; |
111 | ||
f035d41b | 112 | pub use crate::buffer::{Buffer, Float}; |
b7449926 | 113 | |
416331ca | 114 | /// Unsafe functions that mirror the API of the C implementation of Ryū. |
b7449926 | 115 | pub mod raw { |
f035d41b | 116 | pub use crate::pretty::{format32, format64}; |
b7449926 | 117 | } |