All the examples on https://dlang.org/phobos/std_container_binaryheap.html use heaps initialized from slices. Slice semantics are unintuitive since the slice is at first updated to reflect the data structure of the heap, but at some arbitrary point in the future the connection may be broken, when the binaryHeap causes a reallocation. There should be examples pointing out this unintuitive behavior, and explaining alternate stores and their benefits.
@MathewColin created dlang/phobos pull request #8677 "Better document the use of Heaps with Dynamic Array as Store" mentioning this issue: - Better document the use of Heaps with Dynamic Array as Store Fix issue 18333: binaryHeap documentation inadequately describes slice store invalidation https://github.com/dlang/phobos/pull/8677
dlang/phobos pull request #8677 "Better document the use of Heaps with Dynamic Array as Store" was merged into master: - bd8bdb2dee980c2713be0580d592da29f1341a7a by Matei Calin Ceausu: Better document the use of Heaps with Dynamic Array as Store Fix issue 18333: binaryHeap documentation inadequately describes slice store invalidation - d1b7eebf65b7267580378209082b8d3e18120fc7 by Matei Calin Ceausu: Better document the use of Heaps with Dynamic Array as Store Fix issue 18333: binaryHeap documentation inadequately describes slice store invalidation https://github.com/dlang/phobos/pull/8677