# [−] [src] Struct heapless::binary_heap::BinaryHeap

    pub struct BinaryHeap<T, N, KIND>(_)
     where
        T: Ord,
        N: ArrayLength<T>,
        KIND: Kind;

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};
    use heapless::consts::*;

    let mut heap: BinaryHeap<_, U8, Max> = 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

### `impl<T, N, K> BinaryHeap<T, N, K> where
T: Ord,
N: ArrayLength<T>,
K: Kind,` [src]

#### `pub fn new() -> Self` [src]

Creates an empty BinaryHeap as a $K-heap.

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

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

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

#### `pub fn capacity(&self) -> usize` [src]

Returns the capacity of the binary heap.

#### `pub fn clear(&mut self)` [src]

Drops all items from the binary heap.

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

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

    assert!(!heap.is_empty());

    heap.clear();

    assert!(heap.is_empty());

#### `pub fn len(&self) -> usize` [src]

Returns the length of the binary heap.

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

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

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

#### `pub fn is_empty(&self) -> bool` [src]

Checks if the binary heap is empty.

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

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

    assert!(heap.is_empty());

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

    assert!(!heap.is_empty());

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

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

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

    let mut heap: BinaryHeap<_, U8, Max> = 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);

    }

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

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.

#### `pub fn peek(&self) -> Option<&T>` [src]

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};
    use heapless::consts::*;

    let mut heap: BinaryHeap<_, U8, Max> = 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));

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

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};
    use heapless::consts::*;

    let mut heap: BinaryHeap<_, U8, Max> = 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));

#### `pub fn pop(&mut self) -> Option<T>` [src]

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};
    use heapless::consts::*;

    let mut heap: BinaryHeap<_, U8, Max> = 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);

#### `pub unsafe fn pop_unchecked(&mut self) -> T` [src]

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.

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

Pushes an item onto the binary heap.

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

    let mut heap: BinaryHeap<_, U8, Max> = 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));

#### `pub unsafe fn push_unchecked(&mut self, item: T)` [src]

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

## Trait Implementations

### `impl<T, N, K> Clone for BinaryHeap<T, N, K> where
N: ArrayLength<T>,
K: Kind,
T: Ord + Clone,` [src]

#### `fn clone(&self) -> Self` [src]

Returns a copy of the value. Read more

#### `pub fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from `source`. Read more

### `impl<T, N, K> Debug for BinaryHeap<T, N, K> where
N: ArrayLength<T>,
K: Kind,
T: Ord + Debug,` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl<T, N, K> Default for BinaryHeap<T, N, K> where
T: Ord,
N: ArrayLength<T>,
K: Kind,` [src]

#### `fn default() -> Self` [src]

Returns the "default value" for a type. Read more

### `impl<T, N, K> Drop for BinaryHeap<T, N, K> where
N: ArrayLength<T>,
K: Kind,
T: Ord,` [src]

#### `fn drop(&mut self)` [src]

Executes the destructor for this type. Read more

### `impl<'a, T, N, K> IntoIterator for &'a BinaryHeap<T, N, K> where
N: ArrayLength<T>,
K: Kind,
T: Ord,` [src]

#### `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?

#### `fn into_iter(self) -> Self::IntoIter` [src]

Creates an iterator from a value. Read more

## Auto Trait Implementations

### `impl<T, N, KIND> Send for BinaryHeap<T, N, KIND> where
KIND: Send,
T: Send,` [src]

### `impl<T, N, KIND> Sync for BinaryHeap<T, N, KIND> where
KIND: Sync,
T: Sync,` [src]

### `impl<T, N, KIND> Unpin for BinaryHeap<T, N, KIND> where
KIND: Unpin,
<N as ArrayLength<T>>::ArrayType: Unpin,` [src]

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

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

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T> Same<T> for T` [src]

#### `type Output = T`

Should always be `Self`

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

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

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.