Auto merge of #116988 - RalfJung:null, r=WaffleLapkin

bors · bors · commit b049093560aa · 2023-11-06T14:13:00.000Z
document that the null pointer has the 0 address Fixes #116895 Will need t-lang FCP, but I think this is fairly uncontroversial -- there's probably already tons of code out there that relies on this.
diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs
@@ -505,13 +505,18 @@ pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
 
 /// Creates a null raw pointer.
 ///
+/// This function is equivalent to zero-initializing the pointer:
+/// `MaybeUninit::<*const T>::zeroed().assume_init()`.
+/// The resulting pointer has the address 0.
+///
 /// # Examples
 ///
 /// ```
 /// use std::ptr;
 ///
 /// let p: *const i32 = ptr::null();
 /// assert!(p.is_null());
+/// assert_eq!(p as usize, 0); // this pointer has the address 0
 /// ```
 #[inline(always)]
 #[must_use]
@@ -526,13 +531,18 @@ pub const fn null<T: ?Sized + Thin>() -> *const T {
 
 /// Creates a null mutable raw pointer.
 ///
+/// This function is equivalent to zero-initializing the pointer:
+/// `MaybeUninit::<*mut T>::zeroed().assume_init()`.
+/// The resulting pointer has the address 0.
+///
 /// # Examples
 ///
 /// ```
 /// use std::ptr;
 ///
 /// let p: *mut i32 = ptr::null_mut();
 /// assert!(p.is_null());
+/// assert_eq!(p as usize, 0); // this pointer has the address 0
 /// ```
 #[inline(always)]
 #[must_use]
