When should I use `drain` vs `into_iter`?

Question

On the surface, it looks like both drain and into_iter provide similar iterators, namely over the values of the collection. However, they are different:

fn m         


        

Answer 1

They are somewhat redundant with each other. However, as you say, Drain just borrows the vector, in particular, it has a lifetime connected with the vector. If one is wishing to return an iterator, or otherwise munge iterators in the most flexible way possible, using into_iter is better, since it's not chained to the owner of the originating Vec. If one is wishing to reuse the data structure (e.g. reuse the allocation) then drain is the most direct way of doing this.

Also, a (somewhat) theoretical concern is that Drain needs to result in the originating structure being a valid instance of whatever type it is, that is, either preserve invariants, or fix them up at the end, while IntoIter can mangle the structure as much as it likes, since it has complete control of the value.

I say only "somewhat" theoretical because there is a small, real world example of this in std already: HashMap exposes .drain and .into_iter via its internal RawTable type, which also has those methods. into_iter can just read the hash of the value being moved directly and that's that, but drain has to be careful to update the hash to indicate that the cell is then empty, not just read it. Obviously this is absolutely tiny in this instance (probably only one or two additional instructions) but for more complicated data structures like trees there may be some non-trivial gains to be had from breaking the invariants of the data structure.

Answer 2

After using drain, the Vec is empty but the storage previously allocated for its elements remains allocated. This means that you can insert new elements in the Vec without having to allocate storage for them until you reach the Vec's capacity.

Note that before you can use the Vec again, you must drop all references to the Drain iterator. Drain's implementation of Drop will remove all elements that hadn't been removed from the Vec yet, so the Vec will be empty even if you didn't finish the iteration.