Crate lexical_write_float

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.

1. Compact for decimal strings uses the Grisu algorithm.
2. An optimized algorithm based on the Dragonbox algorithm.
3. An optimized algorithm for formatting to string with power-of-two radixes.
4. An optimized algorithm for hexadecimal floats.
5. 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

• Algorithm Approach
• Benchmarks
• Comprehensive Benchmarks

Modules

• format
  Public API for the number format packed struct.
• options
  Configuration options for writing floats.

Structs

• NumberFormatBuilder
  Build number format from specifications.
• Options
  Options to customize writing floats.
• OptionsBuilder
  Builder for Options.

Enums

• RoundMode
  Enumeration for how to round floats with precision control.

Constants

• BUFFER_SIZE
  Maximum number of bytes required to serialize any number to string.

Traits

• FormattedSize
  The size, in bytes, of formatted values.
• ToLexical
  Trait for numerical types that can be serialized to bytes.
• ToLexicalWithOptions
  Trait for numerical types that can be serialized to bytes with custom options.
• WriteOptions
  Shared trait for all writer options.