@@ -66,7 +66,7 @@ use core::ptr::{self, NonNull};
66
66
use core:: slice:: { self , SliceIndex } ;
67
67
use core:: { fmt, intrinsics} ;
68
68
69
- #[ unstable ( feature = "extract_if" , reason = "recently added" , issue = "43244 ") ]
69
+ #[ stable ( feature = "extract_if" , since = "CURRENT_RUSTC_VERSION " ) ]
70
70
pub use self :: extract_if:: ExtractIf ;
71
71
use crate :: alloc:: { Allocator , Global } ;
72
72
use crate :: borrow:: { Cow , ToOwned } ;
@@ -355,11 +355,20 @@ mod spec_extend;
355
355
/// and it may prove desirable to use a non-constant growth factor. Whatever
356
356
/// strategy is used will of course guarantee *O*(1) amortized [`push`].
357
357
///
358
- /// `vec![x; n]`, `vec![a, b, c, d]`, and
359
- /// [`Vec::with_capacity(n)`][`Vec::with_capacity`], will all produce a `Vec`
360
- /// with at least the requested capacity. If <code>[len] == [capacity]</code>,
361
- /// (as is the case for the [`vec!`] macro), then a `Vec<T>` can be converted to
362
- /// and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements.
358
+ /// It is guaranteed, in order to respect the intentions of the programmer, that
359
+ /// all of `vec![e_1, e_2, ..., e_n]`, `vec![x; n]`, and [`Vec::with_capacity(n)`] produce a `Vec`
360
+ /// that requests an allocation of the exact size needed for precisely `n` elements from the allocator,
361
+ /// and no other size (such as, for example: a size rounded up to the nearest power of 2).
362
+ /// The allocator will return an allocation that is at least as large as requested, but it may be larger.
363
+ ///
364
+ /// It is guaranteed that the [`Vec::capacity`] method returns a value that is at least the requested capacity
365
+ /// and not more than the allocated capacity.
366
+ ///
367
+ /// The method [`Vec::shrink_to_fit`] will attempt to discard excess capacity an allocator has given to a `Vec`.
368
+ /// If <code>[len] == [capacity]</code>, then a `Vec<T>` can be converted
369
+ /// to and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements.
370
+ /// `Vec` exploits this fact as much as reasonable when implementing common conversions
371
+ /// such as [`into_boxed_slice`].
363
372
///
364
373
/// `Vec` will not specifically overwrite any data that is removed from it,
365
374
/// but also won't specifically preserve it. Its uninitialized memory is
@@ -383,14 +392,17 @@ mod spec_extend;
383
392
/// [`shrink_to`]: Vec::shrink_to
384
393
/// [capacity]: Vec::capacity
385
394
/// [`capacity`]: Vec::capacity
395
+ /// [`Vec::capacity`]: Vec::capacity
386
396
/// [mem::size_of::\<T>]: core::mem::size_of
387
397
/// [len]: Vec::len
388
398
/// [`len`]: Vec::len
389
399
/// [`push`]: Vec::push
390
400
/// [`insert`]: Vec::insert
391
401
/// [`reserve`]: Vec::reserve
402
+ /// [`Vec::with_capacity(n)`]: Vec::with_capacity
392
403
/// [`MaybeUninit`]: core::mem::MaybeUninit
393
404
/// [owned slice]: Box
405
+ /// [`into_boxed_slice`]: Vec::into_boxed_slice
394
406
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
395
407
#[ cfg_attr( not( test) , rustc_diagnostic_item = "Vec" ) ]
396
408
#[ rustc_insignificant_dtor]
@@ -3684,7 +3696,6 @@ impl<T, A: Allocator> Vec<T, A> {
3684
3696
/// Splitting an array into evens and odds, reusing the original allocation:
3685
3697
///
3686
3698
/// ```
3687
- /// #![feature(extract_if)]
3688
3699
/// let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];
3689
3700
///
3690
3701
/// let evens = numbers.extract_if(.., |x| *x % 2 == 0).collect::<Vec<_>>();
@@ -3697,13 +3708,12 @@ impl<T, A: Allocator> Vec<T, A> {
3697
3708
/// Using the range argument to only process a part of the vector:
3698
3709
///
3699
3710
/// ```
3700
- /// #![feature(extract_if)]
3701
3711
/// let mut items = vec![0, 0, 0, 0, 0, 0, 0, 1, 2, 1, 2, 1, 2];
3702
3712
/// let ones = items.extract_if(7.., |x| *x == 1).collect::<Vec<_>>();
3703
3713
/// assert_eq!(items, vec![0, 0, 0, 0, 0, 0, 0, 2, 2, 2]);
3704
3714
/// assert_eq!(ones.len(), 3);
3705
3715
/// ```
3706
- #[ unstable ( feature = "extract_if" , reason = "recently added" , issue = "43244 ") ]
3716
+ #[ stable ( feature = "extract_if" , since = "CURRENT_RUSTC_VERSION " ) ]
3707
3717
pub fn extract_if < F , R > ( & mut self , range : R , filter : F ) -> ExtractIf < ' _ , T , F , A >
3708
3718
where
3709
3719
F : FnMut ( & mut T ) -> bool ,
0 commit comments