# Struct arduboy_rust::heapless::BinaryHeap

source ·

    pub struct BinaryHeap<T, K, const N: usize> { /* private fields */ }

Expand description

A priority queue implemented with a binary heap.

This can be either a min-heap or a max-heap.

It is a logic error for an item to be modified in such a way that the item’s ordering relative to any other item, as determined by the `Ord` trait, changes while it is in the heap. This is normally only possible through `Cell`, `RefCell`, global state, I/O, or unsafe code.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();

    // We can use peek to look at the next item in the heap. In this case,
    // there's no items in there yet so we get None.
    assert_eq!(heap.peek(), None);

    // Let's add some scores...
    heap.push(1).unwrap();
    heap.push(5).unwrap();
    heap.push(2).unwrap();

    // Now peek shows the most important item in the heap.
    assert_eq!(heap.peek(), Some(&5));

    // We can check the length of a heap.
    assert_eq!(heap.len(), 3);

    // We can iterate over the items in the heap, although they are returned in
    // a random order.
    for x in &heap {
        println!("{}", x);
    }

    // If we instead pop these scores, they should come back in order.
    assert_eq!(heap.pop(), Some(5));
    assert_eq!(heap.pop(), Some(2));
    assert_eq!(heap.pop(), Some(1));
    assert_eq!(heap.pop(), None);

    // We can clear the heap of any remaining items.
    heap.clear();

    // The heap should now be empty.
    assert!(heap.is_empty())

## Implementations§

source §

### impl<T, K, const N: usize> BinaryHeap<T, K, N>

source

#### pub const fn new() -> BinaryHeap<T, K, N>

Creates an empty BinaryHeap as a $K-heap.

    use heapless::binary_heap::{BinaryHeap, Max};

    // allocate the binary heap on the stack
    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    heap.push(4).unwrap();

    // allocate the binary heap in a static variable
    static mut HEAP: BinaryHeap<i32, Max, 8> = BinaryHeap::new();

source §

### impl<T, K, const N: usize> BinaryHeap<T, K, N>where T: Ord, K: Kind,

source

#### pub fn capacity(&self) -> usize

Returns the capacity of the binary heap.

source

#### pub fn clear(&mut self)

Drops all items from the binary heap.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    heap.push(1).unwrap();
    heap.push(3).unwrap();

    assert!(!heap.is_empty());

    heap.clear();

    assert!(heap.is_empty());

source

#### pub fn len(&self) -> usize

Returns the length of the binary heap.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    heap.push(1).unwrap();
    heap.push(3).unwrap();

    assert_eq!(heap.len(), 2);

source

#### pub fn is_empty(&self) -> bool

Checks if the binary heap is empty.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();

    assert!(heap.is_empty());

    heap.push(3).unwrap();
    heap.push(5).unwrap();
    heap.push(1).unwrap();

    assert!(!heap.is_empty());

source

#### pub fn iter(&self) -> Iter<'_, T>

Returns an iterator visiting all values in the underlying vector, in arbitrary order.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    heap.push(1).unwrap();
    heap.push(2).unwrap();
    heap.push(3).unwrap();
    heap.push(4).unwrap();

    // Print 1, 2, 3, 4 in arbitrary order
    for x in heap.iter() {
        println!("{}", x);

    }

source

#### pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns a mutable iterator visiting all values in the underlying vector, in arbitrary order.

WARNING Mutating the items in the binary heap can leave the heap in an inconsistent state.

source

#### pub fn peek(&self) -> Option<&T>

Returns the top (greatest if max-heap, smallest if min-heap) item in the binary heap, or None if it is empty.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    assert_eq!(heap.peek(), None);

    heap.push(1).unwrap();
    heap.push(5).unwrap();
    heap.push(2).unwrap();
    assert_eq!(heap.peek(), Some(&5));

source

#### pub fn peek_mut(&mut self) -> Option<PeekMut<'_, T, K, N>>

Returns a mutable reference to the greatest item in the binary heap, or `None` if it is empty.

Note: If the `PeekMut` value is leaked, the heap may be in an inconsistent state.

##### Examples

Basic usage:

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    assert!(heap.peek_mut().is_none());

    heap.push(1);
    heap.push(5);
    heap.push(2);
    {
        let mut val = heap.peek_mut().unwrap();
        *val = 0;
    }

    assert_eq!(heap.peek(), Some(&2));

source

#### pub fn pop(&mut self) -> Option<T>

Removes the top (greatest if max-heap, smallest if min-heap) item from the binary heap and returns it, or None if it is empty.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    heap.push(1).unwrap();
    heap.push(3).unwrap();

    assert_eq!(heap.pop(), Some(3));
    assert_eq!(heap.pop(), Some(1));
    assert_eq!(heap.pop(), None);

source

#### pub unsafe fn pop_unchecked(&mut self) -> T

Removes the top (greatest if max-heap, smallest if min-heap) item from the binary heap and returns it, without checking if the binary heap is empty.

source

#### pub fn push(&mut self, item: T) -> Result<(), T>

Pushes an item onto the binary heap.

    use heapless::binary_heap::{BinaryHeap, Max};

    let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
    heap.push(3).unwrap();
    heap.push(5).unwrap();
    heap.push(1).unwrap();

    assert_eq!(heap.len(), 3);
    assert_eq!(heap.peek(), Some(&5));

source

#### pub unsafe fn push_unchecked(&mut self, item: T)

Pushes an item onto the binary heap without first checking if it’s full.

source

#### pub fn into_vec(self) -> Vec<T, N>

Returns the underlying `Vec<T,N>`. Order is arbitrary and time is O(1).

## Trait Implementations§

source §

### impl<T, K, const N: usize> Clone for BinaryHeap<T, K, N>where K: Kind, T: Ord + Clone,

source §

#### fn clone(&self) -> BinaryHeap<T, K, N>

Returns a copy of the value. Read more
1.0.0 §

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
source §

### impl<T, K, const N: usize> Debug for BinaryHeap<T, K, N>where K: Kind, T: Ord + Debug,

source §

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

Formats the value using the given formatter. Read more
source §

### impl<T, K, const N: usize> Default for BinaryHeap<T, K, N>where T: Ord, K: Kind,

source §

#### fn default() -> BinaryHeap<T, K, N>

Returns the “default value” for a type. Read more
source §

### impl<'a, T, K, const N: usize> IntoIterator for &'a BinaryHeap<T, K, N>where K: Kind, T: Ord,

§

#### type Item = &'a T

The type of the elements being iterated over.
§

#### type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?
source §

#### fn into_iter(self) -> <&'a BinaryHeap<T, K, N> as IntoIterator>::IntoIter

Creates an iterator from a value. Read more

## Auto Trait Implementations§

§

### impl<T, K, const N: usize> RefUnwindSafe for BinaryHeap<T, K, N>where K: RefUnwindSafe, T: RefUnwindSafe,

§

### impl<T, K, const N: usize> Send for BinaryHeap<T, K, N>where K: Send, T: Send,

§

### impl<T, K, const N: usize> Sync for BinaryHeap<T, K, N>where K: Sync, T: Sync,

§

### impl<T, K, const N: usize> Unpin for BinaryHeap<T, K, N>where K: Unpin, T: Unpin,

§

### impl<T, K, const N: usize> UnwindSafe for BinaryHeap<T, K, N>where K: UnwindSafe, T: UnwindSafe,

## Blanket Implementations§

§

### impl<T> Any for Twhere T: 'static + ?Sized,

§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
§

### impl<T> Borrow<T> for Twhere T: ?Sized,

§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

### impl<T> From<T> for T

§

#### fn from(t: T) -> T

Returns the argument unchanged.

§

### impl<T, U> Into<U> for Twhere U: From<T>,

§

#### fn into(self) -> U

Calls `U::from(self)`.

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

§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.