Struct PeekMut Copy item path

Sifts the current element to its new position.

Afterwards refers to the new element. Returns if the element changed.

§Examples

The condition can be used to upper bound all elements in the heap. When only few elements are affected, the heap’s sort ensures this is faster than a reconstruction from the raw element list and requires no additional allocation.

use dary_heap::BinaryHeap;

let mut heap: BinaryHeap<u32> = (0..128).collect();
let mut peek = heap.peek_mut().unwrap();

loop {
    *peek = 99;

    if !peek.refresh() {
        break;
    }
}

// Post condition, this is now an upper bound.
assert!(*peek < 100);

When the element remains the maximum after modification, the peek remains unchanged:

use dary_heap::BinaryHeap;

let mut heap: BinaryHeap<u32> = [1, 2, 3].into();
let mut peek = heap.peek_mut().unwrap();

assert_eq!(*peek, 3);
*peek = 42;

// When we refresh, the peek is updated to the new maximum.
assert!(!peek.refresh(), "42 is even larger than 3");
assert_eq!(*peek, 42);

Removes the peeked value from the heap and returns it.

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.