Debian Codegraph @

.cargo/vendor/ryu/README.md

raw
1 # Ryū
2
3 [<img alt="github" src="https://img.shields.io/badge/github-dtolnay/ryu-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/ryu)
4 [<img alt="crates.io" src="https://img.shields.io/crates/v/ryu.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/ryu)
5 [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-ryu-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/ryu)
6 [<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/ryu/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/ryu/actions?query=branch%3Amaster)
7
8 Pure Rust implementation of Ryū, an algorithm to quickly convert floating point
9 numbers to decimal strings.
10
11 The PLDI'18 paper [*Ryū: fast float-to-string conversion*][paper] by Ulf Adams
12 includes a complete correctness proof of the algorithm. The paper is available
13 under the creative commons CC-BY-SA license.
14
15 This Rust implementation is a line-by-line port of Ulf Adams' implementation in
16 C, [https://github.com/ulfjack/ryu][upstream].
17
18 *Requirements: this crate supports any compiler version back to rustc 1.36; it
19 uses nothing from the Rust standard library so is usable from no_std crates.*
20
21 [paper]: https://dl.acm.org/citation.cfm?id=3192369
22 [upstream]: https://github.com/ulfjack/ryu/tree/77e767f5e056bab96e895072fc21618ecff2f44b
23
24 ```toml
25 [dependencies]
26 ryu = "1.0"
27 ```
28
29 <br>
30
31 ## Example
32
33 ```rust
34 fn main() {
35 let mut buffer = ryu::Buffer::new();
36 let printed = buffer.format(1.234);
37 assert_eq!(printed, "1.234");
38 }
39 ```
40
41 <br>
42
43 ## Performance (lower is better)
44
45 ![performance](https://raw.githubusercontent.com/dtolnay/ryu/master/performance.png)
46
47 You can run upstream's benchmarks with:
48
49 ```console
50 $ git clone https://github.com/ulfjack/ryu c-ryu
51 $ cd c-ryu
52 $ bazel run -c opt //ryu/benchmark:ryu_benchmark
53 ```
54
55 And the same benchmark against our implementation with:
56
57 ```console
58 $ git clone https://github.com/dtolnay/ryu rust-ryu
59 $ cd rust-ryu
60 $ cargo run --example upstream_benchmark --release
61 ```
62
63 These benchmarks measure the average time to print a 32-bit float and average
64 time to print a 64-bit float, where the inputs are distributed as uniform random
65 bit patterns 32 and 64 bits wide.
66
67 The upstream C code, the unsafe direct Rust port, and the safe pretty Rust API
68 all perform the same, taking around 21 nanoseconds to format a 32-bit float and
69 31 nanoseconds to format a 64-bit float.
70
71 There is also a Rust-specific benchmark comparing this implementation to the
72 standard library which you can run with:
73
74 ```console
75 $ cargo bench
76 ```
77
78 The benchmark shows Ryū approximately 2-5x faster than the standard library
79 across a range of f32 and f64 inputs. Measurements are in nanoseconds per
80 iteration; smaller is better.
81
82 ## Formatting
83
84 This library tends to produce more human-readable output than the standard
85 library's to\_string, which never uses scientific notation. Here are two
86 examples:
87
88 - *ryu:* 1.23e40, *std:* 12300000000000000000000000000000000000000
89 - *ryu:* 1.23e-40, *std:* 0.000000000000000000000000000000000000000123
90
91 Both libraries print short decimals such as 0.0000123 without scientific
92 notation.
93
94 <br>
95
96 #### License
97
98 <sup>
99 Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
100 2.0</a> or <a href="LICENSE-BOOST">Boost Software License 1.0</a> at your
101 option.
102 </sup>
103
104 <br>
105
106 <sub>
107 Unless you explicitly state otherwise, any contribution intentionally submitted
108 for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
109 be dual licensed as above, without any additional terms or conditions.
110 </sub>