Skip to content

Commit

Permalink
Merge rust-bitcoin#3528: hashes: Make more effort with the macros docs
Browse files Browse the repository at this point in the history
abcac54 hashes: Move public macros (Tobin C. Harding)
2868985 Replace TBD with next hashes release version (Tobin C. Harding)
baab5e5 hashes: Move private macro (Tobin C. Harding)
e4486d0 hashes: Hide macros from docs (Tobin C. Harding)
25c4c78 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 abcac54; successfully ran local tests

Tree-SHA512: e2b4b4fe98e38f32902f7985f995c4bbc302b19b67010ddae38c22cac8151dd19370f3bd236836075744e7e5d9c6900e25416c221cddefa2452e4af81eb49dc2
  • Loading branch information
apoelstra committed Oct 29, 2024
2 parents c40826e + abcac54 commit 77a8f07
Show file tree
Hide file tree
Showing 10 changed files with 150 additions and 140 deletions.
2 changes: 1 addition & 1 deletion hashes/src/hmac.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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() }
Expand Down
33 changes: 32 additions & 1 deletion hashes/src/internal_macros.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down Expand Up @@ -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 changes: 2 additions & 2 deletions hashes/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down
197 changes: 104 additions & 93 deletions hashes/src/macros.rs
Original file line number Diff line number Diff line change
@@ -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),*> {
#[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)
}
}
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<$($gen: $gent),*> $crate::_export::_core::fmt::Debug for $ty<$($gen),*> {
impl $crate::sha256t::Tag for $tag {
#[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;
fn engine() -> $crate::sha256::HashEngine {
const MIDSTATE: $crate::sha256::Midstate = $crate::sha256t_tag_constructor!($constructor, $($tag_value)+);
$crate::sha256::HashEngine::from_midstate(MIDSTATE)
}
self.bytes_hashed += inp.len() as u64;
}
)
);
}
}

/// Creates a new newtype around a [`Hash`] type.
///
Expand Down Expand Up @@ -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)?))
}
Expand Down Expand Up @@ -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)
}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion hashes/src/ripemd160.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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")]
Expand Down
2 changes: 1 addition & 1 deletion hashes/src/sha1.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
4 changes: 2 additions & 2 deletions hashes/src/sha256.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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.
Expand Down
Loading

0 comments on commit 77a8f07

Please sign in to comment.