Tracking issue for Vec::remove_item

[madseagames]

Implemented in #40325

impl<T: PartialEq> Vec<T> {
    pub fn remove_item(&mut self, item: &T) -> Option<T> { /*…*/ }
}

[clarfonthey]

PR moved to #40325 due to reasons

[clarfonthey]

Comments from original thread:

1. I think that we should add this method to VecDeque too.
2. Is remove_last_item desired?

[madseagames]

@clarcharr for remove_last_item you can simply do vec.remove(vec.len() - 1))

[clarfonthey]

@madseagames I meant specifically a method that searches for the item from the end of the vec instead of the beginning

[oberien]

What do you think about adding remove_swap_item? Just as remove_swap reduces the runtime complexity from O(n) to O(1) compared to remove, remove_swap_item would reduce it from O(n + (n-m)) to O(n).

[clarfonthey]

I like swap_remove_item.

[MarkSwanson]

It would be nice if this was more generic.
let v: Vec = Vec::new();
v.remove_item("s"); <-- fails because &str is not a &String

we really want the remove_item "item: &T" to be "something that we can compare equality with the type in the container". This would let remove_item() walk the T items, compare equality, and remove if equal.

[sfackler]

Seems reasonable to change the signature to fn remove_item<U>(&mut self, item: &U) -> Option<T> where T: PartialEq<U> + ?Sized

[leoyvens]

Reviewing the naming used in method names and the docs, it would seem that iterators yield items while vecs contain elements. Considering that we insert elements then we should also remove elements and the method should be called remove_element. That name is a bit long so I'd propose simply remove_eq. However I wonder if we should favor a more general remove_by, or have both.

fn remove_by<F: FnMut(&T) -> bool>(&mut self, f: F)

[zbraniecki]

Any plan to stabilize this?

[SimonSapin]

This has been in nightly for a year with no issue reported on the method itself. There are proposals for additional methods, but that shouldn’t block this one. Please submit separate PRs or RFCs.

@rfcbot fcp merge

[rfcbot]

Team member @SimonSapin has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Kimundi
• @SimonSapin
• @alexcrichton
• @aturon
• @dtolnay
• @sfackler
• @withoutboats

Concerns:

• rationale-and-vecdeque resolved by Tracking issue for Vec::remove_item #40062 (comment)

Once a majority of reviewers approve (and none object), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[sfackler]

Are we switching to a V: PartialEq<T> bound?

[SimonSapin]

Oops, sorry I missed that. Yes, let’s.

[gnzlbg]

Again here, as a maintainer of collections that offer the Vec and VecDeque APIs I'd like at least a summary comment explaining what this method does, why this design was followed, alternatives, and addressing the issues mentioned here that have received zero replies:

• should this method be added to VecDeque?
• @sfackler :

Seems reasonable to change the signature to fn remove_item<U>(&mut self, item: &U) -> Option<T> where T: PartialEq<U> + ?Sized

• @leodasvacas naming issue: why items instead of elements? why remove_items instead of remove_by, etc.

[alexcrichton]

@rfcbot concern rationale-and-vecdeque

Just gonna formally register @gnzlbg's concern above

[kornelski]

Not an issue with the method per se, but it may need to be very clearly documented that the reference is not supposed to be to an item that is in the Vec already, as it creates impossible borrow-checker conundrum.

Users coming from the C world of pointers but no proper equality comparison, may be confused by this method, e.g. https://users.rust-lang.org/t/difficult-borrowing-situation/16794

The remove_eq name mentioned previously would help.

[alexcrichton]

@SimonSapin as the proposer for FCP, do you have thoughts on @gnzlbg's concern?

[droundy]

My thinking is that the remove_by suggested by @leodasvacas would sidestep most of the issues here.

[Centril]

cc @SimonSapin re. #40062 (comment)

[SimonSapin]

I don’t have a strong desire for this particular feature myself, I proposed FCP as an effort to reduce the number of features in "unstable limbo". That said:

Regarding VecDeque, sure, I don’t see a reason not to add it there as well.

remove_by as proposed in #40062 (comment) sounds good to me. It is more general, and goes with precedent of Iterator::position also taking a boolean callable predicate rather than relying on PartialEq. (Even further, the precedent of Iterator not having a method like position that would rely on PartialEq.)

[withoutboats]

I notice two things:

1. There are a lot of methods similar to this we could add, and its not obvious to me which set of those methods is the ideal set.
2. This has sat in FCP concern limbo for 8 months without anyone complaining.

I think we should not stabilize this just because it exists, but instead someone should come up with a well justified explanation of exactly what the best "find and remove" set of methods of vec-likes would be.

[SimonSapin]

Good points.

drain (which is stable) and drain_filter #43244 also fit the "find and remove" description, and we had a similar concern #43244 (comment) about the combinations of filtering v.s. non-filtering and self-exhausting on drop (rust-lang/rfcs#2369) v.s. not.

[alexcrichton]

@rfcbot resolve rationale-and-vecdeque

I don't want to personally be on the hook for blocking this any more

[SimonSapin]

Checking KodrAus’ checkbox per rust-lang/team@45013d1

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

[KodrAus]

Since we've merged the deprecation would we like to close this tracking issue now? Or keep it open until the unstable deprecated method is removed entirely?

[LukasKalbertodt]

I think keeping this open until we removed the method is a good idea. How long do we want to wait with that by the way? I guess a couple of cycles is sufficient?

[AgarwalPragy]

Before closing, it would be great if someone could suggest a "one clean and obvious" way to remove the first/last occurance of an item from a Vector.

Irrespective of the arguments made here, a method removing the first/last occurance of an item is provided across all major programming languages, and is to be "expected"

Anyone new to rust is bound to google "remove from vec rust" and end up on this discussion which would only leave them more confused.

[LukasKalbertodt]

This StackOverflow Q&A should answer those questions. But here is a copy of my answer for convenience:

---

Remove first element equal to needle

// Panic if no such element is found
vec.remove(vec.iter().position(|x| *x == needle).expect("needle not found"));

// Ignore if no such element is found
if let Some(pos) = vec.iter().position(|x| *x == needle) {
    vec.remove(pos);
}

You can of course handle the None case however you like (panic and ignoring are not the only possibilities).

Remove last element equal to needle

Like the first element, but replace position with rposition.

Remove all elements equal to needle

vec.retain(|x| *x != needle);

... or with swap_remove

Remember that remove has a runtime of O(n) as all elements after the index need to be shifted. Vec::swap_remove has a runtime of O(1) as it swaps the to-be-removed element with the last one. If the order of elements is not important in your case, use swap_remove instead of remove!

[LukasKalbertodt]

It might be worth adding more examples (maybe all of the ones above) to the Vec::remove docs.

[nrabulinski]

I'd like to add those to the docs, should they go along the example that we currently have?

[LukasKalbertodt]

@nrabulinski What examples are you referring to? I could imagine those "remove examples" either going on the type (as a new section "Removing elements" or something like that) or directly on the Vec::remove method (below the existing docs). And by the way, feel free to add (parts of) my text/examples verbatim.

[nrabulinski]

Thank you. I was referring to those "remove examples" as to whether I should append them to what we currently have in docs for Vec::remove, put them somewhere else or perhaps modify examples for Vec::remove to include removal of specific element

[LukasKalbertodt]

append them to what we currently have in docs for Vec::remove

That sounds fine to me. Feel free to just open a PR and we can still see about the specifics then :)