lexical_write_float/
lib.rs

1//! Fast and compact float-to-string conversions.
2//!
3//! # Features
4//!
5//! Each float formatter contains extensive formatting control, including
6//! a maximum number of significant digits written, a minimum number of
7//! significant digits remaining, the positive and negative exponent break
8//! points (at what exponent, in scientific-notation, to force scientific
9//! notation), whether to force or disable scientific notation, and the
10//! rounding mode for truncated float strings.
11//!
12//! # Algorithms
13//!
14//! There's currently 5 algorithms used, depending on the requirements.
15//!
16//! 1. Compact for decimal strings uses the Grisu algorithm.
17//! 2. An optimized algorithm based on the Dragonbox algorithm.
18//! 3. An optimized algorithm for formatting to string with power-of-two radixes.
19//! 4. An optimized algorithm for hexadecimal floats.
20//! 5. A fallback algorithm for all other radixes.
21//!
22//! The Grisu algorithm is based on "Printing Floating-Point Numbers Quickly
23//! and Accurately with Integers", by Florian Loitsch, available online
24//! [here](https://www.cs.tufts.edu/~nr/cs257/archive/florian-loitsch/printf.pdf).
25//! The dragonbox algorithm is based on the reference C++ implementation,
26//! hosted [here](https://github.com/jk-jeon/dragonbox/), and the algorithm
27//! is described in depth
28//! [here](https://github.com/jk-jeon/dragonbox/blob/master/other_files/Dragonbox.pdf).
29//! The radix algorithm is adapted from the V8 codebase, and may be found
30//! [here](https://github.com/v8/v8).
31//!
32//! # Features
33//!
34//! * `std` - Use the standard library.
35//! * `power-of-two` - Add support for wring power-of-two float strings.
36//! * `radix` - Add support for strings of any radix.
37//! * `compact` - Reduce code size at the cost of performance.
38//! * `safe` - Ensure only memory-safe indexing is used.
39//!
40//! # Note
41//!
42//! Only documented functionality is considered part of the public API:
43//! any of the modules, internal functions, or structs may change
44//! release-to-release without major or minor version changes. Use
45//! internal implementation details at your own risk.
46//!
47//! lexical-write-float mainly exists as an implementation detail for
48//! lexical-core, although its API is stable. If you would like to use
49//! a high-level API that writes to and parses from `String` and `&str`,
50//! respectively, please look at [lexical](https://crates.io/crates/lexical)
51//! instead. If you would like an API that supports multiple numeric
52//! conversions, please look at [lexical-core](https://crates.io/crates/lexical-core)
53//! instead.
54//!
55//! # Version Support
56//!
57//! The minimum, standard, required version is 1.51.0, for const generic
58//! support. Older versions of lexical support older Rust versions.
59//!
60//! # Design
61//!
62//! - [Algorithm Approach](https://github.com/Alexhuszagh/rust-lexical/blob/main/lexical-write-float/docs/Algorithm.md)
63//! - [Benchmarks](https://github.com/Alexhuszagh/rust-lexical/blob/main/lexical-write-float/docs/Benchmarks.md)
64
65// We want to have the same safety guarantees as Rust core,
66// so we allow unused unsafe to clearly document safety guarantees.
67#![allow(unused_unsafe)]
68#![cfg_attr(feature = "lint", warn(unsafe_op_in_unsafe_fn))]
69#![cfg_attr(not(feature = "std"), no_std)]
70
71#[macro_use]
72mod index;
73#[macro_use]
74mod shared;
75
76pub mod algorithm;
77pub mod binary;
78pub mod compact;
79pub mod float;
80pub mod hex;
81pub mod options;
82pub mod radix;
83pub mod table;
84pub mod write;
85
86mod api;
87mod table_dragonbox;
88mod table_grisu;
89
90// Re-exports
91pub use self::api::{ToLexical, ToLexicalWithOptions};
92#[doc(inline)]
93pub use self::options::{Options, OptionsBuilder, RoundMode};
94#[cfg(feature = "f16")]
95pub use lexical_util::bf16::bf16;
96pub use lexical_util::constants::{FormattedSize, BUFFER_SIZE};
97#[cfg(feature = "f16")]
98pub use lexical_util::f16::f16;
99pub use lexical_util::format::{self, NumberFormatBuilder};
100pub use lexical_util::options::WriteOptions;
lexical_write_float/lib.rs

lexical_write_float/
lib.rs
