@@ -284,8 +284,13 @@ impl<T> Box<T> {
284284 Self :: new_zeroed_in ( Global )
285285 }
286286
287- /// Constructs a new `Pin<Box<T>>`. If `T` does not implement `Unpin`, then
287+ /// Constructs a new `Pin<Box<T>>`. If `T` does not implement [ `Unpin`] , then
288288/// `x` will be pinned in memory and unable to be moved.
289+ ///
290+ /// Constructing and pinning of the `Box` can also be done in two steps: `Box::pin(x)`
291+ /// does the same as <code>[Box::into_pin]\([Box::new]\(x))</code>. Consider using
292+ /// [`into_pin`](Box::into_pin) if you already have a `Box<T>`, or if you want to
293+ /// construct a (pinned) `Box` in a different way than with [`Box::new`].
289294#[ cfg( not( no_global_oom_handling) ) ]
290295 #[ stable( feature = "pin" , since = "1.33.0" ) ]
291296 #[ must_use]
@@ -573,8 +578,13 @@ impl<T, A: Allocator> Box<T, A> {
573578 unsafe { Ok ( Box :: from_raw_in ( ptr. as_ptr ( ) , alloc) ) }
574579 }
575580
576- /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement `Unpin`, then
581+ /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [ `Unpin`] , then
577582/// `x` will be pinned in memory and unable to be moved.
583+ ///
584+ /// Constructing and pinning of the `Box` can also be done in two steps: `Box::pin_in(x, alloc)`
585+ /// does the same as <code>[Box::into_pin]\([Box::new_in]\(x, alloc))</code>. Consider using
586+ /// [`into_pin`](Box::into_pin) if you already have a `Box<T, A>`, or if you want to
587+ /// construct a (pinned) `Box` in a different way than with [`Box::new_in`].
578588#[ cfg( not( no_global_oom_handling) ) ]
579589 #[ unstable( feature = "allocator_api" , issue = "32838" ) ]
580590 #[ rustc_const_unstable( feature = "const_box" , issue = "92521" ) ]
@@ -1190,12 +1200,18 @@ impl<T: ?Sized, A: Allocator> Box<T, A> {
11901200 unsafe { & mut * mem:: ManuallyDrop :: new ( b) . 0 . as_ptr ( ) }
11911201 }
11921202
1193- /// Converts a `Box<T>` into a `Pin<Box<T>>`
1203+ /// Converts a `Box<T>` into a `Pin<Box<T>>`. If `T` does not implement [`Unpin`], then
1204+ /// `*boxed` will be pinned in memory and unable to be moved.
11941205///
11951206/// This conversion does not allocate on the heap and happens in place.
11961207///
11971208/// This is also available via [`From`].
11981209///
1210+ /// Constructing and pinning a `Box` with <code>Box::into_pin([Box::new]\(x))</code>
1211+ /// can also be written more concisely using <code>[Box::pin]\(x)</code>.
1212+ /// This `into_pin` method is useful if you already have a `Box<T>`, or you are
1213+ /// constructing a (pinned) `Box` in a different way than with [`Box::new`].
1214+ ///
11991215/// # Notes
12001216///
12011217/// It's not recommended that crates add an impl like `From<Box<T>> for Pin<T>`,
@@ -1458,9 +1474,17 @@ impl<T: ?Sized, A: Allocator> const From<Box<T, A>> for Pin<Box<T, A>>
14581474where
14591475 A : ' static ,
14601476{
1461- /// Converts a `Box<T>` into a `Pin<Box<T>>`
1477+ /// Converts a `Box<T>` into a `Pin<Box<T>>`. If `T` does not implement [`Unpin`], then
1478+ /// `*boxed` will be pinned in memory and unable to be moved.
14621479///
14631480/// This conversion does not allocate on the heap and happens in place.
1481+ ///
1482+ /// This is also available via [`Box::into_pin`].
1483+ ///
1484+ /// Constructing and pinning a `Box` with <code><Pin<Box\<T>>>::from([Box::new]\(x))</code>
1485+ /// can also be written more concisely using <code>[Box::pin]\(x)</code>.
1486+ /// This `From` implementation is useful if you already have a `Box<T>`, or you are
1487+ /// constructing a (pinned) `Box` in a different way than with [`Box::new`].
14641488fn from ( boxed : Box < T , A > ) -> Self {
14651489 Box :: into_pin ( boxed)
14661490 }
0 commit comments