Skip to content

Commit ba9f624

Browse files
fmeasefmease
authored
Rollup merge of rust-lang#142101 - lolbinarycat:core-dedup-ptr-docs-139190-pt2, r=workingjubilee
core::ptr: deduplicate more method docs used `rg -Fxf library/core/src/ptr/{const,mut}_ptr.rs` to find duplicated doc comments, and `diff -u` after copying them to files to ensure they are actually identical. `sed 's| */// *||'` was then used to translate the doc comments to plain markdown. part of rust-lang#139190
2 parents 0dbf497 + af58ded commit ba9f624

File tree

4 files changed

+68
-126
lines changed

4 files changed

+68
-126
lines changed

‎core/src/ptr/const_ptr.rs‎

Lines changed: 2 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,7 @@ use crate::mem::{self, SizedTypeProperties};
55
use crate::slice::{self, SliceIndex};
66

77
impl<T: ?Sized> *const T {
8-
/// Returns `true` if the pointer is null.
9-
///
10-
/// Note that unsized types have many possible null pointers, as only the
11-
/// raw data pointer is considered, not their length, vtable, etc.
12-
/// Therefore, two pointers that are null may still not compare equal to
13-
/// each other.
14-
///
15-
/// # Panics during const evaluation
16-
///
17-
/// If this method is used during const evaluation, and `self` is a pointer
18-
/// that is offset beyond the bounds of the memory it initially pointed to,
19-
/// then there might not be enough information to determine whether the
20-
/// pointer is null. This is because the absolute address in memory is not
21-
/// known at compile time. If the nullness of the pointer cannot be
22-
/// determined, this method will panic.
23-
///
24-
/// In-bounds pointers are never null, so the method will never panic for
25-
/// such pointers.
8+
#[doc = include_str!("docs/is_null.md")]
269
///
2710
/// # Examples
2811
///
@@ -1550,50 +1533,7 @@ impl<T> *const [T] {
15501533
unsafe { index.get_unchecked(self) }
15511534
}
15521535

1553-
/// Returns `None` if the pointer is null, or else returns a shared slice to
1554-
/// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require
1555-
/// that the value has to be initialized.
1556-
///
1557-
/// [`as_ref`]: #method.as_ref
1558-
///
1559-
/// # Safety
1560-
///
1561-
/// When calling this method, you have to ensure that *either* the pointer is null *or*
1562-
/// all of the following is true:
1563-
///
1564-
/// * The pointer must be [valid] for reads for `ptr.len() * size_of::<T>()` many bytes,
1565-
/// and it must be properly aligned. This means in particular:
1566-
///
1567-
/// * The entire memory range of this slice must be contained within a single [allocation]!
1568-
/// Slices can never span across multiple allocations.
1569-
///
1570-
/// * The pointer must be aligned even for zero-length slices. One
1571-
/// reason for this is that enum layout optimizations may rely on references
1572-
/// (including slices of any length) being aligned and non-null to distinguish
1573-
/// them from other data. You can obtain a pointer that is usable as `data`
1574-
/// for zero-length slices using [`NonNull::dangling()`].
1575-
///
1576-
/// * The total size `ptr.len() * size_of::<T>()` of the slice must be no larger than `isize::MAX`.
1577-
/// See the safety documentation of [`pointer::offset`].
1578-
///
1579-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
1580-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
1581-
/// In particular, while this reference exists, the memory the pointer points to must
1582-
/// not get mutated (except inside `UnsafeCell`).
1583-
///
1584-
/// This applies even if the result of this method is unused!
1585-
///
1586-
/// See also [`slice::from_raw_parts`][].
1587-
///
1588-
/// [valid]: crate::ptr#safety
1589-
/// [allocation]: crate::ptr#allocation
1590-
///
1591-
/// # Panics during const evaluation
1592-
///
1593-
/// This method will panic during const evaluation if the pointer cannot be
1594-
/// determined to be null or not. See [`is_null`] for more information.
1595-
///
1596-
/// [`is_null`]: #method.is_null
1536+
#[doc = include_str!("docs/as_uninit_slice.md")]
15971537
#[inline]
15981538
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
15991539
pub const unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit<T>]> {

‎core/src/ptr/docs/as_uninit_slice.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
Returns `None` if the pointer is null, or else returns a shared slice to
2+
the value wrapped in `Some`. In contrast to [`as_ref`], this does not require
3+
that the value has to be initialized.
4+
5+
[`as_ref`]: #method.as_ref
6+
7+
# Safety
8+
9+
When calling this method, you have to ensure that *either* the pointer is null *or*
10+
all of the following is true:
11+
12+
* The pointer must be [valid] for reads for `ptr.len() * size_of::<T>()` many bytes,
13+
and it must be properly aligned. This means in particular:
14+
15+
* The entire memory range of this slice must be contained within a single [allocation]!
16+
Slices can never span across multiple allocations.
17+
18+
* The pointer must be aligned even for zero-length slices. One
19+
reason for this is that enum layout optimizations may rely on references
20+
(including slices of any length) being aligned and non-null to distinguish
21+
them from other data. You can obtain a pointer that is usable as `data`
22+
for zero-length slices using [`NonNull::dangling()`].
23+
24+
* The total size `ptr.len() * size_of::<T>()` of the slice must be no larger than `isize::MAX`.
25+
See the safety documentation of [`pointer::offset`].
26+
27+
* You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
28+
arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
29+
In particular, while this reference exists, the memory the pointer points to must
30+
not get mutated (except inside `UnsafeCell`).
31+
32+
This applies even if the result of this method is unused!
33+
34+
See also [`slice::from_raw_parts`][].
35+
36+
[valid]: crate::ptr#safety
37+
[allocation]: crate::ptr#allocation
38+
39+
# Panics during const evaluation
40+
41+
This method will panic during const evaluation if the pointer cannot be
42+
determined to be null or not. See [`is_null`] for more information.
43+
44+
[`is_null`]: #method.is_null

‎core/src/ptr/docs/is_null.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Returns `true` if the pointer is null.
2+
3+
Note that unsized types have many possible null pointers, as only the
4+
raw data pointer is considered, not their length, vtable, etc.
5+
Therefore, two pointers that are null may still not compare equal to
6+
each other.
7+
8+
# Panics during const evaluation
9+
10+
If this method is used during const evaluation, and `self` is a pointer
11+
that is offset beyond the bounds of the memory it initially pointed to,
12+
then there might not be enough information to determine whether the
13+
pointer is null. This is because the absolute address in memory is not
14+
known at compile time. If the nullness of the pointer cannot be
15+
determined, this method will panic.
16+
17+
In-bounds pointers are never null, so the method will never panic for
18+
such pointers.

‎core/src/ptr/mut_ptr.rs‎

Lines changed: 4 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,7 @@ use crate::mem::{self, SizedTypeProperties};
55
use crate::slice::{self, SliceIndex};
66

77
impl<T: ?Sized> *mut T {
8-
/// Returns `true` if the pointer is null.
9-
///
10-
/// Note that unsized types have many possible null pointers, as only the
11-
/// raw data pointer is considered, not their length, vtable, etc.
12-
/// Therefore, two pointers that are null may still not compare equal to
13-
/// each other.
14-
///
15-
/// # Panics during const evaluation
16-
///
17-
/// If this method is used during const evaluation, and `self` is a pointer
18-
/// that is offset beyond the bounds of the memory it initially pointed to,
19-
/// then there might not be enough information to determine whether the
20-
/// pointer is null. This is because the absolute address in memory is not
21-
/// known at compile time. If the nullness of the pointer cannot be
22-
/// determined, this method will panic.
23-
///
24-
/// In-bounds pointers are never null, so the method will never panic for
25-
/// such pointers.
8+
#[doc = include_str!("docs/is_null.md")]
269
///
2710
/// # Examples
2811
///
@@ -1906,53 +1889,10 @@ impl<T> *mut [T] {
19061889
unsafe { index.get_unchecked_mut(self) }
19071890
}
19081891

1909-
/// Returns `None` if the pointer is null, or else returns a shared slice to
1910-
/// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require
1911-
/// that the value has to be initialized.
1912-
///
1913-
/// For the mutable counterpart see [`as_uninit_slice_mut`].
1914-
///
1915-
/// [`as_ref`]: pointer#method.as_ref-1
1916-
/// [`as_uninit_slice_mut`]: #method.as_uninit_slice_mut
1917-
///
1918-
/// # Safety
1919-
///
1920-
/// When calling this method, you have to ensure that *either* the pointer is null *or*
1921-
/// all of the following is true:
1922-
///
1923-
/// * The pointer must be [valid] for reads for `ptr.len() * size_of::<T>()` many bytes,
1924-
/// and it must be properly aligned. This means in particular:
1925-
///
1926-
/// * The entire memory range of this slice must be contained within a single [allocation]!
1927-
/// Slices can never span across multiple allocations.
1928-
///
1929-
/// * The pointer must be aligned even for zero-length slices. One
1930-
/// reason for this is that enum layout optimizations may rely on references
1931-
/// (including slices of any length) being aligned and non-null to distinguish
1932-
/// them from other data. You can obtain a pointer that is usable as `data`
1933-
/// for zero-length slices using [`NonNull::dangling()`].
1934-
///
1935-
/// * The total size `ptr.len() * size_of::<T>()` of the slice must be no larger than `isize::MAX`.
1936-
/// See the safety documentation of [`pointer::offset`].
1937-
///
1938-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
1939-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
1940-
/// In particular, while this reference exists, the memory the pointer points to must
1941-
/// not get mutated (except inside `UnsafeCell`).
1942-
///
1943-
/// This applies even if the result of this method is unused!
1944-
///
1945-
/// See also [`slice::from_raw_parts`][].
1946-
///
1947-
/// [valid]: crate::ptr#safety
1948-
/// [allocation]: crate::ptr#allocation
1892+
#[doc = include_str!("docs/as_uninit_slice.md")]
19491893
///
1950-
/// # Panics during const evaluation
1951-
///
1952-
/// This method will panic during const evaluation if the pointer cannot be
1953-
/// determined to be null or not. See [`is_null`] for more information.
1954-
///
1955-
/// [`is_null`]: #method.is_null-1
1894+
/// # See Also
1895+
/// For the mutable counterpart see [`as_uninit_slice_mut`](pointer::as_uninit_slice_mut).
19561896
#[inline]
19571897
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
19581898
pub const unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit<T>]> {

0 commit comments

Comments
 (0)