[Issue 18333] New: binaryHeap documentation inadequately describes slice store invalidation

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=18333

          Issue ID: 18333
           Summary: binaryHeap documentation inadequately describes slice
                    store invalidation
           Product: D
           Version: D2
          Hardware: x86
                OS: Windows
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: phobos
          Assignee: nobody at puremagic.com
          Reporter: simen.kjaras at gmail.com

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.

--