From fc9e40ab1a3582b29d553da73ac5a445a902a015 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 18 Dec 2024 11:22:32 +1100 Subject: [PATCH 1/5] units: Re-order impl_parse_str_from_int_infallible We have a public macro `impl_parse_str_from_int_infallible` and a helper macro used by it, both pubicly exported. To assist readers understanding what is going on put the helper below the other. Code move only, no logic change. --- units/src/parse.rs | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/units/src/parse.rs b/units/src/parse.rs index ec36d4b94..34cbfaba3 100644 --- a/units/src/parse.rs +++ b/units/src/parse.rs @@ -91,23 +91,6 @@ pub fn int + Into>(s: S) -> Result for $to` using `parse::int`, mapping the output using infallible -/// conversion function `fn`. -#[macro_export] -macro_rules! impl_tryfrom_str_from_int_infallible { - ($($from:ty, $to:ident, $inner:ident, $fn:ident);*) => { - $( - impl $crate::_export::_core::convert::TryFrom<$from> for $to { - type Error = $crate::parse::ParseIntError; - - fn try_from(s: $from) -> $crate::_export::_core::result::Result { - $crate::parse::int::<$inner, $from>(s).map($to::$fn) - } - } - )* - } -} - /// Implements `FromStr` and `TryFrom<{&str, String, Box}> for $to` using `parse::int`, mapping /// the output using infallible conversion function `fn`. /// @@ -130,6 +113,23 @@ macro_rules! impl_parse_str_from_int_infallible { } } +/// Implements `TryFrom<$from> for $to` using `parse::int`, mapping the output using infallible +/// conversion function `fn`. +#[macro_export] +macro_rules! impl_tryfrom_str_from_int_infallible { + ($($from:ty, $to:ident, $inner:ident, $fn:ident);*) => { + $( + impl $crate::_export::_core::convert::TryFrom<$from> for $to { + type Error = $crate::parse::ParseIntError; + + fn try_from(s: $from) -> $crate::_export::_core::result::Result { + $crate::parse::int::<$inner, $from>(s).map($to::$fn) + } + } + )* + } +} + /// Implements `TryFrom<$from> for $to`. #[macro_export] macro_rules! impl_tryfrom_str { From 4cc7aae6b925ad6e8a853e6d2741b2a862c29e05 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 31 Dec 2024 13:00:10 +1100 Subject: [PATCH 2/5] Hide impl_tryfrom_str_from_int_infallible This macro is a helper for `impl_parse_str_from_int_infallible` used to reduce code duplication. It does not, and should not, need to be part of the public API - hide it. --- api/units/all-features.txt | 1 - api/units/alloc-only.txt | 1 - api/units/no-features.txt | 1 - units/src/parse.rs | 1 + 4 files changed, 1 insertion(+), 3 deletions(-) diff --git a/api/units/all-features.txt b/api/units/all-features.txt index f084694c5..00fdd5dd6 100644 --- a/api/units/all-features.txt +++ b/api/units/all-features.txt @@ -1196,7 +1196,6 @@ pub fn u64::mul(self, rhs: bitcoin_units::weight::Weight) -> Self::Output pub macro bitcoin_units::impl_parse_str! pub macro bitcoin_units::impl_parse_str_from_int_infallible! pub macro bitcoin_units::impl_tryfrom_str! -pub macro bitcoin_units::impl_tryfrom_str_from_int_infallible! pub mod bitcoin_units pub mod bitcoin_units::amount pub mod bitcoin_units::amount::serde diff --git a/api/units/alloc-only.txt b/api/units/alloc-only.txt index d64e17e23..679646265 100644 --- a/api/units/alloc-only.txt +++ b/api/units/alloc-only.txt @@ -1067,7 +1067,6 @@ pub fn u64::mul(self, rhs: bitcoin_units::weight::Weight) -> Self::Output pub macro bitcoin_units::impl_parse_str! pub macro bitcoin_units::impl_parse_str_from_int_infallible! pub macro bitcoin_units::impl_tryfrom_str! -pub macro bitcoin_units::impl_tryfrom_str_from_int_infallible! pub mod bitcoin_units pub mod bitcoin_units::amount pub mod bitcoin_units::block diff --git a/api/units/no-features.txt b/api/units/no-features.txt index db86722ee..db9ed7378 100644 --- a/api/units/no-features.txt +++ b/api/units/no-features.txt @@ -1021,7 +1021,6 @@ pub fn u64::mul(self, rhs: bitcoin_units::weight::Weight) -> Self::Output pub macro bitcoin_units::impl_parse_str! pub macro bitcoin_units::impl_parse_str_from_int_infallible! pub macro bitcoin_units::impl_tryfrom_str! -pub macro bitcoin_units::impl_tryfrom_str_from_int_infallible! pub mod bitcoin_units pub mod bitcoin_units::amount pub mod bitcoin_units::block diff --git a/units/src/parse.rs b/units/src/parse.rs index 34cbfaba3..398a87798 100644 --- a/units/src/parse.rs +++ b/units/src/parse.rs @@ -116,6 +116,7 @@ macro_rules! impl_parse_str_from_int_infallible { /// Implements `TryFrom<$from> for $to` using `parse::int`, mapping the output using infallible /// conversion function `fn`. #[macro_export] +#[doc(hidden)] // Helper macro called by `impl_parse_str_from_int_infallible`. macro_rules! impl_tryfrom_str_from_int_infallible { ($($from:ty, $to:ident, $inner:ident, $fn:ident);*) => { $( From 2675cd1040cfe254a9258c080a65ab253c8f9250 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 18 Dec 2024 11:24:39 +1100 Subject: [PATCH 3/5] units: Re-order impl_parse_str We have a public macro `impl_parse_str` and a helper macro used by it, both pubicly exported. As we did for `impl_parse_str_from_int_infallible`; to assist readers understanding what is going on put the helper below the other. Done as a separate patch to make the diff easier to read. Internal change only, no logic change. --- units/src/parse.rs | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/units/src/parse.rs b/units/src/parse.rs index 398a87798..d1f402dec 100644 --- a/units/src/parse.rs +++ b/units/src/parse.rs @@ -131,22 +131,6 @@ macro_rules! impl_tryfrom_str_from_int_infallible { } } -/// Implements `TryFrom<$from> for $to`. -#[macro_export] -macro_rules! impl_tryfrom_str { - ($($from:ty, $to:ty, $err:ty, $inner_fn:expr);*) => { - $( - impl $crate::_export::_core::convert::TryFrom<$from> for $to { - type Error = $err; - - fn try_from(s: $from) -> $crate::_export::_core::result::Result { - $inner_fn(s) - } - } - )* - } -} - /// Implements standard parsing traits for `$type` by calling into `$inner_fn`. #[macro_export] macro_rules! impl_parse_str { @@ -165,6 +149,22 @@ macro_rules! impl_parse_str { } } +/// Implements `TryFrom<$from> for $to`. +#[macro_export] +macro_rules! impl_tryfrom_str { + ($($from:ty, $to:ty, $err:ty, $inner_fn:expr);*) => { + $( + impl $crate::_export::_core::convert::TryFrom<$from> for $to { + type Error = $err; + + fn try_from(s: $from) -> $crate::_export::_core::result::Result { + $inner_fn(s) + } + } + )* + } +} + /// Removes the prefix `0x` (or `0X`) from a hex string. /// /// # Errors From 706c7c9f5fca175226c09ec9e8f3431ab4999833 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 31 Dec 2024 13:02:36 +1100 Subject: [PATCH 4/5] Hide impl_tryfrom_str This macro is a helper for `impl_parse_str` used to reduce code duplication. It does not, and should not, need to be part of the public API - hide it. --- api/units/all-features.txt | 1 - api/units/alloc-only.txt | 1 - api/units/no-features.txt | 1 - units/src/parse.rs | 1 + 4 files changed, 1 insertion(+), 3 deletions(-) diff --git a/api/units/all-features.txt b/api/units/all-features.txt index 00fdd5dd6..a788adba0 100644 --- a/api/units/all-features.txt +++ b/api/units/all-features.txt @@ -1195,7 +1195,6 @@ pub fn u64::from(value: bitcoin_units::weight::Weight) -> Self pub fn u64::mul(self, rhs: bitcoin_units::weight::Weight) -> Self::Output pub macro bitcoin_units::impl_parse_str! pub macro bitcoin_units::impl_parse_str_from_int_infallible! -pub macro bitcoin_units::impl_tryfrom_str! pub mod bitcoin_units pub mod bitcoin_units::amount pub mod bitcoin_units::amount::serde diff --git a/api/units/alloc-only.txt b/api/units/alloc-only.txt index 679646265..61e5afbfd 100644 --- a/api/units/alloc-only.txt +++ b/api/units/alloc-only.txt @@ -1066,7 +1066,6 @@ pub fn u64::from(value: bitcoin_units::weight::Weight) -> Self pub fn u64::mul(self, rhs: bitcoin_units::weight::Weight) -> Self::Output pub macro bitcoin_units::impl_parse_str! pub macro bitcoin_units::impl_parse_str_from_int_infallible! -pub macro bitcoin_units::impl_tryfrom_str! pub mod bitcoin_units pub mod bitcoin_units::amount pub mod bitcoin_units::block diff --git a/api/units/no-features.txt b/api/units/no-features.txt index db9ed7378..367d8501a 100644 --- a/api/units/no-features.txt +++ b/api/units/no-features.txt @@ -1020,7 +1020,6 @@ pub fn u64::from(value: bitcoin_units::weight::Weight) -> Self pub fn u64::mul(self, rhs: bitcoin_units::weight::Weight) -> Self::Output pub macro bitcoin_units::impl_parse_str! pub macro bitcoin_units::impl_parse_str_from_int_infallible! -pub macro bitcoin_units::impl_tryfrom_str! pub mod bitcoin_units pub mod bitcoin_units::amount pub mod bitcoin_units::block diff --git a/units/src/parse.rs b/units/src/parse.rs index d1f402dec..35c880f37 100644 --- a/units/src/parse.rs +++ b/units/src/parse.rs @@ -151,6 +151,7 @@ macro_rules! impl_parse_str { /// Implements `TryFrom<$from> for $to`. #[macro_export] +#[doc(hidden)] // Helper macro called by `impl_parse_str`. macro_rules! impl_tryfrom_str { ($($from:ty, $to:ty, $err:ty, $inner_fn:expr);*) => { $( From b1399d193fcb20c09457a1f22c5c1dd8009c84b1 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 18 Dec 2024 11:26:14 +1100 Subject: [PATCH 5/5] units: Improve rustdocs on macros Extensively document the two _real_ public macros (not the helpers) in `units::parse`. --- units/src/parse.rs | 48 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/units/src/parse.rs b/units/src/parse.rs index 35c880f37..ec927716f 100644 --- a/units/src/parse.rs +++ b/units/src/parse.rs @@ -91,10 +91,30 @@ pub fn int + Into>(s: S) -> Result}> for $to` using `parse::int`, mapping -/// the output using infallible conversion function `fn`. +/// Implements standard parsing traits for `$type` by calling `parse::int`. /// -/// The `Error` type is `ParseIntError` +/// Once the string is converted to an integer the infallible conversion function `fn` is used to +/// create the type `to`. +/// +/// Implements: +/// +/// * `FromStr` +/// * `TryFrom<&str>` +/// +/// And if `alloc` feature is enabled in calling crate: +/// +/// * `TryFrom>` +/// * `TryFrom` +/// +/// # Arguments +/// +/// * `to` - the type converted to e.g., `impl From<&str> for $to`. +/// * `err` - the error type returned by `$inner_fn` (implies returned by `FromStr` and `TryFrom`). +/// * `fn`: The infallible conversion function to call to convert from an integer. +/// +/// # Errors +/// +/// If parsing the string fails then a `units::parse::ParseIntError` is returned. #[macro_export] macro_rules! impl_parse_str_from_int_infallible { ($to:ident, $inner:ident, $fn:ident) => { @@ -131,7 +151,27 @@ macro_rules! impl_tryfrom_str_from_int_infallible { } } -/// Implements standard parsing traits for `$type` by calling into `$inner_fn`. +/// Implements standard parsing traits for `$type` by calling through to `$inner_fn`. +/// +/// Implements: +/// +/// * `FromStr` +/// * `TryFrom<&str>` +/// +/// And if `alloc` feature is enabled in calling crate: +/// +/// * `TryFrom>` +/// * `TryFrom` +/// +/// # Arguments +/// +/// * `to` - the type converted to e.g., `impl From<&str> for $to`. +/// * `err` - the error type returned by `$inner_fn` (implies returned by `FromStr` and `TryFrom`). +/// * `inner_fn`: The fallible conversion function to call to convert from a string reference. +/// +/// # Errors +/// +/// All functions use the error returned by `$inner_fn`. #[macro_export] macro_rules! impl_parse_str { ($to:ty, $err:ty, $inner_fn:expr) => {