lexical-util 1.0.7

//! Implement string conversion routines in a single trait.

// NOTE:
//  We use macros to define the traits, rather than implement here
//  since we can't define traits for types when both are defined outside
//  the current crate, including in workspaces.

// FROM LEXICAL

/// Define the [`FromLexical`] trait.
///
/// * `name`: The name of the crate calling the function.
/// * `value`: A numerical value to use for the example.
/// * `t`: The type of the number for the example.
/// * `len`: The length of the string form of `value`.
///
/// # Examples
///
/// ```rust,ignore
/// from_lexical!("lexical_core", 1234, u64, 4);
/// ```
///
/// [`FromLexical`]: https://docs.rs/lexical-core/latest/lexical_core/trait.FromLexical.html
#[macro_export]
#[cfg(any(feature = "parse-floats", feature = "parse-integers"))]
macro_rules! from_lexical {
    ($name:literal, $value:literal, $t:ty, $len:literal $(, #[$attr:meta])? $(,)?) => {
        /// Trait for numerical types that can be parsed from bytes.
        $(#[$attr])?
        pub trait FromLexical: lexical_util::num::Number {
            /// Checked parser for a string-to-number conversion.
            ///
            /// This method parses the entire string, returning an error if
            /// any invalid digits are found during parsing. Returns a [`Result`]
            /// containing either the parsed value, or an error containing
            /// any errors that occurred during parsing.
            ///
            /// * `bytes`   - Slice containing a numeric string.
            ///
            /// # Examples
            ///
            /// ```rust
            #[doc = concat!("# assert_eq!(", stringify!($len), ", \"", stringify!($value), "\".len());")]
            #[doc = concat!("use ", $name, "::FromLexical;")]
            ///
            #[doc = concat!("let value = \"", stringify!($value), "\";")]
            #[doc = concat!("let parsed = ", stringify!($t), "::from_lexical(value.as_bytes());")]
            #[doc = concat!("assert_eq!(parsed, Ok(", stringify!($value), "));")]
            /// ```
            fn from_lexical(bytes: &[u8]) -> lexical_util::result::Result<Self>;

            /// Checked parser for a string-to-number conversion.
            ///
            /// This method parses until an invalid digit is found (or the end
            /// of the string), returning the number of processed digits
            /// and the parsed value until that point. Returns a [`Result`]
            /// containing either the parsed value and the number of processed
            /// digits, or an error containing any errors that occurred during
            /// parsing.
            ///
            /// * `bytes`   - Slice containing a numeric string.
            ///
            /// # Examples
            ///
            /// ```rust
            #[doc = concat!("# assert_eq!(", stringify!($len), ", \"", stringify!($value), "\".len());")]
            #[doc = concat!("use ", $name, "::FromLexical;")]
            ///
            #[doc = concat!("let value = \"", stringify!($value), "\";")]
            #[doc = concat!("let parsed = ", stringify!($t), "::from_lexical_partial(value.as_bytes());")]
            #[doc = concat!("assert_eq!(parsed, Ok((", stringify!($value), ", ", stringify!($len), ")));")]
            /// ```
            fn from_lexical_partial(bytes: &[u8]) -> lexical_util::result::Result<(Self, usize)>;
        }
    };
}

/// Define the [`FromLexicalWithOptions`] trait.
///
/// * `name`: The name of the crate calling the function.
/// * `value`: A numerical value to use for the example.
/// * `t`: The type of the number for the example.
/// * `len`: The length of the string form of `value`.
/// * `ops_t`: The options type.
///
/// # Examples
///
/// ```rust,ignore
/// from_lexical_with_options!("lexical_core", 1234, u64, 4, ParseIntegerOptions);
/// ```
///
/// [`FromLexicalWithOptions`]: https://docs.rs/lexical-core/latest/lexical_core/trait.FromLexicalWithOptions.html
#[macro_export]
#[cfg(any(feature = "parse-floats", feature = "parse-integers"))]
macro_rules! from_lexical_with_options {
    ($name:literal, $value:literal, $t:ty, $len:literal, $ops_t:ty $(, #[$attr:meta])? $(,)?) => {
        /// Trait for numerical types that can be parsed from bytes with custom options.
        ///
        /// The [`Options`][Self::Options] type specifies the configurable
        /// options to provide.
        $(#[$attr])?
        pub trait FromLexicalWithOptions: lexical_util::num::Number {
            /// Custom formatting options for parsing a number.
            type Options: lexical_util::options::ParseOptions;

            /// Checked parser for a string-to-number conversion.
            ///
            /// This method parses the entire string, returning an error if
            /// any invalid digits are found during parsing. The parsing
            /// is dictated by the options, which specifies special
            /// float strings, required float components, digit separators,
            /// exponent characters, and more. Returns a [`Result`] containing
            /// either the parsed value, or an error containing any errors
            /// that occurred during parsing.
            ///
            /// * `FORMAT`  - Flags and characters designating the number grammar.
            /// * `bytes`   - Slice containing a numeric string.
            /// * `options` - Options to dictate number parsing.
            ///
            /// The `FORMAT` packed struct is built using [`NumberFormatBuilder`].
            /// Any invalid number format will prevent parsing, returning
            /// the appropriate format error. If you are unsure which format
            /// to use, use [`STANDARD`].
            ///
            /// # Examples
            ///
            /// ```rust
            #[doc = concat!("# assert_eq!(", stringify!($len), ", \"", stringify!($value), "\".len());")]
            #[doc = concat!("use ", $name, "::{format, FromLexicalWithOptions, ", stringify!($ops_t), "};")]
            ///
            /// const FORMAT: u128 = format::STANDARD;
            #[doc = concat!("const OPTIONS: ", stringify!($ops_t), " = ", stringify!($ops_t), "::new();")]
            #[doc = concat!("let value = \"", stringify!($value), "\";")]
            #[doc = concat!("let parsed = ", stringify!($t), "::from_lexical_with_options::<FORMAT>(value.as_bytes(), &OPTIONS);")]
            #[doc = concat!("assert_eq!(parsed, Ok(", stringify!($value), "));")]
            /// ```
            ///
            /// [`NumberFormatBuilder`]: lexical_util::format::NumberFormatBuilder
            /// [`STANDARD`]: lexical_util::format::STANDARD
            fn from_lexical_with_options<const FORMAT: u128>(
                bytes: &[u8],
                options: &Self::Options,
            ) -> lexical_util::result::Result<Self>;

            /// Checked parser for a string-to-number conversion.
            ///
            /// This method parses until an invalid digit is found (or the end
            /// of the string), returning the number of processed digits
            /// and the parsed value until that point. Returns a [`Result`]
            /// containing either the parsed value and the number of
            /// processed digits, or an error containing any errors that
            /// occurred during parsing.
            ///
            /// * `FORMAT`  - Flags and characters designating the number grammar.
            /// * `bytes`   - Slice containing a numeric string.
            /// * `options` - Options to dictate number parsing.
            ///
            /// The `FORMAT` packed struct is built using [`NumberFormatBuilder`].
            /// Any invalid number format will prevent parsing, returning
            /// the appropriate format error. If you are unsure which format
            /// to use, use [`STANDARD`].
            ///
            /// # Examples
            ///
            /// ```rust
            #[doc = concat!("# assert_eq!(", stringify!($len), ", \"", stringify!($value), "\".len());")]
            #[doc = concat!("use ", $name, "::{format, FromLexicalWithOptions, ", stringify!($ops_t), "};")]
            ///
            /// const FORMAT: u128 = format::STANDARD;
            #[doc = concat!("const OPTIONS: ", stringify!($ops_t), " = ", stringify!($ops_t), "::new();")]
            ///
            #[doc = concat!("let value = \"", stringify!($value), "\";")]
            #[doc = concat!(
                "let parsed = ",
                stringify!($t),
                "::from_lexical_partial_with_options::<FORMAT>(value.as_bytes(), &OPTIONS);"
            )]
            #[doc = concat!("assert_eq!(parsed, Ok((", stringify!($value), ", ", stringify!($len), ")));")]
            /// ```
            ///
            /// [`NumberFormatBuilder`]: lexical_util::format::NumberFormatBuilder
            /// [`STANDARD`]: lexical_util::format::STANDARD
            fn from_lexical_partial_with_options<const FORMAT: u128>(
                bytes: &[u8],
                options: &Self::Options,
            ) -> lexical_util::result::Result<(Self, usize)>;
        }
    };
}

// TO LEXICAL

/// Define the [`ToLexical`] trait.
///
/// * `name`: The name of the crate calling the function.
/// * `value`: A numerical value to use for the example.
/// * `t`: The type of the number for the example.
///
/// # Examples
///
/// ```rust,ignore
/// to_lexical!("lexical_core", 1234, u64);
/// ```
///
/// [`ToLexical`]: https://docs.rs/lexical-core/latest/lexical_core/trait.ToLexical.html
#[macro_export]
#[cfg(any(feature = "write-floats", feature = "write-integers"))]
macro_rules! to_lexical {
    ($name:literal, $value:literal, $t:ty $(, #[$attr:meta])? $(,)?) => {
        /// Trait for numerical types that can be serialized to bytes.
        ///
        /// To determine the number of bytes required to serialize a value to
        /// string, check the associated constants from a required trait:
        /// - [`FORMATTED_SIZE`]: The number of bytes required for any number for any
        ///   radix, that is, `2` to `36`.
        /// - [`FORMATTED_SIZE_DECIMAL`]: The number of bytes required for decimal (base
        ///   10) numbers.
        ///
        /// [`FORMATTED_SIZE`]: crate::FormattedSize::FORMATTED_SIZE
        /// [`FORMATTED_SIZE_DECIMAL`]: crate::FormattedSize::FORMATTED_SIZE_DECIMAL
        $(#[$attr])?
        pub trait ToLexical:
            lexical_util::constants::FormattedSize + lexical_util::num::Number
        {
            /// Serializer for a number-to-string conversion.
            ///
            /// Returns a subslice of the input buffer containing the written bytes,
            /// starting from the same address in memory as the input slice. That
            /// is, the `bytes` provided to the function and the returned buffer
            /// reference the same buffer, just with the number of elements truncated
            /// to the written digits.
            ///
            /// * `value`   - Number to serialize.
            /// * `bytes`   - Buffer to write number to.
            ///
            /// # Examples
            ///
            /// ```rust
            /// use core::str;
            ///
            #[doc = concat!("use ", $name, "::{format, FormattedSize, ToLexical};")]
            ///
            #[doc = concat!("let value: ", stringify!($t), " = ", stringify!($value), ";")]
            #[doc = concat!("let mut buffer = [0u8; ", stringify!($t), "::FORMATTED_SIZE_DECIMAL];")]
            /// let digits = value.to_lexical(&mut buffer);
            #[doc = concat!("assert_eq!(str::from_utf8(digits), Ok(\"", stringify!($value), "\"));")]
            /// ```
            ///
            /// # Panics
            ///
            /// Panics if the buffer is not of sufficient size. The caller
            /// must provide a slice of sufficient size. In order to ensure
            /// the function will not panic, ensure the buffer has at least
            /// [`FORMATTED_SIZE_DECIMAL`] elements.
            ///
            /// [`FORMATTED_SIZE_DECIMAL`]: lexical_util::constants::FormattedSize::FORMATTED_SIZE_DECIMAL
            fn to_lexical<'a>(self, bytes: &'a mut [u8]) -> &'a mut [u8];
        }
    };
}

/// Define the [`ToLexicalWithOptions`] trait.
///
/// * `name`: The name of the crate calling the function.
/// * `value`: A numerical value to use for the example.
/// * `t`: The type of the number for the example.
/// * `ops_t`: The options type.
///
/// # Examples
///
/// ```rust,ignore
/// to_lexical_with_options!("lexical_core", 1234, u64, WriteIntegerOptions);
/// ```
///
/// [`ToLexicalWithOptions`]: https://docs.rs/lexical-core/latest/lexical_core/trait.ToLexicalWithOptions.html
#[macro_export]
#[cfg(any(feature = "write-floats", feature = "write-integers"))]
macro_rules! to_lexical_with_options {
    ($name:literal, $value:literal, $t:ty, $ops_t:ty $(, #[$attr:meta])? $(,)?) => {
        /// Trait for numerical types that can be serialized to bytes with custom
        /// options.
        ///
        /// To determine the number of bytes required to serialize a value to
        /// string, check the associated constants from a required trait:
        /// - [`FORMATTED_SIZE`]: The number of bytes required for any number for any
        ///   radix, that is, `2` to `36`.
        /// - [`FORMATTED_SIZE_DECIMAL`]: The number of bytes required for decimal (base
        ///   10) numbers.
        ///
        /// The [`Options`][Self::Options] type specifies the configurable options to provide.
        ///
        /// [`FORMATTED_SIZE`]: crate::FormattedSize::FORMATTED_SIZE
        /// [`FORMATTED_SIZE_DECIMAL`]: crate::FormattedSize::FORMATTED_SIZE_DECIMAL
        $(#[$attr])?
        pub trait ToLexicalWithOptions:
            lexical_util::constants::FormattedSize + lexical_util::num::Number
        {
            /// Custom formatting options for writing a number.
            type Options: lexical_util::options::WriteOptions;

            /// Serializer for a number-to-string conversion.
            ///
            /// Returns a subslice of the input buffer containing the written bytes,
            /// starting from the same address in memory as the input slice. That
            /// is, the `bytes` provided to the function and the returned buffer
            /// reference the same buffer, just with the number of elements truncated
            /// to the written digits.
            ///
            /// * `FORMAT`  - Flags and characters designating the number grammar.
            /// * `value`   - Number to serialize.
            /// * `bytes`   - Buffer to write number to.
            /// * `options` - Options for number formatting.
            ///
            /// `FORMAT` should be built using [`NumberFormatBuilder`] and includes
            /// options such as the numerical radix for writing the value to string.
            /// `options` specificies extra, additional configurations such as
            /// special values like `NaN` or `+Infinity` for how to serialize
            /// the number.
            ///
            /// [`NumberFormatBuilder`]: crate::NumberFormatBuilder
            ///
            /// # Examples
            ///
            /// ```rust
            /// use core::str;
            ///
            #[doc = concat!(
                "use ",
                $name,
                "::{format, FormattedSize, ",
                stringify!($ops_t),
                ", ToLexicalWithOptions};"
            )]
            ///
            /// const FORMAT: u128 = format::STANDARD;
            #[doc = concat!("const OPTIONS: ", stringify!($ops_t), " = ", stringify!($ops_t), "::new();")]
            #[doc = concat!(
                "const BUFFER_SIZE: usize = OPTIONS.buffer_size_const::<",
                stringify!($t),
                ", FORMAT>();"
            )]
            ///
            #[doc = concat!("let value: ", stringify!($t), " = ", stringify!($value), ";")]
            /// let mut buffer = [0u8; BUFFER_SIZE];
            /// let digits = value.to_lexical_with_options::<FORMAT>(&mut buffer, &OPTIONS);
            #[doc = concat!("assert_eq!(str::from_utf8(digits), Ok(\"", stringify!($value), "\"));")]
            /// ```
            ///
            /// # Panics
            ///
            /// Panics if the buffer is not of sufficient size. The caller
            /// must provide a slice of sufficient size. In order to ensure
            /// the function will not panic, ensure the buffer has at least
            /// [`Options::buffer_size_const`] elements. This is required
            /// only when changing the number of significant digits, the
            /// exponent break point, or disabling scientific notation.
            ///
            /// If you are not using [`min_significant_digits`] (floats only),
            /// 1200 bytes is always enough to hold the the output for a custom
            /// radix, and `400` is always enough for decimal strings.
            ///
            /// **Floats Only**
            ///
            /// These panics are only when using uncommon features for float
            /// writing, represent configuration errors, so runtime error
            /// handling is not provided.
            ///
            /// Also panics if the provided number format is invalid, or
            /// if the mantissa radix is not equal to the exponent base
            /// and the mantissa radix/exponent base combinations are
            /// not in the following list:
            ///
            /// - `4, 2`
            /// - `8, 2`
            /// - `16, 2`
            /// - `32, 2`
            /// - `16, 4`
            ///
            /// Panics as well if `the` NaN or `Inf` string provided to the writer
            /// is disabled, but the value provided is `NaN` or `Inf`, respectively.
            ///
            #[doc = concat!(
                "[`Options::buffer_size_const`]: crate::",
                stringify!($ops_t),
                "::buffer_size_const"
            )]
            /// [`FORMATTED_SIZE`]: crate::FormattedSize::FORMATTED_SIZE
            /// [`min_significant_digits`]: https://docs.rs/lexical-core/latest/lexical_core/struct.WriteFloatOptionsBuilder.html#method.min_significant_digits
            fn to_lexical_with_options<'a, const FORMAT: u128>(
                self,
                bytes: &'a mut [u8],
                options: &Self::Options,
            ) -> &'a mut [u8];
        }
    };
}