Implement `append` for `BinaryHeap`

[apasel422]

This can be done in O(n + m) time by appending the underlying vectors and then using the build heap algorithm in the From<Vec<T>> impl. Note that in some circumstances this will perform worse than repeatedly pushing (as is done in h1.extend(h2)), because the time complexity of that approach is O(m log (m + n)). In both approaches, append should ensure that the larger of the two heaps acts as the "destination" of the merge in order to move as few elements as possible.

append should use a heuristic to determine which approach to take. This should be based on the sizes of the two heaps, but may also incorporate the vectors' capacities.

Pseudo-code:

use std::mem::swap;

fn shouldMergeWithBuildHeap<T>(v1: &Vec<T>, v2: &Vec<T>) -> bool { ... }

impl<T: Ord> BinaryHeap<T> {
    pub fn append(&self, other: &mut Self) {
        if other.is_empty() {
            return;
        }

        if self.is_empty() {
            swap(self, other);
            return;
        }

        if self.len() < other.len() {
            swap(self, other);
        }

        if shouldMergeWithBuildHeap(&self.data, &other.data) {
            self.data.append(&mut other.data.append);
            self.build_heap();
        } else {
            self.extend(other.drain());
        }
    }

    fn build_heap(&mut self) {
        let mut n = self.len() / 2;
        while n > 0 {
            n -= 1;
            self.sift_down(n);
        }
    }
}

For now, a simple version that just extends the smaller one into the larger one could suffice:

impl<T: Ord> BinaryHeap<T> {
    pub fn append(&self, other: &mut Self) {
        if other.is_empty() {
            return;
        }

        if self.is_empty() {
            swap(self, other);
            return;
        }

        if self.len() < other.len() {
            swap(self, other);
        }

        self.extend(other.drain());
    }
}

[xosmig]

I'd like to perform it.

[apasel422]

@xosmig Cool. Feel free to submit a PR!

[alexcrichton]

🔔 This issue is now entering its final comment period for stabilization 🔔

The libs team was unfortunately a little late on stabilizations this cycle, but we're thinking of probably doing a backport of stabilizations partway through the beta cycle. This API also follows existing conventions so should be an easy stabilization!

[alexcrichton]

The libs team discussed this issue during triage yesterday and the decision was to stabilize. We realize that the FCP for this issue was pretty short, however, so please comment with any objections you might have! We're very willing to backport an un-stabilization for the few APIs we have this cycle.