Quickly fork, edit online, and submit a pull request for this page.
Requires a signed-in GitHub account. This works well for small changes.
If you'd like to make larger changes you may want to consider using
a local clone.

std.container.binaryheap

This module provides a BinaryHeap (aka priority queue)
adaptor that makes a binary heap out of any user-provided random-access range.

Implements a binary heap
container on top of a given random-access range type (usually T[]) or a random-access container type (usually Array!T). The
documentation of BinaryHeap will refer to the underlying range or
container as the store of the heap.

The binary heap induces structure over the underlying store such that
accessing the largest element (by using the front property) is a
Ο(1) operation and extracting it (by using the removeFront() method) is done fast in Ο(log n) time.

If less is the less-than operator, which is the default option,
then BinaryHeap defines a so-called max-heap that optimizes
extraction of the largest elements. To define a min-heap,
instantiate BinaryHeap with "a > b" as its predicate.

Simply extracting elements from a BinaryHeap container is
tantamount to lazily fetching elements of Store in descending
order. Extracting elements from the BinaryHeap to completion
leaves the underlying store sorted in ascending order but, again,
yields elements in descending order.

If Store is a range, the BinaryHeap cannot grow beyond the
size of that range. If Store is a container that supports insertBack, the BinaryHeap may grow by adding elements to the
container.

Converts the store s into a heap. If initialSize is
specified, only the first initialSize elements in s
are transformed into a heap, after which the heap can grow up
to r.length (if Store is a range) or indefinitely (if
Store is a container with insertBack). Performs
Ο(min(r.length, initialSize)) evaluations of less.

void acquire(Store s, size_t initialSize = size_t.max);

Takes ownership of a store. After this, manipulating s may make
the heap work incorrectly.

void assume(Store s, size_t initialSize = size_t.max);

Takes ownership of a store assuming it already was organized as a
heap.

auto release();

Clears the heap. Returns the portion of the store from 0 up to
length, which satisfies the heap property.

@property bool empty();

Returns true if the heap is empty, false otherwise.

@property BinaryHeap dup();

Returns a duplicate of the heap. The dup method is available only if the
underlying store supports it.

@property size_t length();

Returns the length of the heap.

@property size_t capacity();

Returns the capacity of the heap, which is the length of the
underlying store (if the store is a range) or the capacity of the
underlying store (if the store is a container).

@property ElementType!Store front();

Returns a copy of the front of the heap, which is the largest element
according to less.

void clear();

Clears the heap by detaching it from the underlying store.

size_t insert(ElementType!Store value);

Inserts value into the store. If the underlying store is a range
and length == capacity, throws an exception.

void removeFront();

alias popFront = removeFront;

Removes the largest element from the heap.

ElementType!Store removeAny();

Removes the largest element from the heap and returns a copy of
it. The element still resides in the heap's store. For performance
reasons you may want to use removeFront with heaps of objects
that are expensive to copy.

void replaceFront(ElementType!Store value);

Replaces the largest element in the store with value.

bool conditionalInsert(ElementType!Store value);

If the heap has room to grow, inserts value into the store and
returns true. Otherwise, if less(value, front), calls replaceFront(value) and returns again true. Otherwise, leaves
the heap unaffected and returns false. This method is useful in
scenarios where the smallest k elements of a set of candidates
must be collected.

bool conditionalSwap(ref ElementType!Store value);

Swapping is allowed if the heap is full. If less(value, front), the
method exchanges store.front and value and returns true. Otherwise, it
leaves the heap unaffected and returns false.