PeekMut in std::collections::binary_heap - Rust (original) (raw)

Struct PeekMut

1.12.0 · Source

pub struct PeekMut<'a, T, A = Global>

where
    T: 'a + Ord,
    A: Allocator,

{ /* private fields */ }

Expand description

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

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

Source§

Source

🔬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);

1.18.0 · Source

Removes the peeked value from the heap and returns it.