Add a note about the correctness and the effect on unsafe code to the `ExactSizeIterator` docs

As it is a safe trait it does not provide any guarantee that the
returned length is correct and as such unsafe code must not rely on it.

That's why `TrustedLen` exists.

Fixes https://github.com/rust-lang/rust/issues/81739

1 files changed, 6 insertions, 0 deletions

diff --git a/library/core/src/iter/traits/exact_size.rs b/library/core/src/iter/traits/exact_size.rs
index 996d62e2b4a..167db3359f2 100644
--- a/library/core/src/iter/traits/exact_size.rs
+++ b/library/core/src/iter/traits/exact_size.rs
@@ -13,6 +13,12 @@
 /// implement it. However, you may be able to provide a more performant
 /// implementation than the default, so overriding it in this case makes sense.
 ///
+/// Note that this trait is a safe trait and as such does *not* and *cannot*
+/// guarantee that the returned length is correct. This means that `unsafe`
+/// code **must not** rely on the correctness of [`Iterator::size_hint`]. The
+/// unstable and unsafe [`TrustedLen`](super::marker::TrustedLen) trait gives
+/// this additional guarantee.
+///
 /// [`len`]: ExactSizeIterator::len
 ///
 /// # Examples