Repository files navigation

This crate provides a super-fast decimal number parser from strings into floats.

[dependencies]fast-float2 ="0.2.3"

There are no dependencies and the crate can be used in a no_std context by disabling the "std" feature.

Compiler support: rustc 1.37+.

This crate is in maintenance mode for bug fixes (especially security patches): minimal feature enhancements will be accepted. This implementation has been adopted by the Rust standard library: if you do not need parsing directly from bytes and/or partial parsers, you should useFromStr forf32 orf64 instead.

There's two top-level functions provided:parse() andparse_partial(), both takingeither a string or a bytes slice and parsing the input into eitherf32 orf64:

• parse() treats the whole string as a decimal number and returns an error if there areinvalid characters or if the string is empty.
• parse_partial() tries to find the longest substring at the beginning of the given inputstring that can be parsed as a decimal number and, in the case of success, returns the parsedvalue along the number of characters processed; an error is returned if the string doesn'tstart with a decimal number or if it is empty. This function is most useful as a buildingblock when constructing more complex parsers, or when parsing streams of data.

Example:

// Parse the entire string as a decimal number.let s ="1.23e-02";let x:f32 = fast_float2::parse(s).unwrap();assert_eq!(x,0.0123);// Parse as many characters as possible as a decimal number.let s ="1.23e-02foo";let(x, n) = fast_float2::parse_partial::<f32,_>(s).unwrap();assert_eq!(x,0.0123);assert_eq!(n,8);assert_eq!(&s[n..],"foo");

This crate is a direct port of Daniel Lemire'sfast_floatC++ library (valuable discussions with Daniel while porting it helped shape the crate and get it tothe performance level it's at now), with some Rust-specific tweaks. Please see the originalrepository for many useful details regarding the algorithm and the implementation.

The parser is locale-independent. The resulting value is the closest floating-point values (using eitherf32 orf64), using the "round to even" convention for values that would otherwise fall right in-betweentwo values. That is, we provide exact parsing according to the IEEE standard.

Infinity and NaN values can be parsed, along with scientific notation.

Both little-endian and big-endian platforms are equally supported, with extra optimizations enabledon little-endian architectures.

Sincefast-float-rust is unmaintained, this is a forkcontaining the patches and security updates.

There are a few ways this crate is tested:

• A suite of explicit tests (taken from the original library) covering lots of edge cases.
• A file-based test suite (taken from the original library; credits to Nigel Tao), ~5M tests.
• All 4B float32 numbers are exhaustively roundtripped via ryu formatter.
• Roundtripping a large quantity of random float64 numbers via ryu formatter.
• Roundtripping float64 numbers and fuzzing random input strings via cargo-fuzz.
• All explicit test suites run on CI; roundtripping and fuzzing are run manually.

The presented parser seems to beat all of the existing C/C++/Rust float parsers known to us at themoment by a large margin, in all of the datasets we tested it on so far – see detailed benchmarksbelow (the only exception being the original fast_float C++ library, of course – performance ofwhich is within noise bounds of this crate). On modern machines like Apple M1, parsing throughputcan reach up to 1.5 GB/s.

While various details regarding the algorithm can be found in the repository for the originalC++ library, here are few brief notes:

• The parser is specialized to work lightning-fast on inputs with at most 19 significant digits(which constitutes the so called "fast-path"). We believe that most real-life inputs shouldfall under this category, and we treat longer inputs as "degenerate" edge cases since itinevitable causes overflows and loss of precision.
• If the significand happens to be longer than 19 digits, the parser falls back to the "slow path",in which case its performance roughly matches that of the top Rust/C++ libraries (and stillbeats them most of the time, although not by a lot).
• On little-endian systems, there's additional optimizations for numbers with more than 8 digitsafter the decimal point.

Below are tables of best timings in nanoseconds for parsing a single number into a 64-bit float (using the median score, lower is better).

• CPU: Intel i7-14700K 3.40GHz
• OS: Ubuntu 24.04 (WSL2)
• Rust: 1.81
• C++: GCC 13.2.0

• CPU: AMD EPYC 7763 64-Core Processor 3.20GHz
• OS: Ubuntu 24.04.1
• Rust: 1.83
• C++: GCC 13.2.0
• Environment: Github Actions (2.321.0)

• CPU: AMD EPYC 7763 64-Core Processor 3.20GHz
• OS: Windows Server 2022 (10.0.20348)
• Rust: 1.83
• C++: MSVC 19.42.34435.0
• Environment: Github Actions (2.321.0)

• CPU: AMD EPYC 7763 64-Core Processor 3.20GHz
• OS: macOS (14.7.1)
• Rust: 1.83
• C++: Clang (Apple) 15.0.0.15000309
• Environment: Github Actions

Note that the random number generation seems to differ between C/C++ and Rust, since the Rust implementations are slightly faster for pre-determined datasets likecanada andmesh, but equivalent random number generators are slightly slower. Any performance penalty withfast-float2 occurred due to fixing the UB incheck_len. The massive performance differences betweenfast-float (Rust) andfast_float (C++) are expected due to a faster fallback algorithms (#96 and#104) used in these cases.

• fast-float2 - this very crate
• fast-float - the pre-ported variant
• lexical –lexical_core, v1.0.05
• from_str – Rust standard library,FromStr trait
• fast_float (C++) – original C++ implementation of 'fast-float' method
• abseil (C++) – Abseil C++ Common Libraries
• netlib (C++) – C++ Network Library
• strtod (C) – C standard library

• canada – numbers incanada.txt file
• mesh – numbers inmesh.txt file
• uniform – uniform random numbers from 0 to 1
• bi – large, integer-only floats <!--big_ints -- >
• int_e_int – random numbers of format%de%d
• rec32 – reciprocals of random 32-bit integers

• The two test files referred above can be found inthis repository.
• The Rust part of the table (along with a few other benchmarks) can be generated viathe benchmark tool that can be found underextras/simple-bench of this repo.
• The C/C++ part of the table (along with a few other benchmarks and parsers) can begenerated via a C++ utility that can be found inthis repository.

• Daniel Lemire,Number Parsing at a Gigabyte per Second, Software: Practice and Experience 51 (8), 2021.