@@ -146,28 +146,7 @@ impl<T: PointeeSized> *const T {
146
146
self as _
147
147
}
148
148
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" ) ]
171
150
#[ must_use]
172
151
#[ inline( always) ]
173
152
#[ stable( feature = "strict_provenance" , since = "1.84.0" ) ]
@@ -254,23 +233,16 @@ impl<T: PointeeSized> *const T {
254
233
( self . cast ( ) , metadata ( self ) )
255
234
}
256
235
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" ) ]
267
237
///
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;
272
240
///
273
- /// [`is_null`]: #method.is_null
241
+ /// unsafe {
242
+ /// let val_back = &*ptr;
243
+ /// assert_eq!(val_back, &10);
244
+ /// }
245
+ /// ```
274
246
///
275
247
/// # Examples
276
248
///
@@ -284,20 +256,9 @@ impl<T: PointeeSized> *const T {
284
256
/// }
285
257
/// ```
286
258
///
287
- /// # Null-unchecked version
288
259
///
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
301
262
#[ stable( feature = "ptr_as_ref" , since = "1.9.0" ) ]
302
263
#[ rustc_const_stable( feature = "const_ptr_is_null" , since = "1.84.0" ) ]
303
264
#[ inline]
@@ -338,23 +299,10 @@ impl<T: PointeeSized> *const T {
338
299
unsafe { & * self }
339
300
}
340
301
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" ) ]
356
303
///
357
304
/// [`is_null`]: #method.is_null
305
+ /// [`as_ref`]: #method.as_ref
358
306
///
359
307
/// # Examples
360
308
///
0 commit comments