From a4fe67645ac2ac130de5509b84c142b0a0f63179 Mon Sep 17 00:00:00 2001 From: ndungudedan Date: Thu, 6 Feb 2025 22:23:45 +0300 Subject: [PATCH] Use relative::* or absolute::* in locktime example Users should be encouraged to explicitly use relative::* or absolute::* instead of just LockTime, Time, or Height so that it is clear when looking at the code if it is a relative or absolute locktime. --- primitives/src/locktime/absolute.rs | 58 ++++++++++++++--------------- primitives/src/locktime/relative.rs | 38 +++++++++---------- 2 files changed, 48 insertions(+), 48 deletions(-) diff --git a/primitives/src/locktime/absolute.rs b/primitives/src/locktime/absolute.rs index 976f56143..ae924e26b 100644 --- a/primitives/src/locktime/absolute.rs +++ b/primitives/src/locktime/absolute.rs @@ -42,9 +42,9 @@ pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, P /// # Examples /// /// ``` -/// # use bitcoin_primitives::absolute::{LockTime, LockTime::*}; -/// # let n = LockTime::from_consensus(741521); // n OP_CHECKLOCKTIMEVERIFY -/// # let lock_time = LockTime::from_consensus(741521); // nLockTime +/// # use bitcoin_primitives::absolute::{self, LockTime::*}; +/// # let n = absolute::LockTime::from_consensus(741521); // n OP_CHECKLOCKTIMEVERIFY +/// # let lock_time = absolute::LockTime::from_consensus(741521); // nLockTime /// // To compare absolute lock times there are various `is_satisfied_*` methods, you may also use: /// let _is_satisfied = match (n, lock_time) { /// (Blocks(n), Blocks(lock_time)) => n <= lock_time, @@ -59,10 +59,10 @@ pub enum LockTime { /// # Examples /// /// ```rust - /// use bitcoin_primitives::absolute::LockTime; + /// use bitcoin_primitives::absolute; /// /// let block: u32 = 741521; - /// let n = LockTime::from_height(block).expect("valid height"); + /// let n = absolute::LockTime::from_height(block).expect("valid height"); /// assert!(n.is_block_height()); /// assert_eq!(n.to_consensus_u32(), block); /// ``` @@ -72,10 +72,10 @@ pub enum LockTime { /// # Examples /// /// ```rust - /// use bitcoin_primitives::absolute::LockTime; + /// use bitcoin_primitives::absolute; /// /// let seconds: u32 = 1653195600; // May 22nd, 5am UTC. - /// let n = LockTime::from_time(seconds).expect("valid time"); + /// let n = absolute::LockTime::from_time(seconds).expect("valid time"); /// assert!(n.is_block_time()); /// assert_eq!(n.to_consensus_u32(), seconds); /// ``` @@ -95,9 +95,9 @@ impl LockTime { /// # Examples /// /// ``` - /// # use bitcoin_primitives::absolute::LockTime; + /// # use bitcoin_primitives::absolute; /// let hex_str = "0x61cf9980"; // Unix timestamp for January 1, 2022 - /// let lock_time = LockTime::from_hex(hex_str)?; + /// let lock_time = absolute::LockTime::from_hex(hex_str)?; /// assert_eq!(lock_time.to_consensus_u32(), 0x61cf9980); /// /// # Ok::<_, units::parse::PrefixedHexError>(()) @@ -112,9 +112,9 @@ impl LockTime { /// # Examples /// /// ``` - /// # use bitcoin_primitives::absolute::LockTime; + /// # use bitcoin_primitives::absolute; /// let hex_str = "61cf9980"; // Unix timestamp for January 1, 2022 - /// let lock_time = LockTime::from_unprefixed_hex(hex_str)?; + /// let lock_time = absolute::LockTime::from_unprefixed_hex(hex_str)?; /// assert_eq!(lock_time.to_consensus_u32(), 0x61cf9980); /// /// # Ok::<_, units::parse::UnprefixedHexError>(()) @@ -129,11 +129,11 @@ impl LockTime { /// # Examples /// /// ```rust - /// # use bitcoin_primitives::absolute::LockTime; + /// # use bitcoin_primitives::absolute; /// /// // `from_consensus` roundtrips as expected with `to_consensus_u32`. /// let n_lock_time: u32 = 741521; - /// let lock_time = LockTime::from_consensus(n_lock_time); + /// let lock_time = absolute::LockTime::from_consensus(n_lock_time); /// assert_eq!(lock_time.to_consensus_u32(), n_lock_time); #[inline] pub fn from_consensus(n: u32) -> Self { @@ -157,9 +157,9 @@ impl LockTime { /// # Examples /// /// ```rust - /// # use bitcoin_primitives::absolute::LockTime; - /// assert!(LockTime::from_height(741521).is_ok()); - /// assert!(LockTime::from_height(1653195600).is_err()); + /// # use bitcoin_primitives::absolute; + /// assert!(absolute::LockTime::from_height(741521).is_ok()); + /// assert!(absolute::LockTime::from_height(1653195600).is_err()); /// ``` #[inline] pub fn from_height(n: u32) -> Result { @@ -183,9 +183,9 @@ impl LockTime { /// # Examples /// /// ```rust - /// # use bitcoin_primitives::absolute::LockTime; - /// assert!(LockTime::from_time(1653195600).is_ok()); - /// assert!(LockTime::from_time(741521).is_err()); + /// # use bitcoin_primitives::absolute; + /// assert!(absolute::LockTime::from_time(1653195600).is_ok()); + /// assert!(absolute::LockTime::from_time(741521).is_err()); /// ``` #[inline] pub fn from_time(n: u32) -> Result { @@ -223,12 +223,12 @@ impl LockTime { /// # Examples /// /// ```no_run - /// # use bitcoin_primitives::absolute::{LockTime, Height, Time}; + /// # use bitcoin_primitives::absolute; /// // Can be implemented if block chain data is available. - /// fn get_height() -> Height { todo!("return the current block height") } - /// fn get_time() -> Time { todo!("return the current block time") } + /// fn get_height() -> absolute::Height { todo!("return the current block height") } + /// fn get_time() -> absolute::Time { todo!("return the current block time") } /// - /// let n = LockTime::from_consensus(741521); // `n OP_CHEKCLOCKTIMEVERIFY`. + /// let n = absolute::LockTime::from_consensus(741521); // `n OP_CHEKCLOCKTIMEVERIFY`. /// if n.is_satisfied_by(get_height(), get_time()) { /// // Can create and mine a transaction that satisfies the OP_CLTV timelock constraint. /// } @@ -257,9 +257,9 @@ impl LockTime { /// # Examples /// /// ```rust - /// # use bitcoin_primitives::absolute::LockTime; - /// let lock_time = LockTime::from_consensus(741521); - /// let check = LockTime::from_consensus(741521 + 1); + /// # use bitcoin_primitives::absolute; + /// let lock_time = absolute::LockTime::from_consensus(741521); + /// let check = absolute::LockTime::from_consensus(741521 + 1); /// assert!(lock_time.is_implied_by(check)); /// ``` #[inline] @@ -285,9 +285,9 @@ impl LockTime { /// # Examples /// /// ```rust - /// # use bitcoin_primitives::absolute::{LockTime, LockTime::*}; - /// # let n = LockTime::from_consensus(741521); // n OP_CHECKLOCKTIMEVERIFY - /// # let lock_time = LockTime::from_consensus(741521 + 1); // nLockTime + /// # use bitcoin_primitives::absolute::{self, LockTime::*}; + /// # let n = absolute::LockTime::from_consensus(741521); // n OP_CHECKLOCKTIMEVERIFY + /// # let lock_time = absolute::LockTime::from_consensus(741521 + 1); // nLockTime /// /// let _is_satisfied = match (n, lock_time) { /// (Blocks(n), Blocks(lock_time)) => n <= lock_time, diff --git a/primitives/src/locktime/relative.rs b/primitives/src/locktime/relative.rs index 85aeeaeaa..0874225b2 100644 --- a/primitives/src/locktime/relative.rs +++ b/primitives/src/locktime/relative.rs @@ -36,16 +36,16 @@ pub use units::locktime::relative::{Height, Time, TimeOverflowError}; /// # Examples /// /// ``` -/// use bitcoin_primitives::relative::{LockTime, Height, Time}; -/// let lock_by_height = LockTime::from_height(144); // 144 blocks, approx 24h. +/// use bitcoin_primitives::relative; +/// let lock_by_height = relative::LockTime::from_height(144); // 144 blocks, approx 24h. /// assert!(lock_by_height.is_block_height()); /// -/// let lock_by_time = LockTime::from_512_second_intervals(168); // 168 time intervals, approx 24h. +/// let lock_by_time = relative::LockTime::from_512_second_intervals(168); // 168 time intervals, approx 24h. /// assert!(lock_by_time.is_block_time()); /// /// // Check if a lock time is satisfied by a given height or time. -/// let height = Height::from(150); -/// let time = Time::from_512_second_intervals(200); +/// let height = relative::Height::from(150); +/// let time = relative::Time::from_512_second_intervals(200); /// assert!(lock_by_height.is_satisfied_by(height, time)); /// assert!(lock_by_time.is_satisfied_by(height, time)); /// ``` @@ -75,17 +75,17 @@ impl LockTime { /// # Examples /// /// ```rust - /// # use bitcoin_primitives::relative::LockTime; + /// # use bitcoin_primitives::relative; /// /// // Values with bit 22 set to 0 will be interpreted as height-based lock times. /// let height: u32 = 144; // 144 blocks, approx 24h. - /// let lock_time = LockTime::from_consensus(height)?; + /// let lock_time = relative::LockTime::from_consensus(height)?; /// assert!(lock_time.is_block_height()); /// assert_eq!(lock_time.to_consensus_u32(), height); /// /// // Values with bit 22 set to 1 will be interpreted as time-based lock times. /// let time: u32 = 168 | (1 << 22) ; // Bit 22 is 1 with time approx 24h. - /// let lock_time = LockTime::from_consensus(time)?; + /// let lock_time = relative::LockTime::from_consensus(time)?; /// assert!(lock_time.is_block_time()); /// assert_eq!(lock_time.to_consensus_u32(), time); /// @@ -118,11 +118,11 @@ impl LockTime { /// # Examples /// /// ```rust - /// # use bitcoin_primitives::{Sequence, relative::LockTime}; + /// # use bitcoin_primitives::{Sequence, relative}; /// /// // Interpret a sequence number from a Bitcoin transaction input as a relative lock time /// let sequence_number = Sequence::from_consensus(144); // 144 blocks, approx 24h. - /// let lock_time = LockTime::from_sequence(sequence_number)?; + /// let lock_time = relative::LockTime::from_sequence(sequence_number)?; /// assert!(lock_time.is_block_height()); /// /// # Ok::<_, bitcoin_primitives::relative::DisabledLockTimeError>(()) @@ -200,12 +200,12 @@ impl LockTime { /// /// ```rust /// # use bitcoin_primitives::Sequence; - /// # use bitcoin_primitives::locktime::relative::{Height, Time}; + /// # use bitcoin_primitives::relative; /// /// # let required_height = 100; // 100 blocks. /// # let intervals = 70; // Approx 10 hours. - /// # let current_height = || Height::from(required_height + 10); - /// # let current_time = || Time::from_512_second_intervals(intervals + 10); + /// # let current_height = || relative::Height::from(required_height + 10); + /// # let current_time = || relative::Time::from_512_second_intervals(intervals + 10); /// # let lock = Sequence::from_height(required_height).to_relative_lock_time().expect("valid height"); /// /// // Users that have chain data can get the current height and time to check against a lock. @@ -269,10 +269,10 @@ impl LockTime { /// # Examples /// /// ``` - /// # use bitcoin_primitives::{Sequence, relative::LockTime}; + /// # use bitcoin_primitives::{Sequence, relative}; /// /// let sequence = Sequence::from_consensus(1 << 22 | 168); // Bit 22 is 1 with time approx 24h. - /// let lock_time = LockTime::from_sequence(sequence)?; + /// let lock_time = relative::LockTime::from_sequence(sequence)?; /// let input_sequence = Sequence::from_consensus(1 << 22 | 336); // Approx 48h. /// assert!(lock_time.is_block_time()); /// @@ -299,11 +299,11 @@ impl LockTime { /// /// ```rust /// # use bitcoin_primitives::Sequence; - /// # use bitcoin_primitives::locktime::relative::Height; + /// # use bitcoin_primitives::relative; /// /// let required_height: u16 = 100; /// let lock = Sequence::from_height(required_height).to_relative_lock_time().expect("valid height"); - /// assert!(lock.is_satisfied_by_height(Height::from(required_height + 1)).expect("a height")); + /// assert!(lock.is_satisfied_by_height(relative::Height::from(required_height + 1)).expect("a height")); /// ``` #[inline] pub fn is_satisfied_by_height(&self, height: Height) -> Result { @@ -325,11 +325,11 @@ impl LockTime { /// /// ```rust /// # use bitcoin_primitives::Sequence; - /// # use bitcoin_primitives::locktime::relative::Time; + /// # use bitcoin_primitives::relative; /// /// let intervals: u16 = 70; // approx 10 hours; /// let lock = Sequence::from_512_second_intervals(intervals).to_relative_lock_time().expect("valid time"); - /// assert!(lock.is_satisfied_by_time(Time::from_512_second_intervals(intervals + 10)).expect("a time")); + /// assert!(lock.is_satisfied_by_time(relative::Time::from_512_second_intervals(intervals + 10)).expect("a time")); /// ``` #[inline] pub fn is_satisfied_by_time(&self, time: Time) -> Result {