Skip to content

Commit b8689d6

Browse files
lolbinarycatlolbinarycat
committed
core::ptr: deduplicate docs for as_ref, addr, and as_uninit_ref
also add INFO.md file explaining the purpuse of the ptr/docs dir.
1 parent 8ce2287 commit b8689d6

File tree

6 files changed

+113
-134
lines changed

6 files changed

+113
-134
lines changed

‎library/core/src/ptr/const_ptr.rs

Lines changed: 13 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -146,28 +146,7 @@ impl<T: ?Sized> *const T {
146146
self as _
147147
}
148148

149-
/// Gets the "address" portion of the pointer.
150-
///
151-
/// This is similar to `self as usize`, except that the [provenance][crate::ptr#provenance] of
152-
/// the pointer is discarded and not [exposed][crate::ptr#exposed-provenance]. This means that
153-
/// casting the returned address back to a pointer yields a [pointer without
154-
/// provenance][without_provenance], which is undefined behavior to dereference. To properly
155-
/// restore the lost information and obtain a dereferenceable pointer, use
156-
/// [`with_addr`][pointer::with_addr] or [`map_addr`][pointer::map_addr].
157-
///
158-
/// If using those APIs is not possible because there is no way to preserve a pointer with the
159-
/// required provenance, then Strict Provenance might not be for you. Use pointer-integer casts
160-
/// or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance]
161-
/// instead. However, note that this makes your code less portable and less amenable to tools
162-
/// that check for compliance with the Rust memory model.
163-
///
164-
/// On most platforms this will produce a value with the same bytes as the original
165-
/// pointer, because all the bytes are dedicated to describing the address.
166-
/// Platforms which need to store additional information in the pointer may
167-
/// perform a change of representation to produce a value containing only the address
168-
/// portion of the pointer. What that means is up to the platform to define.
169-
///
170-
/// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
149+
#[doc = include_str!("./docs/addr.md")]
171150
#[must_use]
172151
#[inline(always)]
173152
#[stable(feature = "strict_provenance", since = "1.84.0")]
@@ -254,23 +233,16 @@ impl<T: ?Sized> *const T {
254233
(self.cast(), metadata(self))
255234
}
256235

257-
/// Returns `None` if the pointer is null, or else returns a shared reference to
258-
/// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`]
259-
/// must be used instead.
260-
///
261-
/// [`as_uninit_ref`]: #method.as_uninit_ref
262-
///
263-
/// # Safety
264-
///
265-
/// When calling this method, you have to ensure that *either* the pointer is null *or*
266-
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
236+
#[doc = include_str!("./docs/as_ref.md")]
267237
///
268-
/// # Panics during const evaluation
269-
///
270-
/// This method will panic during const evaluation if the pointer cannot be
271-
/// determined to be null or not. See [`is_null`] for more information.
238+
/// ```
239+
/// let ptr: *const u8 = &10u8 as *const u8;
272240
///
273-
/// [`is_null`]: #method.is_null
241+
/// unsafe {
242+
/// let val_back = &*ptr;
243+
/// assert_eq!(val_back, &10);
244+
/// }
245+
/// ```
274246
///
275247
/// # Examples
276248
///
@@ -284,20 +256,9 @@ impl<T: ?Sized> *const T {
284256
/// }
285257
/// ```
286258
///
287-
/// # Null-unchecked version
288259
///
289-
/// If you are sure the pointer can never be null and are looking for some kind of
290-
/// `as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can
291-
/// dereference the pointer directly.
292-
///
293-
/// ```
294-
/// let ptr: *const u8 = &10u8 as *const u8;
295-
///
296-
/// unsafe {
297-
/// let val_back = &*ptr;
298-
/// assert_eq!(val_back, &10);
299-
/// }
300-
/// ```
260+
/// [`is_null`]: #method.is_null
261+
/// [`as_uninit_ref`]: #method.as_uninit_ref
301262
#[stable(feature = "ptr_as_ref", since = "1.9.0")]
302263
#[rustc_const_stable(feature = "const_ptr_is_null", since = "1.84.0")]
303264
#[inline]
@@ -338,23 +299,10 @@ impl<T: ?Sized> *const T {
338299
unsafe { &*self }
339300
}
340301

341-
/// Returns `None` if the pointer is null, or else returns a shared reference to
342-
/// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require
343-
/// that the value has to be initialized.
344-
///
345-
/// [`as_ref`]: #method.as_ref
346-
///
347-
/// # Safety
348-
///
349-
/// When calling this method, you have to ensure that *either* the pointer is null *or*
350-
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
351-
///
352-
/// # Panics during const evaluation
353-
///
354-
/// This method will panic during const evaluation if the pointer cannot be
355-
/// determined to be null or not. See [`is_null`] for more information.
302+
#[doc = include_str!("./docs/as_uninit_ref.md")]
356303
///
357304
/// [`is_null`]: #method.is_null
305+
/// [`as_ref`]: #method.as_ref
358306
///
359307
/// # Examples
360308
///

‎library/core/src/ptr/docs/INFO.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
This directory holds method documentation that otherwise
2+
would be duplicated across mutable and immutable pointers.
3+
4+
Note that most of the docs here are not the complete docs
5+
for their corrosponding method. This is for a few reasons:
6+
7+
1. Examples need to be different for mutable/immutable
8+
pointers, in order to actually call the correct method.
9+
2. Link reference definitions are frequently different
10+
between mutable/immutable pointers, in order to link to
11+
the correct method.
12+
For example, `<*const T>::as_ref` links to
13+
`<*const T>::is_null`, while `<*mut T>::as_ref` links to
14+
`<*mut T>::is_null`.
15+
3. Many methods on mutable pointers link to an alternate
16+
version that returns a mutable reference instead of
17+
a shared reference.
18+
19+
Always review the rendered docs manually when making
20+
changes to these files to make sure you're not accidentally
21+
splitting up a section.

‎library/core/src/ptr/docs/addr.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Gets the "address" portion of the pointer.
2+
3+
This is similar to `self as usize`, except that the [provenance][crate::ptr#provenance] of
4+
the pointer is discarded and not [exposed][crate::ptr#exposed-provenance]. This means that
5+
casting the returned address back to a pointer yields a [pointer without
6+
provenance][without_provenance], which is undefined behavior to dereference. To properly
7+
restore the lost information and obtain a dereferenceable pointer, use
8+
[`with_addr`][pointer::with_addr] or [`map_addr`][pointer::map_addr].
9+
10+
If using those APIs is not possible because there is no way to preserve a pointer with the
11+
required provenance, then Strict Provenance might not be for you. Use pointer-integer casts
12+
or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance]
13+
instead. However, note that this makes your code less portable and less amenable to tools
14+
that check for compliance with the Rust memory model.
15+
16+
On most platforms this will produce a value with the same bytes as the original
17+
pointer, because all the bytes are dedicated to describing the address.
18+
Platforms which need to store additional information in the pointer may
19+
perform a change of representation to produce a value containing only the address
20+
portion of the pointer. What that means is up to the platform to define.
21+
22+
This is a [Strict Provenance][crate::ptr#strict-provenance] API.
23+

‎library/core/src/ptr/docs/as_ref.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Returns `None` if the pointer is null, or else returns a shared reference to
2+
the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`]
3+
must be used instead.
4+
5+
# Safety
6+
7+
When calling this method, you have to ensure that *either* the pointer is null *or*
8+
the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
9+
10+
# Panics during const evaluation
11+
12+
This method will panic during const evaluation if the pointer cannot be
13+
determined to be null or not. See [`is_null`] for more information.
14+
15+
# Null-unchecked version
16+
17+
If you are sure the pointer can never be null and are looking for some kind of
18+
`as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can
19+
dereference the pointer directly.

‎library/core/src/ptr/docs/as_uninit_ref.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Returns `None` if the pointer is null, or else returns a shared reference 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+
# Safety
6+
7+
When calling this method, you have to ensure that *either* the pointer is null *or*
8+
the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
9+
Note that because the created reference is to `MaybeUninit<T>`, the
10+
source pointer can point to uninitialized memory.
11+
12+
# Panics during const evaluation
13+
14+
This method will panic during const evaluation if the pointer cannot be
15+
determined to be null or not. See [`is_null`] for more information.
16+

‎library/core/src/ptr/mut_ptr.rs

Lines changed: 21 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -133,28 +133,9 @@ impl<T: ?Sized> *mut T {
133133
self as _
134134
}
135135

136-
/// Gets the "address" portion of the pointer.
137-
///
138-
/// This is similar to `self as usize`, except that the [provenance][crate::ptr#provenance] of
139-
/// the pointer is discarded and not [exposed][crate::ptr#exposed-provenance]. This means that
140-
/// casting the returned address back to a pointer yields a [pointer without
141-
/// provenance][without_provenance_mut], which is undefined behavior to dereference. To properly
142-
/// restore the lost information and obtain a dereferenceable pointer, use
143-
/// [`with_addr`][pointer::with_addr] or [`map_addr`][pointer::map_addr].
144-
///
145-
/// If using those APIs is not possible because there is no way to preserve a pointer with the
146-
/// required provenance, then Strict Provenance might not be for you. Use pointer-integer casts
147-
/// or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance]
148-
/// instead. However, note that this makes your code less portable and less amenable to tools
149-
/// that check for compliance with the Rust memory model.
150-
///
151-
/// On most platforms this will produce a value with the same bytes as the original
152-
/// pointer, because all the bytes are dedicated to describing the address.
153-
/// Platforms which need to store additional information in the pointer may
154-
/// perform a change of representation to produce a value containing only the address
155-
/// portion of the pointer. What that means is up to the platform to define.
136+
#[doc = include_str!("./docs/addr.md")]
156137
///
157-
/// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
138+
/// [without_provenance]: without_provenance_mut
158139
#[must_use]
159140
#[inline(always)]
160141
#[stable(feature = "strict_provenance", since = "1.84.0")]
@@ -241,26 +222,16 @@ impl<T: ?Sized> *mut T {
241222
(self.cast(), super::metadata(self))
242223
}
243224

244-
/// Returns `None` if the pointer is null, or else returns a shared reference to
245-
/// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`]
246-
/// must be used instead.
247-
///
248-
/// For the mutable counterpart see [`as_mut`].
225+
#[doc = include_str!("./docs/as_ref.md")]
249226
///
250-
/// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1
251-
/// [`as_mut`]: #method.as_mut
252-
///
253-
/// # Safety
254-
///
255-
/// When calling this method, you have to ensure that *either* the pointer is null *or*
256-
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
257-
///
258-
/// # Panics during const evaluation
259-
///
260-
/// This method will panic during const evaluation if the pointer cannot be
261-
/// determined to be null or not. See [`is_null`] for more information.
227+
/// ```
228+
/// let ptr: *mut u8 = &mut 10u8 as *mut u8;
262229
///
263-
/// [`is_null`]: #method.is_null-1
230+
/// unsafe {
231+
/// let val_back = &*ptr;
232+
/// println!("We got back the value: {val_back}!");
233+
/// }
234+
/// ```
264235
///
265236
/// # Examples
266237
///
@@ -274,20 +245,14 @@ impl<T: ?Sized> *mut T {
274245
/// }
275246
/// ```
276247
///
277-
/// # Null-unchecked version
278-
///
279-
/// If you are sure the pointer can never be null and are looking for some kind of
280-
/// `as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can
281-
/// dereference the pointer directly.
248+
/// # See Also
282249
///
283-
/// ```
284-
/// let ptr: *mut u8 = &mut 10u8 as *mut u8;
250+
/// For the mutable counterpart see [`as_mut`].
285251
///
286-
/// unsafe {
287-
/// let val_back = &*ptr;
288-
/// println!("We got back the value: {val_back}!");
289-
/// }
290-
/// ```
252+
/// [`is_null`]: #method.is_null-1
253+
/// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1
254+
/// [`as_mut`]: #method.as_mut
255+
291256
#[stable(feature = "ptr_as_ref", since = "1.9.0")]
292257
#[rustc_const_stable(feature = "const_ptr_is_null", since = "1.84.0")]
293258
#[inline]
@@ -330,28 +295,15 @@ impl<T: ?Sized> *mut T {
330295
unsafe { &*self }
331296
}
332297

333-
/// Returns `None` if the pointer is null, or else returns a shared reference to
334-
/// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require
335-
/// that the value has to be initialized.
336-
///
337-
/// For the mutable counterpart see [`as_uninit_mut`].
298+
#[doc = include_str!("./docs/as_uninit_ref.md")]
338299
///
300+
/// [`is_null`]: #method.is_null-1
339301
/// [`as_ref`]: pointer#method.as_ref-1
340-
/// [`as_uninit_mut`]: #method.as_uninit_mut
341-
///
342-
/// # Safety
343-
///
344-
/// When calling this method, you have to ensure that *either* the pointer is null *or*
345-
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
346-
/// Note that because the created reference is to `MaybeUninit<T>`, the
347-
/// source pointer can point to uninitialized memory.
348-
///
349-
/// # Panics during const evaluation
350302
///
351-
/// This method will panic during const evaluation if the pointer cannot be
352-
/// determined to be null or not. See [`is_null`] for more information.
303+
/// # See Also
304+
/// For the mutable counterpart see [`as_uninit_mut`].
353305
///
354-
/// [`is_null`]: #method.is_null-1
306+
/// [`as_uninit_mut`]: #method.as_uninit_mut
355307
///
356308
/// # Examples
357309
///

0 commit comments

Comments
 (0)