Struct PeekMut

pub struct PeekMut<'a, T, A = Global>
where
    T: 'a + Ord,
    A: Allocator,
{ /* private fields */ }

Structure wrapping a mutable reference to the greatest item on a BinaryHeap.

This struct is created by the peek_mut method on BinaryHeap. See its documentation for more.

Implementations

impl<'a, T, A> PeekMut<'a, T, A>

where T: Ord, A: Allocator,

pub fn refresh(&mut self) -> bool

🔬This is a nightly-only experimental API. (binary_heap_peek_mut_refresh #138355)

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.

#![feature(binary_heap_peek_mut_refresh)]
use std::collections::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:

#![feature(binary_heap_peek_mut_refresh)]
use std::collections::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);

pub fn pop(this: PeekMut<'a, T, A>) -> T

Removes the peeked value from the heap and returns it.

Trait Implementations

impl<T, A> Debug for PeekMut<'_, T, A>

where T: Ord + Debug, A: Allocator,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T, A> Deref for PeekMut<'_, T, A>

where T: Ord, A: Allocator,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T, A> DerefMut for PeekMut<'_, T, A>

where T: Ord, A: Allocator,

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T, A> Drop for PeekMut<'_, T, A>

where T: Ord, A: Allocator,

fn drop(&mut self)

Executes the destructor for this type.