When possible without changing semantics, implement Iterator::last in terms of DoubleEndedIterator::next_back for types in liballoc and libcore.

[khuey]

Provided that the iterator has finite length and does not trigger user-provided code, this is safe.

What follows is a full list of the DoubleEndedIterators in liballoc/libcore and whether this optimization is safe, and if not, why not.

src/liballoc/boxed.rs
Box: Pass through to avoid defeating optimization of the underlying DoubleIterator implementation. This has no correctness impact.

src/liballoc/collections/binary_heap.rs
Iter: Pass through to avoid defeating optimizations on slice::Iter
IntoIter: Not safe, changes Drop order
Drain: Not safe, changes Drop order

src/liballoc/collections/btree/map.rs
Iter: Safe to call next_back, invokes no user defined code.
IterMut: ditto
IntoIter: Not safe, changes Drop order
Keys: Safe to call next_back, invokes no user defined code.
Values: ditto
ValuesMut: ditto
Range: ditto
RangeMut: ditto

src/liballoc/collections/btree/set.rs
Iter: Safe to call next_back, invokes no user defined code.
IntoIter: Not safe, changes Drop order
Range: Safe to call next_back, invokes no user defined code.

src/liballoc/collections/linked_list.rs
Iter: Safe to call next_back, invokes no user defined code.
IterMut: ditto
IntoIter: Not safe, changes Drop order

src/liballoc/collections/vec_deque.rs
Iter: Safe to call next_back, invokes no user defined code.
IterMut: ditto
IntoIter: Not safe, changes Drop order
Drain: ditto

src/liballoc/string.rs
Drain: Safe because return type is a primitive (char)

src/liballoc/vec.rs
IntoIter: Not safe, changes Drop order
Drain: ditto
Splice: ditto

src/libcore/ascii.rs
EscapeDefault: Safe because return type is a primitive (u8)

src/libcore/iter/adapters/chain.rs
Chain: Not safe, invokes user defined code (Iterator impl)

src/libcore/iter/adapters/flatten.rs
FlatMap: Not safe, invokes user defined code (Iterator impl)
Flatten: ditto
FlattenCompat: ditto

src/libcore/iter/adapters/mod.rs
Rev: Not safe, invokes user defined code (Iterator impl)
Copied: ditto
Cloned: Not safe, invokes user defined code (Iterator impl and T::clone)
Map: Not safe, invokes user defined code (Iterator impl + closure)
Filter: ditto
FilterMap: ditto
Enumerate: Not safe, invokes user defined code (Iterator impl)
Skip: ditto
Fuse: ditto
Inspect: ditto

src/libcore/iter/adapters/zip.rs
Zip: Not safe, invokes user defined code (Iterator impl)

src/libcore/iter/range.rs
ops::Range: Not safe, changes Drop order, but ALREADY HAS SPECIALIZATION
ops::RangeInclusive: ditto

src/libcore/iter/sources.rs
Repeat: Not safe, calling last should iloop.
Empty: No point, iterator is at most one item long.
Once: ditto
OnceWith: ditto

src/libcore/option.rs
Item: No point, iterator is at most one item long.
Iter: ditto
IterMut: ditto
IntoIter: ditto

src/libcore/result.rs
Iter: No point, iterator is at most one item long
IterMut: ditto
IntoIter: ditto

src/libcore/slice/mod.rs
Split: Not safe, invokes user defined closure
SplitMut: ditto
RSplit: ditto
RSplitMut: ditto
Windows: Safe, already has specialization
Chunks: ditto
ChunksMut: ditto
ChunksExact: ditto
ChunksExactMut: ditto
RChunks: ditto
RChunksMut: ditto
RChunksExact: ditto
RChunksExactMut: ditto

src/libcore/str/mod.rs
Chars: Safe, already has specialization
CharIndices: ditto
Bytes: ditto
Lines: Safe to call next_back, invokes no user defined code.
LinesAny: Deprecated
Everything that is generic over P: Pattern: Not safe because Pattern invokes user defined code.
SplitWhitespace: Safe to call next_back, invokes no user defined code.
SplitAsciiWhitespace: ditto

This is attempt 2 of #60130.

r? @sfackler

[sfackler]

These all seem right to me, thanks!

@bors r+

[bors]

📌 Commit db16e17 has been approved by sfackler

[ssomers]

For what it's worth, I argue the qualification "IntoIter: Not safe, changes Drop order" is inaccurate, for btree collections and probably others.

Currently, what happens is:

1. BTreeMap hands over its tree to IntoIter through ManuallyDrop.
2. IntoIter::last iterates up to the last element in ascending key order, drops each element, deallocates tree nodes (chunks of memory) as they become obsolete (except a pile of tree nodes up to the root, but that doesn't matter here).
3. When IntoIter::last hits the last element, it ptr::reads it from the tree node, deallocates the last leaf node, has the drop handler (since it consumes self) deallocate the remainder of the tree (the pile of tree nodes), and returns the last element.

So elements are dropped in IntoIter's ascending key order, except of course the last one. If we were to "shortcut" last:

2. IntoIter::last immediately asks next_back to locate the last element, ptr::reads it from the tree node, might deallocate that tree node early (★), then has the drop handler (since it consumes self) iterate and drop the remaining elements and deallocate the tree nodes just like step 2. above does.
3. Finally IntoIter::last just returns the last element.

Elements are dropped in the same ascending order. But even how that intertwines with the deallocation of tree nodes, which could possibly matter if the element's drop handler somehow notices the amount of heap memory allocated, is the same… except that…

★ The last tree node may be deallocated early, if the element located by last() is the last one contained in a tree node. That would happen if:

• A btree collection has only one element to begin with, but then the tree node deallocated early is the only tree node; nothing changes after all.
• The IntoIter already had some trailing element nibbled off, before last closes off. At last, here is a case where deallocation order would change if last would shortcut:

use std::collections::BTreeSet;

fn main() {
    let s = (0..12).collect::<BTreeSet<_>>();
    // Keys 0..=5 are in first leaf, 6 is in root node, 7..=11 are in second leaf
    let mut it = s.into_iter();
    assert_eq!(it.next_back(), Some(11));
    assert_eq!(it.next_back(), Some(10));
    assert_eq!(it.next_back(), Some(9));
    assert_eq!(it.next_back(), Some(8));
    assert_eq!(it.last(), Some(7));
}

A more accurate reason for leaving IntoIter alone is: "Useless, doesn't help". Because btree collections (like LinkedList and I believe VecDeque) have an infrastructure that scales linearly with the number of elements, and most of the work that IntoIter does is deallocating that infrastructure, in addition to dropping the elements if they have a drop handler. If there is anything to be gained, it's nothing like improving O(n) to O(1) like this PR did for ordinary iterators.