#js #string #ecmascript #ryu

ryu-js

Fast floating point to string conversion, ECMAScript compliant

3 unstable releases

0.2.1 Sep 11, 2020
0.2.0 Jul 14, 2020
0.1.0 Jul 13, 2020
Download history 451/week @ 2021-04-12 528/week @ 2021-04-19 734/week @ 2021-04-26 879/week @ 2021-05-03 1200/week @ 2021-05-10 779/week @ 2021-05-17 831/week @ 2021-05-24 396/week @ 2021-05-31 521/week @ 2021-06-07 1358/week @ 2021-06-14 1138/week @ 2021-06-21 974/week @ 2021-06-28 688/week @ 2021-07-05 720/week @ 2021-07-12 1068/week @ 2021-07-19 1250/week @ 2021-07-26

3,352 downloads per month
Used in 23 crates (3 directly)

Apache-2.0 OR BSL-1.0

115KB
2K SLoC

Ryū-js

Ryū-js is a fork of the ryu crate adjusted to comply to the ECMAScript number-to-string algorithm. This crate is used in the boa crate for number to string conversions.

Pure Rust implementation of Ryū, an algorithm to quickly convert floating point numbers to decimal strings.

The PLDI'18 paper Ryū: fast float-to-string conversion by Ulf Adams includes a complete correctness proof of the algorithm. The paper is available under the creative commons CC-BY-SA license.

This Rust implementation is a line-by-line port of Ulf Adams' implementation in C, https://github.com/ulfjack/ryu.

Requirements: this crate supports any compiler version back to rustc 1.31; it uses nothing from the Rust standard library so is usable from no_std crates.

[dependencies]
ryu-js = "0.2"

Example

fn main() {
    let mut buffer = ryu_js::Buffer::new();
    let printed = buffer.format(1.234);
    assert_eq!(printed, "1.234");
}

Performance

The benchmarks measure the average time to print a 32-bit float and average time to print a 64-bit float, where the inputs are distributed as uniform random bit patterns 32 and 64 bits wide.

The upstream C code, the unsafe direct Rust port, and the safe pretty Rust API all perform the same, taking around 21 nanoseconds to format a 32-bit float and 31 nanoseconds to format a 64-bit float.

There is also a Rust-specific benchmark comparing this implementation to the standard library which you can run with:

$ cargo bench

The benchmark shows Ryū approximately 4-10x faster than the standard library across a range of f32 and f64 inputs. Measurements are in nanoseconds per iteration; smaller is better.

type=f32 0.0 0.1234 2.718281828459045 f32::MAX
RYU 3ns 28ns 23ns 22ns
STD 40ns 106ns 128ns 110ns
type=f64 0.0 0.1234 2.718281828459045 f64::MAX
RYU 3ns 50ns 35ns 32ns
STD 39ns 105ns 128ns 202ns

Formatting

This library tends to produce more human-readable output than the standard library's to_string, which never uses scientific notation. Here are two examples:

  • ryu: 1.23e40, std: 12300000000000000000000000000000000000000
  • ryu: 1.23e-40, std: 0.000000000000000000000000000000000000000123

Both libraries print short decimals such as 0.0000123 without scientific notation.


License

Licensed under either of Apache License, Version 2.0 or Boost Software License 1.0 at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies