|
66 | 66 |
|
67 | 67 | #![stable(feature = "rust1", since = "1.0.0")]
|
68 | 68 |
|
69 |
| -use core::cmp::Ordering; |
| 69 | +use core::cmp::{self, Ordering}; |
70 | 70 | use core::fmt;
|
71 | 71 | use core::hash::{self, Hash};
|
72 | 72 | use core::intrinsics::{arith_offset, assume};
|
@@ -334,9 +334,10 @@ impl<T> Vec<T> {
|
334 | 334 | /// The vector will be able to hold exactly `capacity` elements without
|
335 | 335 | /// reallocating. If `capacity` is 0, the vector will not allocate.
|
336 | 336 | ///
|
337 |
| - /// It is important to note that this function does not specify the *length* |
338 |
| - /// of the returned vector, but only the *capacity*. For an explanation of |
339 |
| - /// the difference between length and capacity, see *[Capacity and reallocation]*. |
| 337 | + /// It is important to note that although the returned vector has the |
| 338 | + /// *capacity* specified, the vector will have a zero *length*. For an |
| 339 | + /// explanation of the difference between length and capacity, see |
| 340 | + /// *[Capacity and reallocation]*. |
340 | 341 | ///
|
341 | 342 | /// [Capacity and reallocation]: #capacity-and-reallocation
|
342 | 343 | ///
|
@@ -586,6 +587,31 @@ impl<T> Vec<T> {
|
586 | 587 | self.buf.shrink_to_fit(self.len);
|
587 | 588 | }
|
588 | 589 |
|
| 590 | + /// Shrinks the capacity of the vector with a lower bound. |
| 591 | + /// |
| 592 | + /// The capacity will remain at least as large as both the length |
| 593 | + /// and the supplied value. |
| 594 | + /// |
| 595 | + /// Panics if the current capacity is smaller than the supplied |
| 596 | + /// minimum capacity. |
| 597 | + /// |
| 598 | + /// # Examples |
| 599 | + /// |
| 600 | + /// ``` |
| 601 | + /// #![feature(shrink_to)] |
| 602 | + /// let mut vec = Vec::with_capacity(10); |
| 603 | + /// vec.extend([1, 2, 3].iter().cloned()); |
| 604 | + /// assert_eq!(vec.capacity(), 10); |
| 605 | + /// vec.shrink_to(4); |
| 606 | + /// assert!(vec.capacity() >= 4); |
| 607 | + /// vec.shrink_to(0); |
| 608 | + /// assert!(vec.capacity() >= 3); |
| 609 | + /// ``` |
| 610 | + #[unstable(feature = "shrink_to", reason = "new API", issue="0")] |
| 611 | + pub fn shrink_to(&mut self, min_capacity: usize) { |
| 612 | + self.buf.shrink_to_fit(cmp::max(self.len, min_capacity)); |
| 613 | + } |
| 614 | + |
589 | 615 | /// Converts the vector into [`Box<[T]>`][owned slice].
|
590 | 616 | ///
|
591 | 617 | /// Note that this will drop any excess capacity.
|
|
0 commit comments