Fast and exact implementation of the C++ from_chars functions for float and double types: 4x faster than strtod
The fastfloat library provides fast header-only implementations for the C++ fromchars functions for
floatand
doubletypes. These functions convert ASCII strings representing decimal values (e.g.,
1.3e10) into binary types. We provide exact rounding (including round to even). In our experience, these
fast_floatfunctions many times faster than comparable number-parsing functions from existing C++ standard libraries.
Specifically,
fast_floatprovides the following two functions with a C++17-like syntax (the library itself only requires C++11):
from_chars_result from_chars(const char* first, const char* last, float& value, ...); from_chars_result from_chars(const char* first, const char* last, double& value, ...);
The return type (
from_chars_result) is defined as the struct:
C++ struct from_chars_result { const char* ptr; std::errc ec; };
It parses the character sequence [first,last) for a number. It parses floating-point numbers expecting a locale-independent format equivalent to the C++17 from_chars function. The resulting floating-point value is the closest floating-point values (using either float or double), using the "round to even" convention for values that would otherwise fall right in-between two values. That is, we provide exact parsing according to the IEEE standard.
Given a successful parse, the pointer (
ptr) in the returned value is set to point right after the parsed number, and the
valuereferenced is set to the parsed value. In case of error, the returned
eccontains a representative error, otherwise the default (
std::errc()) value is stored.
The implementation does not throw and does not allocate memory (e.g., with
newor
malloc).
It will parse infinity and nan values.
Example:
#include "fast_float/fast_float.h" #includeint main() { const std::string input = "3.1416 xyz "; double result; auto answer = fast_float::from_chars(input.data(), input.data()+input.size(), result); if(answer.ec != std::errc()) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << result << std::endl; return EXIT_SUCCESS; }
Like the C++17 standard, the
fast_float::from_charsfunctions take an optional last argument of the type
fast_float::chars_format. It is a bitset value: we check whether
fmt & fast_float::chars_format::fixedand
fmt & fast_float::chars_format::scientificare set to determine whether we allow the fixed point and scientific notation respectively. The default is
fast_float::chars_format::generalwhich allows both
fixedand
scientific.
The library seeks to follow the C++17 (see 20.19.3.(7.1)) specification. * The
from_charsfunction does not skip leading white-space characters. * A leading
+sign is forbidden. * It is generally impossible to represent a decimal value exactly as binary floating-point number (
floatand
doubletypes). We seek the nearest value. We round to an even mantissa when we are in-between two binary floating-point numbers.
Furthermore, we have the following restrictions: * We only support
floatand
doubletypes at this time. * We only support the decimal format: we do not support hexadecimal strings. * For values that are either very large or very small (e.g.,
1e9999), we represent it using the infinity or negative infinity value.
We support Visual Studio, macOS, Linux, freeBSD. We support big and little endian. We support 32-bit and 64-bit systems.
The C++ standard stipulate that
from_charshas to be locale-independent. In particular, the decimal separator has to be the period (
.). However, some users still want to use the
fast_floatlibrary with in a locale-dependent manner. Using a separate function called
from_chars_advanced, we allow the users to pass a
parse_optionsinstance which contains a custom decimal separator (e.g., the comma). You may use it as follows.
#include "fast_float/fast_float.h" #includeint main() { const std::string input = "3,1416 xyz "; double result; fast_float::parse_options options{fast_float::chars_format::general, ','}; auto answer = fast_float::from_chars_advanced(input.data(), input.data()+input.size(), result, options); if((answer.ec != std::errc()) || ((result != 3.1416))) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << result << std::endl; return EXIT_SUCCESS; }
rcppfastfloat.
fast-float-rust.
FastDoubleParser.
csFastFloat.
The fastfloat library provides a performance similar to that of the fastdoubleparser library but using an updated algorithm reworked from the ground up, and while offering an API more in line with the expectations of C++ programmers. The fastdouble_parser library is part of the Microsoft LightGBM machine-learning framework.
The fast_float library is used by Apache Arrow where it multiplied the number parsing speed by two or three times. It is also used by Yandex ClickHouse and by Google Jsonnet.
It can parse random floating-point numbers at a speed of 1 GB/s on some systems. We find that it is often twice as fast as the best available competitor, and many times faster than many standard-library implementations.
$ ./build/benchmarks/benchmark # parsing random integers in the range [0,1) volume = 2.09808 MB netlib : 271.18 MB/s (+/- 1.2 %) 12.93 Mfloat/s doubleconversion : 225.35 MB/s (+/- 1.2 %) 10.74 Mfloat/s strtod : 190.94 MB/s (+/- 1.6 %) 9.10 Mfloat/s abseil : 430.45 MB/s (+/- 2.2 %) 20.52 Mfloat/s fastfloat : 1042.38 MB/s (+/- 9.9 %) 49.68 Mfloat/s
See https://github.com/lemire/simplefastfloatbenchmark for our benchmarking code.
This library is header-only by design. The CMake file provides the
fast_floattarget which is merely a pointer to the
includedirectory.
If you drop the
fast_floatrepository in your CMake project, you should be able to use it in this manner:
add_subdirectory(fast_float) target_link_libraries(myprogram PUBLIC fast_float)
Or you may want to retrieve the dependency automatically if you have a sufficiently recent version of CMake (3.11 or better at least):
FetchContent_Declare( fast_float GIT_REPOSITORY https://github.com/lemire/fast_float.git GIT_TAG tags/v1.1.2 GIT_SHALLOW TRUE)FetchContent_MakeAvailable(fast_float) target_link_libraries(myprogram PUBLIC fast_float)
You should change the
GIT_TAGline so that you recover the version you wish to use.
The script
script/amalgamate.pymay be used to generate a single header version of the library if so desired. Just run the script from the root directory of this repository. You can customize the license type and output file if desired as described in the command line help.
You may directly download automatically generated single-header files:
https://github.com/fastfloat/fastfloat/releases/download/v1.1.2/fastfloat.h
Though this work is inspired by many different people, this work benefited especially from exchanges with Michael Eisel, who motivated the original research with his key insights, and with Nigel Tao who provided invaluable feedback. Rémy Oudompheng first implemented a fast path we use in the case of long digits.
The library includes code adapted from Google Wuffs (written by Nigel Tao) which was originally published under the Apache 2.0 license.
^{ Licensed under either of Apache License, Version 2.0 or MIT license at your option. }
_{ Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this repository by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. }