Ryūū

This is a fork of the ryu crate with the following changes:

• Const ready, requiring Rust 1.83.

• The APIs are changed, so it is not compatible with the original ryu crate, though migration is trivial:

  The original ryu crate provided a Buffer type:

  use ryu::Buffer;
  let mut buffer = Buffer::new();
  let formatted = buffer.format(1.234f64); // the `formatted` is a `&str`, referencing the buffer
  assert_eq!(formatted, "1.234");
  

  Now it is:

  use ryuu::Formatter;
  let formatted = Formatter::format(1.234f64);
  assert_eq!(&*formatted, "1.234"); // the `formatted` is now with a dedicated type `Formatted`
  

  The most significant change is that Formatted allows being "dereferenced" into a string with specified decimal places.

  See the API documentation for more details.

  According to the bench results, no significant performance regression was observed.

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.36; it uses nothing from the Rust standard library so is usable from no_std crates.

[dependencies]
ryuu = "1.0"

Example

fn main() {
    let formatted = ryuu::Formatter::format_f64(1.234);
    assert_eq!(&*formatted, "1.234");
}

Performance (lower is better)

You can run upstream's benchmarks with:

$ git clone https://github.com/ulfjack/ryu c-ryu
$ cd c-ryu
$ bazel run -c opt //ryu/benchmark:ryu_benchmark

And the same benchmark against our implementation with:

$ git clone https://github.com/hanyu-dev/ryuu rust-ryuu
$ cd rust-ryuu
$ cargo run --example upstream_benchmark --release

These 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 2-5x faster than the standard library across a range of f32 and f64 inputs. Measurements are in nanoseconds per iteration; smaller is better.

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:

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

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

License