Implement append for b-trees.

[jooert]

I have finally found time to revive #26227, this time only with an append implementation.

The algorithm implemented here is linear in the size of the two b-trees. It firsts creates
a MergeIter from the two b-trees and then builds a new b-tree by pushing
key-value pairs from the MergeIter into nodes at the right heights.

Three functions for stealing have been added to the implementation of Handle as
well as a getter for the height of a NodeRef.

The docs have been updated with performance information about BTreeMap::append and
the remark about B has been removed now that it is the same for all instances of BTreeMap.

cc @gereeter@gankro@apasel422

[rust-highfive]

r? @alexcrichton

(rust_highfive has picked a reviewer for you, use r? to override)

[apasel422]

Is it possible to use this instead (i.e. without explicitly getting a reference to the fields)?

match(self.left_cur,self.right_cur){(Some((ref left_key, _)),Some((ref right_key, _))) => {
...

EDIT: Never mind, I expect not.

[alexcrichton]

r? @apasel422

[gereeter]

This unreachable branch seems a bit ugly to me. It would be better if cur_node just explicitly stored a Leaf node. The loop for descending to a leaf node would just need to use a separate variable for its internal state.

[gereeter]

This looks excellent on the correctness and algorithmic fronts. The code could use some mostly cosmetic restructuring and possibly some optimization (though that could wait to a later PR), but otherwise everything seems good to me.

Thank you, @jooert!

[apasel422]

@alexcrichton Does this need to be gated?

[alexcrichton]

Ah yeah let's add all new methods as #[unstable], they can likely be quitely stabilized though

[jooert]

Thanks for all your comments! I just pushed a new commit that should fix all of the issues mentioned. I'm not satisifed with the bulk_steal_left method but it works.

[apasel422]

This looks good to me, pending a final review by @gereeter.

[gereeter]

This return is the same, regardless of whether is_left is true or not, so it can be moved out of the if statement.

[apasel422]

@jooert What's the status of this?

[bors]

☔ The latest upstream changes (presumably #33049) made this pull request unmergeable. Please resolve the merge conflicts.

[jooert]

Sorry for the long delay, I resolved the merge conflicts and fixed the remaining issues.