Rollup merge of rust-lang#107962 - scottmcm:why-not-exact, r=Mark-Simulacrum

Add a doc note about why `Chain` is not `ExactSizeIterator`

Inspired by <https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/Why.20isn't.20Chain.3CA.2C.20B.3E.20an.20ExactSizeIterator.3F/near/327395874>.

Author: Dylan-DPC

library/core/src/iter/traits/exact_size.rs

@@ -21,6 +21,16 @@
 ///
 /// [`len`]: ExactSizeIterator::len
 ///
+/// # When *shouldn't* an adapter be `ExactSizeIterator`?
+///
+/// If an adapter makes an iterator *longer*, then it's usually incorrect for
+/// that adapter to implement `ExactSizeIterator`.  The inner exact-sized
+/// iterator might already be `usize::MAX`-long, and thus the length of the
+/// longer adapted iterator would no longer be exactly representable in `usize`.
+///
+/// This is why [`Chain<A, B>`](crate::iter::Chain) isn't `ExactSizeIterator`,
+/// even when `A` and `B` are both `ExactSizeIterator`.
+///
 /// # Examples
 ///
 /// Basic usage:

library/core/src/iter/traits/marker.rs

@@ -31,6 +31,17 @@ impl<I: FusedIterator + ?Sized> FusedIterator for &mut I {}
 /// The iterator must produce exactly the number of elements it reported
 /// or diverge before reaching the end.
 ///
+/// # When *shouldn't* an adapter be `TrustedLen`?
+///
+/// If an adapter makes an iterator *shorter* by a given amount, then it's
+/// usually incorrect for that adapter to implement `TrustedLen`.  The inner
+/// iterator might return more than `usize::MAX` items, but there's no way to
+/// know what `k` elements less than that will be, since the `size_hint` from
+/// the inner iterator has already saturated and lost that information.
+///
+/// This is why [`Skip<I>`](crate::iter::Skip) isn't `TrustedLen`, even when
+/// `I` implements `TrustedLen`.
+///
 /// # Safety
 ///
 /// This trait must only be implemented when the contract is upheld. Consumers