Crate lexical_write_float
source ·Expand description
Fast and compact float-to-string conversions.
§Features
Each float formatter contains extensive formatting control, including a maximum number of significant digits written, a minimum number of significant digits remaining, the positive and negative exponent break points (at what exponent, in scientific-notation, to force scientific notation), whether to force or disable scientific notation, and the rounding mode for truncated float strings.
§Algorithms
There’s currently 5 algorithms used, depending on the requirements.
- Compact for decimal strings uses the Grisu algorithm.
- An optimized algorithm based on the Dragonbox algorithm.
- An optimized algorithm for formatting to string with power-of-two radixes.
- An optimized algorithm for hexadecimal floats.
- A fallback algorithm for all other radixes.
The Grisu algorithm is based on “Printing Floating-Point Numbers Quickly and Accurately with Integers”, by Florian Loitsch, available online here. The dragonbox algorithm is based on the reference C++ implementation, hosted here, and the algorithm is described in depth here. The radix algorithm is adapted from the V8 codebase, and may be found here.
§Features
std
- Use the standard library.power-of-two
- Add support for wring power-of-two float strings.radix
- Add support for strings of any radix.compact
- Reduce code size at the cost of performance.safe
- Ensure only memory-safe indexing is used.
§Note
Only documented functionality is considered part of the public API: any of the modules, internal functions, or structs may change release-to-release without major or minor version changes. Use internal implementation details at your own risk.
lexical-write-float mainly exists as an implementation detail for
lexical-core, although its API is stable. If you would like to use
a high-level API that writes to and parses from String
and &str
,
respectively, please look at lexical
instead. If you would like an API that supports multiple numeric
conversions, please look at lexical-core
instead.
§Version Support
The minimum, standard, required version is 1.63.0, for const generic support. Older versions of lexical support older Rust versions.
§Safety
The unsafe
usage in the options does not actually have any actual safety
concerns unless the format is not validated: the float formatters assume
NaN and Infinite strings are <= 50 characters. Creating custom format
specification with longer special strings and not validating the :
incorrectly using the API however can cause incorrect floating
point specifications due to conflicting requirements.
§Design
Modules§
- Public API for the number format packed struct.
- Configuration options for writing floats.
Structs§
- Build number format from specifications.
- Options to customize writing floats.
- Builder for
Options
.
Enums§
- Enumeration for how to round floats with precision control.
Constants§
- Maximum number of bytes required to serialize any number to string.
Traits§
- The size, in bytes, of formatted values.
- Trait for numerical types that can be serialized to bytes.
- Trait for numerical types that can be serialized to bytes with custom options.
- Shared trait for all writer options.