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

Merge rust-bitcoin/rust-bitcoin#3528: hashes: Make more effort with the macros docs 

abcac54078 hashes: Move public macros (Tobin C. Harding)
2868985a91 Replace TBD with next hashes release version (Tobin C. Harding)
baab5e580d hashes: Move private macro (Tobin C. Harding)
e4486d07f0 hashes: Hide macros from docs (Tobin C. Harding)
25c4c78e26 hashes: Put attribute under rustdoc (Tobin C. Harding)

Pull request description:

  A quick cleanup to try and make the docs better around our macros.

  Last patch might be churn, can drop it if wanted. Came about because the `macros` module shows empty in the docs currently.

ACKs for top commit:
  apoelstra:
    ACK abcac540782dd84992e47f342929efd407746c65; successfully ran local tests

Tree-SHA512: e2b4b4fe98e38f32902f7985f995c4bbc302b19b67010ddae38c22cac8151dd19370f3bd236836075744e7e5d9c6900e25416c221cddefa2452e4af81eb49dc2
This commit is contained in:
merge-script 2024-10-29 22:39:02 +00:00
parent c40826e008 abcac54078
commit 77a8f076b8
No known key found for this signature in database
GPG Key ID: C588D63CE41B97C1
10 changed files with 151 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hashes/src/hmac.rs
View File

@ -129,7 +129,7 @@ impl<T: GeneralHash> Hash for Hmac<T> {
fn from_byte_array(bytes: T::Bytes) -> Self { Hmac(T::from_byte_array(bytes)) }
#[allow(deprecated_in_future)]
#[allow(deprecated)]
fn from_slice(sl: &[u8]) -> Result<Hmac<T>, FromSliceError> { T::from_slice(sl).map(Hmac) }
fn to_byte_array(self) -> Self::Bytes { self.0.to_byte_array() }

33
hashes/src/internal_macros.rs
View File

@ -99,7 +99,7 @@ macro_rules! hash_trait_impls {
fn from_byte_array(bytes: Self::Bytes) -> Self { Self::from_byte_array(bytes) }
#[allow(deprecated_in_future)]
#[allow(deprecated)]
fn from_slice(sl: &[u8]) -> $crate::_export::_core::result::Result<Hash<$($gen),*>, $crate::FromSliceError> {
Self::from_slice(sl)
}
@ -253,3 +253,34 @@ macro_rules! impl_io_write {
}
}
pub(crate) use impl_io_write;
macro_rules! engine_input_impl(
() => (
#[cfg(not(hashes_fuzz))]
fn input(&mut self, mut inp: &[u8]) {
while !inp.is_empty() {
let buf_idx = $crate::incomplete_block_len(self);
let rem_len = <Self as crate::HashEngine>::BLOCK_SIZE - buf_idx;
let write_len = cmp::min(rem_len, inp.len());
self.buffer[buf_idx..buf_idx + write_len]
.copy_from_slice(&inp[..write_len]);
self.bytes_hashed += write_len as u64;
if $crate::incomplete_block_len(self) == 0 {
self.process_block();
}
inp = &inp[write_len..];
}
}
#[cfg(hashes_fuzz)]
fn input(&mut self, inp: &[u8]) {
for c in inp {
self.buffer[0] ^= *c;
}
self.bytes_hashed += inp.len() as u64;
}
)
);
pub(crate) use engine_input_impl;

4
hashes/src/lib.rs
View File

@ -112,7 +112,7 @@ pub mod sha512;
pub mod sha512_256;
pub mod siphash24;
#[deprecated(since = "TBD", note = "use crate::macros instead")]
#[deprecated(since = "0.15.0", note = "use crate::macros instead")]
pub mod serde_macros {
//! Macros for serde trait implementations, and supporting code.
@ -284,7 +284,7 @@ pub trait Hash:
fn from_byte_array(bytes: Self::Bytes) -> Self;
/// Copies a byte slice into a hash object.
#[deprecated(since = "TBD", note = "use `from_byte_array` instead")]
#[deprecated(since = "0.15.0", note = "use `from_byte_array` instead")]
fn from_slice(sl: &[u8]) -> Result<Self, FromSliceError>;
/// Returns the underlying byte array.

199
hashes/src/macros.rs
View File

@ -1,102 +1,44 @@
// SPDX-License-Identifier: CC0-1.0
//! Public macros.
//!
//! - [`sha256t_tag`](crate::sha256t_tag)
//! - [`hash_newtype`](crate::hash_newtype)
/// Macro used to define a tag.
///
/// Defines new struct and implements `Tag` for it.
///
/// The syntax is:
///
/// ```
/// # use bitcoin_hashes::sha256t_tag;
/// sha256t_tag! {
/// /// Optional documentation details here.
/// /// Summary is always generated.
/// pub struct FooTag = hash_str("foo");
/// }
/// ```
///
/// The `hash_str` marker says the midstate should be generated by hashing the supplied string in a
/// way described in BIP-341. Alternatively, you can supply `hash_bytes` to hash raw bytes. If you
/// have the midstate already pre-computed and prefer **compiler** performance to readability you
/// may use `raw(MIDSTATE_BYTES, HASHED_BYTES_LENGTH)` instead, note that HASHED_BYTES_LENGTH must
/// be a multiple of 64.
#[macro_export]
/// Adds hexadecimal formatting implementation of a trait `$imp` to a given type `$ty`.
macro_rules! hex_fmt_impl(
($reverse:expr, $len:expr, $ty:ident) => (
$crate::hex_fmt_impl!($reverse, $len, $ty, );
);
($reverse:expr, $len:expr, $ty:ident, $($gen:ident: $gent:ident),*) => (
impl<$($gen: $gent),*> $crate::_export::_core::fmt::LowerHex for $ty<$($gen),*> {
macro_rules! sha256t_tag {
($(#[$($tag_attr:tt)*])* $tag_vis:vis struct $tag:ident = $constructor:tt($($tag_value:tt)+);) => {
$crate::sha256t_tag_struct!($tag_vis, $tag, stringify!($hash_name), $(#[$($tag_attr)*])*);
impl $crate::sha256t::Tag for $tag {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
if $reverse {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self).iter().rev(), $crate::hex::Case::Lower)
} else {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self), $crate::hex::Case::Lower)
}
fn engine() -> $crate::sha256::HashEngine {
const MIDSTATE: $crate::sha256::Midstate = $crate::sha256t_tag_constructor!($constructor, $($tag_value)+);
$crate::sha256::HashEngine::from_midstate(MIDSTATE)
}
}
impl<$($gen: $gent),*> $crate::_export::_core::fmt::UpperHex for $ty<$($gen),*> {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
if $reverse {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self).iter().rev(), $crate::hex::Case::Upper)
} else {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self), $crate::hex::Case::Upper)
}
}
}
impl<$($gen: $gent),*> $crate::_export::_core::fmt::Display for $ty<$($gen),*> {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
$crate::_export::_core::fmt::LowerHex::fmt(&self, f)
}
}
impl<$($gen: $gent),*> $crate::_export::_core::fmt::Debug for $ty<$($gen),*> {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
write!(f, "{}", self)
}
}
);
);
/// Adds slicing traits implementations to a given type `$ty`
#[macro_export]
macro_rules! borrow_slice_impl(
($ty:ident) => (
$crate::borrow_slice_impl!($ty, );
);
($ty:ident, $($gen:ident: $gent:ident),*) => (
impl<$($gen: $gent),*> $crate::_export::_core::borrow::Borrow<[u8]> for $ty<$($gen),*> {
fn borrow(&self) -> &[u8] {
self.as_byte_array()
}
}
impl<$($gen: $gent),*> $crate::_export::_core::convert::AsRef<[u8]> for $ty<$($gen),*> {
fn as_ref(&self) -> &[u8] {
self.as_byte_array()
}
}
)
);
macro_rules! engine_input_impl(
() => (
#[cfg(not(hashes_fuzz))]
fn input(&mut self, mut inp: &[u8]) {
while !inp.is_empty() {
let buf_idx = $crate::incomplete_block_len(self);
let rem_len = <Self as crate::HashEngine>::BLOCK_SIZE - buf_idx;
let write_len = cmp::min(rem_len, inp.len());
self.buffer[buf_idx..buf_idx + write_len]
.copy_from_slice(&inp[..write_len]);
self.bytes_hashed += write_len as u64;
if $crate::incomplete_block_len(self) == 0 {
self.process_block();
}
inp = &inp[write_len..];
}
}
#[cfg(hashes_fuzz)]
fn input(&mut self, inp: &[u8]) {
for c in inp {
self.buffer[0] ^= *c;
}
self.bytes_hashed += inp.len() as u64;
}
)
);
}
}
/// Creates a new newtype around a [`Hash`] type.
///
@ -203,8 +145,8 @@ macro_rules! hash_newtype {
}
/// Copies a byte slice into a hash object.
#[deprecated(since = "TBD", note = "use `from_byte_array` instead")]
#[allow(deprecated_in_future)]
#[deprecated(since = "0.15.0", note = "use `from_byte_array` instead")]
#[allow(deprecated)]
pub fn from_slice(sl: &[u8]) -> $crate::_export::_core::result::Result<$newtype, $crate::FromSliceError> {
Ok($newtype(<$hash as $crate::Hash>::from_slice(sl)?))
}
@ -241,7 +183,7 @@ macro_rules! hash_newtype {
fn from_byte_array(bytes: Self::Bytes) -> Self { Self::from_byte_array(bytes) }
#[inline]
#[allow(deprecated_in_future)]
#[allow(deprecated)]
fn from_slice(sl: &[u8]) -> $crate::_export::_core::result::Result<$newtype, $crate::FromSliceError> {
Self::from_slice(sl)
}
@ -273,6 +215,74 @@ macro_rules! hash_newtype {
};
}
/// Adds hexadecimal formatting implementation of a trait `$imp` to a given type `$ty`.
#[doc(hidden)]
#[macro_export]
macro_rules! hex_fmt_impl(
($reverse:expr, $len:expr, $ty:ident) => (
$crate::hex_fmt_impl!($reverse, $len, $ty, );
);
($reverse:expr, $len:expr, $ty:ident, $($gen:ident: $gent:ident),*) => (
impl<$($gen: $gent),*> $crate::_export::_core::fmt::LowerHex for $ty<$($gen),*> {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
if $reverse {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self).iter().rev(), $crate::hex::Case::Lower)
} else {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self), $crate::hex::Case::Lower)
}
}
}
impl<$($gen: $gent),*> $crate::_export::_core::fmt::UpperHex for $ty<$($gen),*> {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
if $reverse {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self).iter().rev(), $crate::hex::Case::Upper)
} else {
$crate::hex::fmt_hex_exact!(f, $len, <Self as $crate::Hash>::as_byte_array(&self), $crate::hex::Case::Upper)
}
}
}
impl<$($gen: $gent),*> $crate::_export::_core::fmt::Display for $ty<$($gen),*> {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
$crate::_export::_core::fmt::LowerHex::fmt(&self, f)
}
}
impl<$($gen: $gent),*> $crate::_export::_core::fmt::Debug for $ty<$($gen),*> {
#[inline]
fn fmt(&self, f: &mut $crate::_export::_core::fmt::Formatter) -> $crate::_export::_core::fmt::Result {
write!(f, "{}", self)
}
}
);
);
/// Adds slicing traits implementations to a given type `$ty`
#[doc(hidden)]
#[macro_export]
macro_rules! borrow_slice_impl(
($ty:ident) => (
$crate::borrow_slice_impl!($ty, );
);
($ty:ident, $($gen:ident: $gent:ident),*) => (
impl<$($gen: $gent),*> $crate::_export::_core::borrow::Borrow<[u8]> for $ty<$($gen),*> {
fn borrow(&self) -> &[u8] {
self.as_byte_array()
}
}
impl<$($gen: $gent),*> $crate::_export::_core::convert::AsRef<[u8]> for $ty<$($gen),*> {
fn as_ref(&self) -> &[u8] {
self.as_byte_array()
}
}
)
);
// Generates the struct only (no impls)
//
// This is a separate macro to make it more readable and have a separate interface that allows for
@ -439,6 +449,7 @@ pub mod serde_details {
/// Implements `Serialize` and `Deserialize` for a type `$t` which
/// represents a newtype over a byte-slice over length `$len`.
#[doc(hidden)]
#[macro_export]
#[cfg(feature = "serde")]
macro_rules! serde_impl(

2
hashes/src/ripemd160.rs
View File

@ -85,7 +85,7 @@ impl crate::HashEngine for HashEngine {
fn n_bytes_hashed(&self) -> u64 { self.bytes_hashed }
engine_input_impl!();
crate::internal_macros::engine_input_impl!();
}
#[cfg(feature = "small-hash")]

2
hashes/src/sha1.rs
View File

@ -77,7 +77,7 @@ impl crate::HashEngine for HashEngine {
fn n_bytes_hashed(&self) -> u64 { self.bytes_hashed }
engine_input_impl!();
crate::internal_macros::engine_input_impl!();
}
impl HashEngine {

4
hashes/src/sha256.rs
View File

@ -132,7 +132,7 @@ impl crate::HashEngine for HashEngine {
fn n_bytes_hashed(&self) -> u64 { self.bytes_hashed }
engine_input_impl!();
crate::internal_macros::engine_input_impl!();
}
impl Hash {
@ -144,7 +144,7 @@ impl Hash {
/// Computes hash from `bytes` in `const` context.
///
/// Warning: this function is inefficient. It should be only used in `const` context.
#[deprecated(since = "TBD", note = "use `Self::hash_unoptimized` instead")]
#[deprecated(since = "0.15.0", note = "use `Self::hash_unoptimized` instead")]
pub const fn const_hash(bytes: &[u8]) -> Self { Hash::hash_unoptimized(bytes) }
/// Computes hash from `bytes` in `const` context.

41
hashes/src/sha256t.rs
View File

@ -43,7 +43,7 @@ where
}
/// Copies a byte slice into a hash object.
#[deprecated(since = "TBD", note = "use `from_byte_array` instead")]
#[deprecated(since = "0.15.0", note = "use `from_byte_array` instead")]
pub fn from_slice(sl: &[u8]) -> Result<Hash<T>, FromSliceError> {
if sl.len() != 32 {
Err(FromSliceError { expected: 32, got: sl.len() })
@ -141,41 +141,6 @@ where
Hash::from_byte_array(sha256::Hash::from_engine(e).to_byte_array())
}
/// Macro used to define a tag.
///
/// Defines new struct and implements `Tag` for it.
///
/// The syntax is:
///
/// ```
/// # use bitcoin_hashes::sha256t_tag;
/// sha256t_tag! {
/// /// Optional documentation details here.
/// /// Summary is always generated.
/// pub struct FooTag = hash_str("foo");
/// }
/// ```
///
/// The `hash_str` marker says the midstate should be generated by hashing the supplied string in a
/// way described in BIP-341. Alternatively, you can supply `hash_bytes` to hash raw bytes. If you
/// have the midstate already pre-computed and prefer **compiler** performance to readability you
/// may use `raw(MIDSTATE_BYTES, HASHED_BYTES_LENGTH)` instead, note that HASHED_BYTES_LENGTH must
/// be a multiple of 64.
#[macro_export]
macro_rules! sha256t_tag {
($(#[$($tag_attr:tt)*])* $tag_vis:vis struct $tag:ident = $constructor:tt($($tag_value:tt)+);) => {
$crate::sha256t_tag_struct!($tag_vis, $tag, stringify!($hash_name), $(#[$($tag_attr)*])*);
impl $crate::sha256t::Tag for $tag {
#[inline]
fn engine() -> $crate::sha256::HashEngine {
const MIDSTATE: $crate::sha256::Midstate = $crate::sha256t_tag_constructor!($constructor, $($tag_value)+);
$crate::sha256::HashEngine::from_midstate(MIDSTATE)
}
}
}
}
/// Macro used to define a newtype tagged hash.
///
/// This macro creates two types:
@ -186,6 +151,7 @@ macro_rules! sha256t_tag {
/// The syntax is:
///
/// ```
/// # #[allow(deprecated)] {
/// # use bitcoin_hashes::sha256t_hash_newtype;
/// sha256t_hash_newtype! {
/// /// Optional documentation details here.
@ -197,6 +163,7 @@ macro_rules! sha256t_tag {
/// #[hash_newtype(backward)]
/// pub struct FooHash(_);
/// }
/// # }
/// ```
///
/// The structs must be defined in this order - tag first, then hash type. `hash_str` marker
@ -211,7 +178,7 @@ macro_rules! sha256t_tag {
///
/// [`hash_newtype`]: crate::hash_newtype
#[macro_export]
#[deprecated(since = "TBD", note = "use `sha256_tag!` combined with `hash_newtype!` instead")]
#[deprecated(since = "0.15.0", note = "use `sha256_tag!` combined with `hash_newtype!` instead")]
macro_rules! sha256t_hash_newtype {
($(#[$($tag_attr:tt)*])* $tag_vis:vis struct $tag:ident = $constructor:tt($($tag_value:tt)+); $(#[$($hash_attr:tt)*])* $hash_vis:vis struct $hash_name:ident($(#[$($field_attr:tt)*])* _);) => {
$crate::sha256t_tag_struct!($tag_vis, $tag, stringify!($hash_name), $(#[$($tag_attr)*])*);

2
hashes/src/sha512.rs
View File

@ -118,7 +118,7 @@ impl crate::HashEngine for HashEngine {
fn n_bytes_hashed(&self) -> u64 { self.bytes_hashed }
engine_input_impl!();
crate::internal_macros::engine_input_impl!();
}
#[allow(non_snake_case)]

3
hashes/src/siphash24.rs
View File

@ -1,3 +1,4 @@
// SPDX-License-Identifier: CC0-1.0
//! SipHash 2-4 implementation.
@ -203,7 +204,7 @@ impl Hash {
}
/// Returns the (little endian) 64-bit integer representation of the hash value.
#[deprecated(since = "TBD", note = "use `to_u64` instead")]
#[deprecated(since = "0.15.0", note = "use `to_u64` instead")]
pub fn as_u64(&self) -> u64 { self.to_u64() }
/// Returns the (little endian) 64-bit integer representation of the hash value.