Explain one-past-the-end pointer in std library

Signed-off-by: xizheyin <[email protected]>

Author: xizheyin

library/core/src/ptr/const_ptr.rs

@@ -388,6 +388,12 @@ impl<T: ?Sized> *const T {
     ///   bounds of that allocated object. In particular, this range must not "wrap around" the edge
     ///   of the address space.
     ///
+    /// * Note that the special case of "one-past-the-end" pointers is explicitly allowed: a pointer
+    ///   exactly one byte past the end of an allocated object (at address `base + size`, using the
+    ///   terminology from [allocated object]) is valid for offset calculations, though dereferencing
+    ///   such a pointer remains invalid. This allows for efficiently calculating ranges and detecting
+    ///   the end of iteration.
+    ///
     /// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
     /// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
     /// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always

library/core/src/ptr/mod.rs

@@ -116,6 +116,9 @@
 //! `addresses`, the following are guaranteed:
 //! - For all addresses `a` in `addresses`, `a` is in the range `base .. (base +
 //!   size)` (note that this requires `a < base + size`, not `a <= base + size`)
+//! - However, for pointer offset calculations, a special "one-past-the-end" address
+//!   exactly at `base + size` is considered valid, though this address should not be
+//!   dereferenced. This exception is crucial for iteration and range calculations.
 //! - `base` is not equal to [`null()`] (i.e., the address with the numerical
 //!   value 0)
 //! - `base + size <= usize::MAX`