Tracking issue for BinaryHeap::{push_pop, replace}

[eefriedman]

Updated issue

Tracking issue for

• BinaryHeap::push_pop
• BinaryHeap::replace

Original Report

std::collections::BinaryHeap has a bunch of unstable methods without proper stability markings; filing an issue to point them at. Someone please label this B-unstable.

[BurntSushi]

It looks like the unstable methods are: from_vec, push_pop, replace, into_vec, into_sorted_vec and drain. Except for drain, is there any writing on why these methods were not stabilized? Were there any specific reservations about those methods?

[alexcrichton]

I believe they weren't stabilized mostly because they didn't fit into any existing collections conventions and to be conservative we didn't add too much special functionality to collections around 1.0. They're pretty innocuous though, so I'd imagine they're ripe for some small modernization followed by stabilization.

[sfackler]

from_vec and into_vec seem like super obvious and straightforward methods to stabilize as is.

push_pop and replace seems a bit weirder. What use cases are they targeting? What kind of performance improvements do you actually see using them vs replicating their behavior naively? C++ and Java don't have any equivalent functionality.

[aturon]

Should replace from_vec with an impl of the From trait.

[sfackler]

We should be careful to document the impl so that people can ctrl+f heapify and find it.

[alexcrichton]

This issue is now entering its cycle-long FCP for stabilization in 1.5

The specific actions to be taken here will be:

• Deprecate from_vec in favor of From<Vec<T>> for BinaryHeap<T>
• Stabilize into_vec as well as add Into<Vec<T>> for BinaryHeap<T>
• Stabilize intoto_sorted_vec

The push_pop and replace methods will have an FCP at a later time.

[BurntSushi]

I think we want From<BinaryHeap<T>> for Vec<T> instead? (I think this gives us the Into impl automatically.)

[photino]

If we have already stabilized the into_vec method, are there any good reasons for adding Into<Vec<T>> for BinaryHeap<T> with the same functionality?

[sfackler]

Into<Vec<T>> can be used in generic contexts.

[alexcrichton]

The libs team discussed this today and the decision was to stabilize.

[constituent]

I'd like to ask a question about replace.

It seems it's the optimized (and suggested) way if you are sure that one item will be pushed after a pop. Sometimes the pushed item is related with the popped one, say, pop an x: u32 and then push x / 2 back. In this situation replace(&mut self, item: T) cannot be used as the will-be-pushed item is not known while calling replace.

Should I use normal pop & push, or replace can have a more generalized signature?

Furthermore, is it possible to push back conditionally, e.g. only if x > 1 (else break the pop-push-pop-... loop)

[bsteinb]

@constituent I think you might be interested in contain-rs/discuss#13

[sfackler]

I believe the functionality of replace is subsumed by peek_mut.

[sfackler]

The libs team discussed the remaining unstable methods, and are putting them in a final comment period to deprecate. They're fairly niche, and peek_mut provides similar functionality in a more flexible API.

[alexcrichton]

The libs team discussed this at triage the other day and the conclusion was to deprecate