milksad
/
rust-bitcoin-unsafe-fast
14
0
Fork 0
Code Issues Pull Requests Activity

Merge rust-bitcoin/rust-bitcoin#2650: Improve docs in pow module 

1bb32febbd Use manual docs attributes (Tobin C. Harding)
19f70959e1 Document private from_hex_internal function (Tobin C. Harding)
81a704302c Improve rustdocs on U256 type (Tobin C. Harding)

Pull request description:

  Follow up to #2514, improve docs in the `pow` module. Done as separate patches because there are 3 distinct improvements. The first two are trivial the last can be verified by running:

      `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly rustdoc --all-features -- -D rustdoc::broken-intra-doc-links`

ACKs for top commit:
  apoelstra:
    ACK 1bb32febbd
  sanket1729:
    ACK 1bb32febbd

Tree-SHA512: 13b9db4b184328fdea1f212b9d049c76b0b824bae822cd9f6cf9460a38f3ca3d2f7270d4c4ee2b9301a5a4049a30d82a706b8b5c8415573fa6724d5105093d97
This commit is contained in:
Andrew Poelstra 2024-04-03 02:41:34 +00:00
parent 6ec93ce685 1bb32febbd
commit 924104daec
No known key found for this signature in database
GPG Key ID: C588D63CE41B97C1
1 changed files with 26 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
bitcoin/src/pow.rs
View File

@ -24,29 +24,41 @@ use crate::error::{ContainsPrefixError, MissingPrefixError, ParseIntError, Prefi
macro_rules! do_impl {
($ty:ident) => {
impl $ty {
/// Creates `Self` from a prefixed hex string.
#[doc = "Creates `"]
#[doc = stringify!($ty)]
#[doc = "` from a prefixed hex string."]
pub fn from_hex(s: &str) -> Result<Self, PrefixedHexError> {
Ok($ty(U256::from_hex(s)?))
}
/// Creates `Self` from an unprefixed hex string.
#[doc = "Creates `"]
#[doc = stringify!($ty)]
#[doc = "` from an unprefixed hex string."]
pub fn from_unprefixed_hex(s: &str) -> Result<Self, UnprefixedHexError> {
Ok($ty(U256::from_unprefixed_hex(s)?))
}
/// Creates `Self` from a big-endian byte array.
#[doc = "Creates `"]
#[doc = stringify!($ty)]
#[doc = "` from a big-endian byte array."]
#[inline]
pub fn from_be_bytes(bytes: [u8; 32]) -> $ty { $ty(U256::from_be_bytes(bytes)) }
/// Creates `Self` from a little-endian byte array.
#[doc = "Creates `"]
#[doc = stringify!($ty)]
#[doc = "` from a little-endian byte array."]
#[inline]
pub fn from_le_bytes(bytes: [u8; 32]) -> $ty { $ty(U256::from_le_bytes(bytes)) }
/// Converts `self` to a big-endian byte array.
#[doc = "Converts `"]
#[doc = stringify!($ty)]
#[doc = "` to a big-endian byte array."]
#[inline]
pub fn to_be_bytes(self) -> [u8; 32] { self.0.to_be_bytes() }
/// Converts `self` to a little-endian byte array.
#[doc = "Converts `"]
#[doc = stringify!($ty)]
#[doc = "` to a little-endian byte array."]
#[inline]
pub fn to_le_bytes(self) -> [u8; 32] { self.0.to_le_bytes() }
}
@ -400,7 +412,7 @@ impl U256 {
const ONE: U256 = U256(0, 1);
/// Creates a `U256` from an prefixed hex string.
/// Creates a `U256` from a prefixed hex string.
fn from_hex(s: &str) -> Result<Self, PrefixedHexError> {
let stripped = if let Some(stripped) = s.strip_prefix("0x") {
stripped
@ -412,7 +424,7 @@ impl U256 {
Ok(U256::from_hex_internal(stripped)?)
}
/// Creates a `CompactTarget` from an unprefixed hex string.
/// Creates a `U256` from an unprefixed hex string.
fn from_unprefixed_hex(s: &str) -> Result<Self, UnprefixedHexError> {
if s.starts_with("0x") || s.starts_with("0X") {
return Err(ContainsPrefixError::new(s).into());
@ -420,6 +432,7 @@ impl U256 {
Ok(U256::from_hex_internal(s)?)
}
// Caller to ensure `s` does not contain a prefix.
fn from_hex_internal(s: &str) -> Result<Self, ParseIntError> {
let (high, low) = if s.len() < 32 {
let low = parse::hex_u128(s)?;
@ -437,7 +450,7 @@ impl U256 {
Ok(U256(high, low))
}
/// Creates [`U256`] from a big-endian array of `u8`s.
/// Creates `U256` from a big-endian array of `u8`s.
#[cfg_attr(all(test, mutate), mutate)]
fn from_be_bytes(a: [u8; 32]) -> U256 {
let (high, low) = split_in_half(a);
@ -446,7 +459,7 @@ impl U256 {
U256(big, little)
}
/// Creates a [`U256`] from a little-endian array of `u8`s.
/// Creates a `U256` from a little-endian array of `u8`s.
#[cfg_attr(all(test, mutate), mutate)]
fn from_le_bytes(a: [u8; 32]) -> U256 {
let (high, low) = split_in_half(a);
@ -455,7 +468,7 @@ impl U256 {
U256(big, little)
}
/// Converts `Self` to a big-endian array of `u8`s.
/// Converts `U256` to a big-endian array of `u8`s.
#[cfg_attr(all(test, mutate), mutate)]
fn to_be_bytes(self) -> [u8; 32] {
let mut out = [0; 32];
@ -464,7 +477,7 @@ impl U256 {
out
}
/// Converts `Self` to a little-endian array of `u8`s.
/// Converts `U256` to a little-endian array of `u8`s.
#[cfg_attr(all(test, mutate), mutate)]
fn to_le_bytes(self) -> [u8; 32] {
let mut out = [0; 32];
@ -515,7 +528,7 @@ impl U256 {
/// Returns the low 128 bits.
fn low_u128(&self) -> u128 { self.1 }
/// Returns `self` as a `u128` saturating to `u128::MAX` if `self` is too big.
/// Returns this `U256` as a `u128` saturating to `u128::MAX` if `self` is too big.
// Matagen gives false positive because >= and > both return u128::MAX
fn saturating_to_u128(&self) -> u128 {
if *self > U256::from(u128::MAX) {