@@ -189,6 +189,7 @@ impl<T> Box<T> {
189
189
#[ cfg( not( no_global_oom_handling) ) ]
190
190
#[ inline( always) ]
191
191
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
192
+ #[ must_use]
192
193
pub fn new ( x : T ) -> Self {
193
194
box x
194
195
}
@@ -213,6 +214,7 @@ impl<T> Box<T> {
213
214
/// ```
214
215
#[ cfg( not( no_global_oom_handling) ) ]
215
216
#[ unstable( feature = "new_uninit" , issue = "63291" ) ]
217
+ #[ must_use]
216
218
#[ inline]
217
219
pub fn new_uninit ( ) -> Box < mem:: MaybeUninit < T > > {
218
220
Self :: new_uninit_in ( Global )
@@ -239,6 +241,7 @@ impl<T> Box<T> {
239
241
#[ cfg( not( no_global_oom_handling) ) ]
240
242
#[ inline]
241
243
#[ unstable( feature = "new_uninit" , issue = "63291" ) ]
244
+ #[ must_use]
242
245
pub fn new_zeroed ( ) -> Box < mem:: MaybeUninit < T > > {
243
246
Self :: new_zeroed_in ( Global )
244
247
}
@@ -247,6 +250,7 @@ impl<T> Box<T> {
247
250
/// `x` will be pinned in memory and unable to be moved.
248
251
#[ cfg( not( no_global_oom_handling) ) ]
249
252
#[ stable( feature = "pin" , since = "1.33.0" ) ]
253
+ #[ must_use]
250
254
#[ inline( always) ]
251
255
pub fn pin ( x : T ) -> Pin < Box < T > > {
252
256
( box x) . into ( )
@@ -341,6 +345,7 @@ impl<T, A: Allocator> Box<T, A> {
341
345
/// ```
342
346
#[ cfg( not( no_global_oom_handling) ) ]
343
347
#[ unstable( feature = "allocator_api" , issue = "32838" ) ]
348
+ #[ must_use]
344
349
#[ inline]
345
350
pub fn new_in ( x : T , alloc : A ) -> Self {
346
351
let mut boxed = Self :: new_uninit_in ( alloc) ;
@@ -397,6 +402,7 @@ impl<T, A: Allocator> Box<T, A> {
397
402
/// ```
398
403
#[ unstable( feature = "allocator_api" , issue = "32838" ) ]
399
404
#[ cfg( not( no_global_oom_handling) ) ]
405
+ #[ must_use]
400
406
// #[unstable(feature = "new_uninit", issue = "63291")]
401
407
pub fn new_uninit_in ( alloc : A ) -> Box < mem:: MaybeUninit < T > , A > {
402
408
let layout = Layout :: new :: < mem:: MaybeUninit < T > > ( ) ;
@@ -461,6 +467,7 @@ impl<T, A: Allocator> Box<T, A> {
461
467
#[ unstable( feature = "allocator_api" , issue = "32838" ) ]
462
468
#[ cfg( not( no_global_oom_handling) ) ]
463
469
// #[unstable(feature = "new_uninit", issue = "63291")]
470
+ #[ must_use]
464
471
pub fn new_zeroed_in ( alloc : A ) -> Box < mem:: MaybeUninit < T > , A > {
465
472
let layout = Layout :: new :: < mem:: MaybeUninit < T > > ( ) ;
466
473
// NOTE: Prefer match over unwrap_or_else since closure sometimes not inlineable.
@@ -505,6 +512,7 @@ impl<T, A: Allocator> Box<T, A> {
505
512
/// `x` will be pinned in memory and unable to be moved.
506
513
#[ cfg( not( no_global_oom_handling) ) ]
507
514
#[ unstable( feature = "allocator_api" , issue = "32838" ) ]
515
+ #[ must_use]
508
516
#[ inline( always) ]
509
517
pub fn pin_in ( x : T , alloc : A ) -> Pin < Self >
510
518
where
@@ -563,6 +571,7 @@ impl<T> Box<[T]> {
563
571
/// ```
564
572
#[ cfg( not( no_global_oom_handling) ) ]
565
573
#[ unstable( feature = "new_uninit" , issue = "63291" ) ]
574
+ #[ must_use]
566
575
pub fn new_uninit_slice ( len : usize ) -> Box < [ mem:: MaybeUninit < T > ] > {
567
576
unsafe { RawVec :: with_capacity ( len) . into_box ( len) }
568
577
}
@@ -587,6 +596,7 @@ impl<T> Box<[T]> {
587
596
/// [zeroed]: mem::MaybeUninit::zeroed
588
597
#[ cfg( not( no_global_oom_handling) ) ]
589
598
#[ unstable( feature = "new_uninit" , issue = "63291" ) ]
599
+ #[ must_use]
590
600
pub fn new_zeroed_slice ( len : usize ) -> Box < [ mem:: MaybeUninit < T > ] > {
591
601
unsafe { RawVec :: with_capacity_zeroed ( len) . into_box ( len) }
592
602
}
@@ -683,6 +693,7 @@ impl<T, A: Allocator> Box<[T], A> {
683
693
#[ cfg( not( no_global_oom_handling) ) ]
684
694
#[ unstable( feature = "allocator_api" , issue = "32838" ) ]
685
695
// #[unstable(feature = "new_uninit", issue = "63291")]
696
+ #[ must_use]
686
697
pub fn new_uninit_slice_in ( len : usize , alloc : A ) -> Box < [ mem:: MaybeUninit < T > ] , A > {
687
698
unsafe { RawVec :: with_capacity_in ( len, alloc) . into_box ( len) }
688
699
}
@@ -710,6 +721,7 @@ impl<T, A: Allocator> Box<[T], A> {
710
721
#[ cfg( not( no_global_oom_handling) ) ]
711
722
#[ unstable( feature = "allocator_api" , issue = "32838" ) ]
712
723
// #[unstable(feature = "new_uninit", issue = "63291")]
724
+ #[ must_use]
713
725
pub fn new_zeroed_slice_in ( len : usize , alloc : A ) -> Box < [ mem:: MaybeUninit < T > ] , A > {
714
726
unsafe { RawVec :: with_capacity_zeroed_in ( len, alloc) . into_box ( len) }
715
727
}
@@ -1088,6 +1100,7 @@ unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Box<T, A> {
1088
1100
}
1089
1101
}
1090
1102
1103
+ #[ cfg( not( no_global_oom_handling) ) ]
1091
1104
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1092
1105
impl < T : Default > Default for Box < T > {
1093
1106
/// Creates a `Box<T>`, with the `Default` value for T.
@@ -1278,6 +1291,7 @@ impl<T> From<T> for Box<T> {
1278
1291
/// from the stack into it.
1279
1292
///
1280
1293
/// # Examples
1294
+ ///
1281
1295
/// ```rust
1282
1296
/// let x = 5;
1283
1297
/// let boxed = Box::new(5);
@@ -1331,6 +1345,12 @@ impl<T: Copy> From<&[T]> for Box<[T]> {
1331
1345
#[ cfg( not( no_global_oom_handling) ) ]
1332
1346
#[ stable( feature = "box_from_cow" , since = "1.45.0" ) ]
1333
1347
impl < T : Copy > From < Cow < ' _ , [ T ] > > for Box < [ T ] > {
1348
+ /// Converts a `Cow<'_, [T]>` into a `Box<[T]>`
1349
+ ///
1350
+ /// When `cow` is the `Cow::Borrowed` variant, this
1351
+ /// conversion allocates on the heap and copies the
1352
+ /// underlying slice. Otherwise, it will try to reuse the owned
1353
+ /// `Vec`'s allocation.
1334
1354
#[ inline]
1335
1355
fn from ( cow : Cow < ' _ , [ T ] > ) -> Box < [ T ] > {
1336
1356
match cow {
@@ -1349,6 +1369,7 @@ impl From<&str> for Box<str> {
1349
1369
/// and performs a copy of `s`.
1350
1370
///
1351
1371
/// # Examples
1372
+ ///
1352
1373
/// ```rust
1353
1374
/// let boxed: Box<str> = Box::from("hello");
1354
1375
/// println!("{}", boxed);
@@ -1362,6 +1383,29 @@ impl From<&str> for Box<str> {
1362
1383
#[ cfg( not( no_global_oom_handling) ) ]
1363
1384
#[ stable( feature = "box_from_cow" , since = "1.45.0" ) ]
1364
1385
impl From < Cow < ' _ , str > > for Box < str > {
1386
+ /// Converts a `Cow<'_, str>` into a `Box<str>`
1387
+ ///
1388
+ /// When `cow` is the `Cow::Borrowed` variant, this
1389
+ /// conversion allocates on the heap and copies the
1390
+ /// underlying `str`. Otherwise, it will try to reuse the owned
1391
+ /// `String`'s allocation.
1392
+ ///
1393
+ /// # Examples
1394
+ ///
1395
+ /// ```rust
1396
+ /// use std::borrow::Cow;
1397
+ ///
1398
+ /// let unboxed = Cow::Borrowed("hello");
1399
+ /// let boxed: Box<str> = Box::from(unboxed);
1400
+ /// println!("{}", boxed);
1401
+ /// ```
1402
+ ///
1403
+ /// ```rust
1404
+ /// # use std::borrow::Cow;
1405
+ /// let unboxed = Cow::Owned("hello".to_string());
1406
+ /// let boxed: Box<str> = Box::from(unboxed);
1407
+ /// println!("{}", boxed);
1408
+ /// ```
1365
1409
#[ inline]
1366
1410
fn from ( cow : Cow < ' _ , str > ) -> Box < str > {
1367
1411
match cow {
@@ -1396,13 +1440,15 @@ impl<A: Allocator> From<Box<str, A>> for Box<[u8], A> {
1396
1440
}
1397
1441
}
1398
1442
1443
+ #[ cfg( not( no_global_oom_handling) ) ]
1399
1444
#[ stable( feature = "box_from_array" , since = "1.45.0" ) ]
1400
1445
impl < T , const N : usize > From < [ T ; N ] > for Box < [ T ] > {
1401
1446
/// Converts a `[T; N]` into a `Box<[T]>`
1402
1447
///
1403
1448
/// This conversion moves the array to newly heap-allocated memory.
1404
1449
///
1405
1450
/// # Examples
1451
+ ///
1406
1452
/// ```rust
1407
1453
/// let boxed: Box<[u8]> = Box::from([4, 2]);
1408
1454
/// println!("{:?}", boxed);
@@ -1416,6 +1462,15 @@ impl<T, const N: usize> From<[T; N]> for Box<[T]> {
1416
1462
impl < T , const N : usize > TryFrom < Box < [ T ] > > for Box < [ T ; N ] > {
1417
1463
type Error = Box < [ T ] > ;
1418
1464
1465
+ /// Attempts to convert a `Box<[T]>` into a `Box<[T; N]>`.
1466
+ ///
1467
+ /// The conversion occurs in-place and does not require a
1468
+ /// new memory allocation.
1469
+ ///
1470
+ /// # Errors
1471
+ ///
1472
+ /// Returns the old `Box<[T]>` in the `Err` variant if
1473
+ /// `boxed_slice.len()` does not equal `N`.
1419
1474
fn try_from ( boxed_slice : Box < [ T ] > ) -> Result < Self , Self :: Error > {
1420
1475
if boxed_slice. len ( ) == N {
1421
1476
Ok ( unsafe { Box :: from_raw ( Box :: into_raw ( boxed_slice) as * mut [ T ; N ] ) } )
0 commit comments