@@ -26,6 +26,9 @@ use crate::{assert_unsafe_precondition, fmt, mem};
2626/// requirements, or use the more lenient `Allocator` interface.)
2727#[ stable( feature = "alloc_layout" , since = "1.28.0" ) ]
2828#[ derive( Copy , Clone , Debug , PartialEq , Eq , Hash ) ]
29+ // BEWARE! The implementation of the `layout_of_val` intrinsic is coupled to the
30+ // declared order of these fields. As a reminder, you'll also get a (debug-only)
31+ // ICE if you change their names, though you can easily update that expectation.
2932#[ lang = "alloc_layout" ]
3033pub struct Layout {
3134 // size of the requested block of memory, measured in bytes.
@@ -247,6 +250,30 @@ impl Layout {
247250 ///
248251 /// [trait object]: ../../book/ch17-02-trait-objects.html
249252 /// [extern type]: ../../unstable-book/language-features/extern-types.html
253+ ///
254+ /// # Examples
255+ ///
256+ /// ```
257+ /// #![feature(layout_for_ptr)]
258+ ///
259+ /// use std::alloc::Layout;
260+ /// use std::ptr;
261+ ///
262+ /// let arbitrary = ptr::without_provenance::<[u16; 3]>(123456);
263+ /// assert_eq!(
264+ /// // SAFETY: for a sized pointee, the function is always sound.
265+ /// unsafe { Layout::for_value_raw(arbitrary) },
266+ /// Layout::from_size_align(6, 2).unwrap(),
267+ /// );
268+ ///
269+ /// let slice = ptr::slice_from_raw_parts(arbitrary, 789);
270+ /// assert_eq!(
271+ /// // SAFETY: with a slice pointee, this is sound because the length
272+ /// // is short enough that size in bytes doesn't overflow isize::MAX.
273+ /// unsafe { Layout::for_value_raw(slice) },
274+ /// Layout::from_size_align(6 * 789, 2).unwrap(),
275+ /// );
276+ /// ```
250277 #[ unstable( feature = "layout_for_ptr" , issue = "69835" ) ]
251278 #[ must_use]
252279 #[ inline]
0 commit comments