diff --git a/library/core/src/ptr/const_ptr.rs b/library/core/src/ptr/const_ptr.rs index a1dab23ea7b49..9366cb36c6efa 100644 --- a/library/core/src/ptr/const_ptr.rs +++ b/library/core/src/ptr/const_ptr.rs @@ -5,24 +5,7 @@ use crate::mem::{self, SizedTypeProperties}; use crate::slice::{self, SliceIndex}; impl *const T { - /// Returns `true` if the pointer is null. - /// - /// Note that unsized types have many possible null pointers, as only the - /// raw data pointer is considered, not their length, vtable, etc. - /// Therefore, two pointers that are null may still not compare equal to - /// each other. - /// - /// # Panics during const evaluation - /// - /// If this method is used during const evaluation, and `self` is a pointer - /// that is offset beyond the bounds of the memory it initially pointed to, - /// then there might not be enough information to determine whether the - /// pointer is null. This is because the absolute address in memory is not - /// known at compile time. If the nullness of the pointer cannot be - /// determined, this method will panic. - /// - /// In-bounds pointers are never null, so the method will never panic for - /// such pointers. + #[doc = include_str!("docs/is_null.md")] /// /// # Examples /// @@ -1550,50 +1533,7 @@ impl *const [T] { unsafe { index.get_unchecked(self) } } - /// Returns `None` if the pointer is null, or else returns a shared slice to - /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require - /// that the value has to be initialized. - /// - /// [`as_ref`]: #method.as_ref - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be [valid] for reads for `ptr.len() * size_of::()` many bytes, - /// and it must be properly aligned. This means in particular: - /// - /// * The entire memory range of this slice must be contained within a single [allocation]! - /// Slices can never span across multiple allocations. - /// - /// * The pointer must be aligned even for zero-length slices. One - /// reason for this is that enum layout optimizations may rely on references - /// (including slices of any length) being aligned and non-null to distinguish - /// them from other data. You can obtain a pointer that is usable as `data` - /// for zero-length slices using [`NonNull::dangling()`]. - /// - /// * The total size `ptr.len() * size_of::()` of the slice must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// See also [`slice::from_raw_parts`][]. - /// - /// [valid]: crate::ptr#safety - /// [allocation]: crate::ptr#allocation - /// - /// # Panics during const evaluation - /// - /// This method will panic during const evaluation if the pointer cannot be - /// determined to be null or not. See [`is_null`] for more information. - /// - /// [`is_null`]: #method.is_null + #[doc = include_str!("docs/as_uninit_slice.md")] #[inline] #[unstable(feature = "ptr_as_uninit", issue = "75402")] pub const unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit]> { diff --git a/library/core/src/ptr/docs/as_uninit_slice.md b/library/core/src/ptr/docs/as_uninit_slice.md new file mode 100644 index 0000000000000..c80c04058838f --- /dev/null +++ b/library/core/src/ptr/docs/as_uninit_slice.md @@ -0,0 +1,44 @@ +Returns `None` if the pointer is null, or else returns a shared slice to +the value wrapped in `Some`. In contrast to [`as_ref`], this does not require +that the value has to be initialized. + +[`as_ref`]: #method.as_ref + +# Safety + +When calling this method, you have to ensure that *either* the pointer is null *or* +all of the following is true: + +* The pointer must be [valid] for reads for `ptr.len() * size_of::()` many bytes, +and it must be properly aligned. This means in particular: + +* The entire memory range of this slice must be contained within a single [allocation]! +Slices can never span across multiple allocations. + +* The pointer must be aligned even for zero-length slices. One +reason for this is that enum layout optimizations may rely on references +(including slices of any length) being aligned and non-null to distinguish +them from other data. You can obtain a pointer that is usable as `data` +for zero-length slices using [`NonNull::dangling()`]. + +* The total size `ptr.len() * size_of::()` of the slice must be no larger than `isize::MAX`. +See the safety documentation of [`pointer::offset`]. + +* You must enforce Rust's aliasing rules, since the returned lifetime `'a` is +arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. +In particular, while this reference exists, the memory the pointer points to must +not get mutated (except inside `UnsafeCell`). + +This applies even if the result of this method is unused! + +See also [`slice::from_raw_parts`][]. + +[valid]: crate::ptr#safety +[allocation]: crate::ptr#allocation + +# Panics during const evaluation + +This method will panic during const evaluation if the pointer cannot be +determined to be null or not. See [`is_null`] for more information. + +[`is_null`]: #method.is_null diff --git a/library/core/src/ptr/docs/is_null.md b/library/core/src/ptr/docs/is_null.md new file mode 100644 index 0000000000000..7368ab9b57630 --- /dev/null +++ b/library/core/src/ptr/docs/is_null.md @@ -0,0 +1,18 @@ +Returns `true` if the pointer is null. + +Note that unsized types have many possible null pointers, as only the +raw data pointer is considered, not their length, vtable, etc. +Therefore, two pointers that are null may still not compare equal to +each other. + +# Panics during const evaluation + +If this method is used during const evaluation, and `self` is a pointer +that is offset beyond the bounds of the memory it initially pointed to, +then there might not be enough information to determine whether the +pointer is null. This is because the absolute address in memory is not +known at compile time. If the nullness of the pointer cannot be +determined, this method will panic. + +In-bounds pointers are never null, so the method will never panic for +such pointers. diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs index 968f033bf5983..efe1031b79cac 100644 --- a/library/core/src/ptr/mut_ptr.rs +++ b/library/core/src/ptr/mut_ptr.rs @@ -5,24 +5,7 @@ use crate::mem::{self, SizedTypeProperties}; use crate::slice::{self, SliceIndex}; impl *mut T { - /// Returns `true` if the pointer is null. - /// - /// Note that unsized types have many possible null pointers, as only the - /// raw data pointer is considered, not their length, vtable, etc. - /// Therefore, two pointers that are null may still not compare equal to - /// each other. - /// - /// # Panics during const evaluation - /// - /// If this method is used during const evaluation, and `self` is a pointer - /// that is offset beyond the bounds of the memory it initially pointed to, - /// then there might not be enough information to determine whether the - /// pointer is null. This is because the absolute address in memory is not - /// known at compile time. If the nullness of the pointer cannot be - /// determined, this method will panic. - /// - /// In-bounds pointers are never null, so the method will never panic for - /// such pointers. + #[doc = include_str!("docs/is_null.md")] /// /// # Examples /// @@ -1906,53 +1889,10 @@ impl *mut [T] { unsafe { index.get_unchecked_mut(self) } } - /// Returns `None` if the pointer is null, or else returns a shared slice to - /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require - /// that the value has to be initialized. - /// - /// For the mutable counterpart see [`as_uninit_slice_mut`]. - /// - /// [`as_ref`]: pointer#method.as_ref-1 - /// [`as_uninit_slice_mut`]: #method.as_uninit_slice_mut - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be [valid] for reads for `ptr.len() * size_of::()` many bytes, - /// and it must be properly aligned. This means in particular: - /// - /// * The entire memory range of this slice must be contained within a single [allocation]! - /// Slices can never span across multiple allocations. - /// - /// * The pointer must be aligned even for zero-length slices. One - /// reason for this is that enum layout optimizations may rely on references - /// (including slices of any length) being aligned and non-null to distinguish - /// them from other data. You can obtain a pointer that is usable as `data` - /// for zero-length slices using [`NonNull::dangling()`]. - /// - /// * The total size `ptr.len() * size_of::()` of the slice must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// See also [`slice::from_raw_parts`][]. - /// - /// [valid]: crate::ptr#safety - /// [allocation]: crate::ptr#allocation + #[doc = include_str!("docs/as_uninit_slice.md")] /// - /// # Panics during const evaluation - /// - /// This method will panic during const evaluation if the pointer cannot be - /// determined to be null or not. See [`is_null`] for more information. - /// - /// [`is_null`]: #method.is_null-1 + /// # See Also + /// For the mutable counterpart see [`as_uninit_slice_mut`](pointer::as_uninit_slice_mut). #[inline] #[unstable(feature = "ptr_as_uninit", issue = "75402")] pub const unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit]> {