[Heap] Change value of minimum or maximum element

[CTMacUser]

Adds two methods to change either the minimum or maximum element of a Heap instance. If the value changes enough that the previous second-place element now surpasses it, that former second-place element will take over for the heap's min/max element.

For testing purposes, I needed a way to precisely define a heap's pre-test state. Therefore, I also added a new initializer that receives an exact storage layout as input. It's a fail-able initializer. This requires a testing function. There is such a procedure locked in the debug-only invariant code. I moved that code to a new unconditional method that both the new initializer and the invariant-test code both reference.

Checklist

• I've read the Contribution Guidelines
• My contributions are licensed under the Swift license.
• I've followed the coding style of the rest of the project.
• I've added tests covering all new code paths my change adds to the project (if appropriate).
• I've added benchmarks covering new functionality (if appropriate).
• I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• I've updated the documentation if necessary.

[lorentey]

The replaceMin and replaceMax members look like good additions to me. BTW, do you have motivating example for adding these? It's not immediately obvious to me that these operations would often come handy in practice. (It would also be nice to list heap implementations in other languages that provide similar operations.)

I strongly object to introducing _someHeapViolation -- I think that part of this change needs to be reverted, and the public init(raw:) replaced with an underscored & _spi(Testing) initializer.

[lorentey]

This is a far simpler case than the general bubbleUp. I think would be beneficial to replace this with a direct conditional swapAt:

Suggested change

	handle.bubbleUp(maxNode) // This must happen first
	if handle[maxNode] < handle[.root] {
	handle.swapAt(maxNode, .root)
	}

(Untested)

[CTMacUser]

The replaceMin and replaceMax members look like good additions to me. BTW, do you have motivating example for adding these? It's not immediately obvious to me that these operations would often come handy in practice. (It would also be nice to list heap implementations in other languages that provide similar operations.)

This was one of the future directions from the original Heap authors. It makes sense because naïve replacement via a pop and push unnecessarily does two rounds of element shuffling instead of one. (And maybe a reallocation too.)

[lorentey]

@swift-ci test

[lorentey]

Merged with changes in #208