Effectively complete our write float API documentation enhancements.

CHANGELOG

@@ -12,11 +12,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Additional trait impls for `f16` and `bf16` to better match Rust's interface.
 - Added `Options::buffer_size_const` for integer and float writers.
 - Added `build_checked` and `build_unchecked` to our `NumberFormatBuilder` API.
+- Added `build_checked` to our `Options` API.
 
 ### Changed
 
 - Lowered the MSRV from 1.63.0 to 1.61.0 and adds support for most testing on 1.61.0.
 - Reduced the required buffer size for integer and float writers when using `buffer_size` and `buffer_size_const` for decimal numbers.
+- Deprecated `NumberFormatBuilder::build` due to a lack of validation.
+- Deprecated `Options::set_*` in our write float API since options should be considered immutable.
 
 ## [1.0.5] 2024-12-08
 

lexical-util/src/feature_format.rs

@@ -2779,9 +2779,9 @@ pub const SAGE_STRING: u128 = NumberFormatBuilder::new()
     .build_strict();
 
 // JSON [456]
-/// Number format for a [`JSON`] literal floating-point number.
+/// Number format for a [`JSON`][`JSON-REF`] literal floating-point number.
 ///
-/// [`JSON`]: https://www.json.org/json-en.html
+/// [`JSON-REF`]: https://www.json.org/json-en.html
 #[rustfmt::skip]
 pub const JSON: u128 = NumberFormatBuilder::new()
     .required_digits(true)
@@ -2792,9 +2792,9 @@ pub const JSON: u128 = NumberFormatBuilder::new()
     .build_strict();
 
 // TOML [34569AB]
-/// Number format for a [`TOML`] literal floating-point number.
+/// Number format for a [`TOML`][`TOML-REF`] literal floating-point number.
 ///
-/// [`TOML`]: https://toml.io/en/
+/// [`TOML-REF`]: https://toml.io/en/
 #[rustfmt::skip]
 pub const TOML: u128 = NumberFormatBuilder::new()
     .digit_separator(num::NonZeroU8::new(b'_'))
@@ -2806,15 +2806,15 @@ pub const TOML: u128 = NumberFormatBuilder::new()
     .build_strict();
 
 // YAML (defined in-terms of JSON schema).
-/// Number format for a [`YAML`] literal floating-point number.
+/// Number format for a [`YAML`][`YAML-REF`] literal floating-point number.
 ///
-/// [`YAML`]: https://yaml.org/
+/// [`YAML-REF`]: https://yaml.org/
 pub const YAML: u128 = JSON;
 
 // XML [01234578MN]
-/// Number format for a [`XML`] literal floating-point number.
+/// Number format for an [`XML`][`XML-REF`] literal floating-point number.
 ///
-/// [`XML`]: https://en.wikipedia.org/wiki/XML
+/// [`XML-REF`]: https://en.wikipedia.org/wiki/XML
 #[rustfmt::skip]
 pub const XML: u128 = NumberFormatBuilder::new()
     .required_exponent_digits(false)

lexical-util/src/format.rs

@@ -320,10 +320,10 @@
 - [`ZIG_STRING`]: Number format to parse a [`Zig`] float from string.
 - [`SAGE_LITERAL`]: Number format for a [`Sage`] literal floating-point number.
 - [`SAGE_STRING`]: Number format to parse a [`Sage`] float from string.
-- [`JSON`]: Number format for a [`JSON`] literal floating-point number.
-- [`TOML`]: Number format for a [`TOML`] literal floating-point number.
-- [`YAML`]: Number format for a [`YAML`] literal floating-point number.
-- [`XML`]: Number format for a [`XML`] literal floating-point number.
+- [`JSON`]: Number format for a [`JSON`][`JSON-REF`] literal floating-point number.
+- [`TOML`]: Number format for a [`TOML`][`TOML-REF`] literal floating-point number.
+- [`YAML`]: Number format for a [`YAML`][`YAML-REF`] literal floating-point number.
+- [`XML`]: Number format for an [`XML`][`XML-REF`] literal floating-point number.
 - [`SQLITE`]: Number format for a [`SQLite`] literal floating-point number.
 - [`POSTGRESQL`]: Number format for a [`PostgreSQL`] literal floating-point number.
 - [`MYSQL`]: Number format for a [`MySQL`] literal floating-point number.
@@ -616,10 +616,10 @@
 [`Matlab`]: https://www.mathworks.com/products/matlab.html
 [`Zig`]: https://ziglang.org/
 [`Sage`]: https://www.sagemath.org/
-[`JSON`]: https://www.json.org/json-en.html
-[`TOML`]: https://toml.io/en/
-[`YAML`]: https://yaml.org/
-[`XML`]: https://en.wikipedia.org/wiki/XML
+[`JSON-REF`]: https://www.json.org/json-en.html
+[`TOML-REF`]: https://toml.io/en/
+[`YAML-REF`]: https://yaml.org/
+[`XML-REF`]: https://en.wikipedia.org/wiki/XML
 [`SQLite`]: https://www.sqlite.org/
 [`PostgreSQL`]: https://www.postgresql.org/
 [`MySQL`]: https://www.mysql.com/

lexical-write-float/src/lib.rs

@@ -31,22 +31,7 @@
 //!
 //! With the default options, using [`FORMATTED_SIZE_DECIMAL`]
 //! guarantees the buffer will be large enough to write the digits for all
-//! numbers of that type. In addition, `digits` is guaranteed to start at the
-//! same address as `buffer`, that is:
-//!
-//! ```rust
-//! # use core::str;
-//! use lexical_write_integer::{FormattedSize, ToLexical};
-//!
-//! let mut buffer = [0u8; u64::FORMATTED_SIZE_DECIMAL];
-//! let digits = 1234u64.to_lexical(&mut buffer);
-//! assert_eq!(str::from_utf8(digits), Ok("1234"));
-//!
-//! // NOTE: This is done for demonstration: don't use this in real code.
-//! let digits_ptr = digits.as_ptr();
-//! let buffer_ptr = buffer.as_ptr();
-//! assert_eq!(digits_ptr, buffer_ptr);
-//! ```
+//! numbers of that type.
 //!
 //! [`FORMATTED_SIZE_DECIMAL`]: FormattedSize::FORMATTED_SIZE_DECIMAL
 //!