fn idx_to_containing_height(len: NonZeroLength, idx: usize) -> Option<(Height, usize)> {
    let len = usize::from(len);
    if idx < len {
        // How does this work?
        //
        // The peaks tree is comprised of one or more perfect merkle trees. Thus each true bit i in
        // len represents a tree with 2^i items. Trees are merged together as new items are added
        // to the MMR, so we want to "skip past" all the trees prior to idx.
        //
        // Each true bit i in idx represents a tree with 2^i items *prior* to idx.
        //
        // That means that XOR *cancels out* the trees that exist in both len, and idx.
        //
        // For example, idx = 0 has no bits set, so there are no *prior* trees. 0 ^ len = len,
        // because no prior trees were cancelled out.
        let diff = len ^ idx;

        // With the common trees removed, leading_zeros() gives us the biggest remaining tree,
        // which will be the tree containing the idx that we want.
        //
        // For example, if the biggest tree is of height 2^i, indexes falling into that tree range
        // from 0 to 2^i - 1:
        //
        // len = 4 = 0b100
        // idx = 0 = 0b000
        // idx = 1 = 0b001
        // idx = 2 = 0b010
        // idx = 3 = 0b011
        // idx^len = 0b1xx
        //
        // Now suppose we have more than one tree:
        //
        // len = 15 = 0b1111 <- four trees, 2^3 + 2^2 + 2^1 + 2^0
        //
        // An item at idx = 14 is in the very last tree, 2^0, and is past the 2^3, 2^2, and 2^1
        // trees. XOR cancels out those trees, leaving just the last bit set, which corresponds to
        // the 2^0 tree:
        //
        // idx = 14 = 0b1110
        // idx^len  = 0b0001

        // Since idx < len, there must be at least one tree present in len that is not present in
        // idx:
        debug_assert!(diff > 0);

        // Thus this assertion holds, because with at least one bit set, there can't be as many
        // leading zeros as bits:
        debug_assert!(usize::MAX.count_ones() > diff.leading_zeros());

        // ...which in turn means the - 1 will never underflow:
        let height = usize::MAX.count_ones() - diff.leading_zeros() - 1;

        // ...and this will never truncate:
        let height = height as u8;

        // SAFETY: We've proven that height must be in the valid range for a Height
        assert_eq!(Height::MAX as u32, usize::MAX.count_ones() - 1);
        debug_assert!(Height::try_from(height).is_ok());
        let height = unsafe { Height::new_unchecked(height) };

        // Now that we know the height of the tree we want, we need to calculate the index *within*
        // that tree.
        //
        // Again, remember that each bit set in idx corresponds to a tree *prior* to the idx we
        // want. Equally, a 2^i tree has i bits of relevant idx. So it suffices to simply mask off
        // the irrelevant bits:
        let idx_mask = !(usize::MAX << height.get());
        let idx_in_peak = idx & idx_mask;

        Some((height, idx_in_peak))
    } else {
        None
    }
}
/// Determines the height of the peak containing a given index, as well as the index within that
/// peak tree.
///
/// Returns `None` if the index is out of bounds.
///
/// This is a separate function so it can be easily tested at the extremes.
Determines the height of the peak containing a given index, as well as the index within that
peak tree.

Returns `None` if the index is out of bounds.

This is a separate function so it can be easily tested at the extremes.
Determines the height of the peak containing a given index as well as the index within that peak tree . Returns ` None ` if the index is out of bounds . This is a separate function so it can be easily tested at the extremes .
fn idx_to_containing_height(len: NonZeroLength, idx: usize) -> Option<(Height, usize)> {
    let len = usize::from(len);
    if idx < len {
        // How does this work?
        //
        // The peaks tree is comprised of one or more perfect merkle trees. Thus each true bit i in
        // len represents a tree with 2^i items. Trees are merged together as new items are added
        // to the MMR, so we want to "skip past" all the trees prior to idx.
        //
        // Each true bit i in idx represents a tree with 2^i items *prior* to idx.
        //
        // That means that XOR *cancels out* the trees that exist in both len, and idx.
        //
        // For example, idx = 0 has no bits set, so there are no *prior* trees. 0 ^ len = len,
        // because no prior trees were cancelled out.
        let diff = len ^ idx;
        // With the common trees removed, leading_zeros() gives us the biggest remaining tree,
        // which will be the tree containing the idx that we want.
        //
        // For example, if the biggest tree is of height 2^i, indexes falling into that tree range
        // from 0 to 2^i - 1:
        //
        // len = 4 = 0b100
        // idx = 0 = 0b000
        // idx = 1 = 0b001
        // idx = 2 = 0b010
        // idx = 3 = 0b011
        // idx^len = 0b1xx
        //
        // Now suppose we have more than one tree:
        //
        // len = 15 = 0b1111 <- four trees, 2^3 + 2^2 + 2^1 + 2^0
        //
        // An item at idx = 14 is in the very last tree, 2^0, and is past the 2^3, 2^2, and 2^1
        // trees. XOR cancels out those trees, leaving just the last bit set, which corresponds to
        // the 2^0 tree:
        //
        // idx = 14 = 0b1110
        // idx^len  = 0b0001
        // Since idx < len, there must be at least one tree present in len that is not present in
        // idx:
        debug_assert!(diff > 0);
        // Thus this assertion holds, because with at least one bit set, there can't be as many
        // leading zeros as bits:
        debug_assert!(usize::MAX.count_ones() > diff.leading_zeros());
        // ...which in turn means the - 1 will never underflow:
        let height = usize::MAX.count_ones() - diff.leading_zeros() - 1;
        // ...and this will never truncate:
        let height = height as u8;
        // SAFETY: We've proven that height must be in the valid range for a Height
        assert_eq!(Height::MAX as u32, usize::MAX.count_ones() - 1);
        debug_assert!(Height::try_from(height).is_ok());
        let height = unsafe { Height::new_unchecked(height) };
        // Now that we know the height of the tree we want, we need to calculate the index *within*
        // that tree.
        //
        // Again, remember that each bit set in idx corresponds to a tree *prior* to the idx we
        // want. Equally, a 2^i tree has i bits of relevant idx. So it suffices to simply mask off
        // the irrelevant bits:
        let idx_mask = !(usize::MAX << height.get());
        let idx_in_peak = idx & idx_mask;
        Some((height, idx_in_peak))
    } else {
        None
    }
}
fn idx_to_containing_height ( len : NonZeroLength , idx : usize ) -> Option < ( Height , usize ) > { let len = usize :: from ( len ) ; if idx < len { // How does this work? // // The peaks tree is comprised of one or more perfect merkle trees. Thus each true bit i in // len represents a tree with 2^i items. Trees are merged together as new items are added // to the MMR, so we want to "skip past" all the trees prior to idx. // // Each true bit i in idx represents a tree with 2^i items *prior* to idx. // // That means that XOR *cancels out* the trees that exist in both len, and idx. // // For example, idx = 0 has no bits set, so there are no *prior* trees. 0 ^ len = len, // because no prior trees were cancelled out. let diff = len ^ idx ; // With the common trees removed, leading_zeros() gives us the biggest remaining tree, // which will be the tree containing the idx that we want. // // For example, if the biggest tree is of height 2^i, indexes falling into that tree range // from 0 to 2^i - 1: // // len = 4 = 0b100 // idx = 0 = 0b000 // idx = 1 = 0b001 // idx = 2 = 0b010 // idx = 3 = 0b011 // idx^len = 0b1xx // // Now suppose we have more than one tree: // // len = 15 = 0b1111 <- four trees, 2^3 + 2^2 + 2^1 + 2^0 // // An item at idx = 14 is in the very last tree, 2^0, and is past the 2^3, 2^2, and 2^1 // trees. XOR cancels out those trees, leaving just the last bit set, which corresponds to // the 2^0 tree: // // idx = 14 = 0b1110 // idx^len  = 0b0001 // Since idx < len, there must be at least one tree present in len that is not present in // idx: debug_assert ! ( diff 0 ) ; // Thus this assertion holds, because with at least one bit set, there can't be as many // leading zeros as bits: debug_assert ! ( usize MAX count_ones ( ) diff leading_zeros ( ) ) ; // ...which in turn means the - 1 will never underflow: let height = usize :: MAX . count_ones ( ) - diff . leading_zeros ( ) - 1 ; // ...and this will never truncate: let height = height as u8 ; // SAFETY: We've proven that height must be in the valid range for a Height assert_eq ! ( Height MAX as u32 usize MAX count_ones ( ) 1 ) ; debug_assert ! ( Height try_from ( height ) is_ok ( ) ) ; let height = unsafe { Height :: new_unchecked ( height ) } ; // Now that we know the height of the tree we want, we need to calculate the index *within* // that tree. // // Again, remember that each bit set in idx corresponds to a tree *prior* to the idx we // want. Equally, a 2^i tree has i bits of relevant idx. So it suffices to simply mask off // the irrelevant bits: let idx_mask = ! ( usize :: MAX << height . get ( ) ) ; let idx_in_peak = idx & idx_mask ; Some ( ( height , idx_in_peak ) ) } else { None } }
Determines the height of the peak containing a given index, as well as the index within that
peak tree.
Determines the height of the peak containing a given index as well as the index within that peak tree .
len
NonZeroLength
idx
usize