String { vec: Vec::new() }
}
- /// Creates a new empty `String` with a particular capacity.
+ /// Creates a new empty `String` with at least the specified capacity.
///
/// `String`s have an internal buffer to hold their data. The capacity is
/// the length of that buffer, and can be queried with the [`capacity`]
/// method. This method creates an empty `String`, but one with an initial
- /// buffer that can hold `capacity` bytes. This is useful when you may be
- /// appending a bunch of data to the `String`, reducing the number of
+ /// buffer that can hold at least `capacity` bytes. This is useful when you
+ /// may be appending a bunch of data to the `String`, reducing the number of
/// reallocations it needs to do.
///
/// [`capacity`]: String::capacity
self.vec.capacity()
}
- /// Ensures that this `String`'s capacity is at least `additional` bytes
- /// larger than its length.
- ///
- /// The capacity may be increased by more than `additional` bytes if it
- /// chooses, to prevent frequent reallocations.
- ///
- /// If you do not want this "at least" behavior, see the [`reserve_exact`]
- /// method.
+ /// Reserves capacity for at least `additional` bytes more than the
+ /// current length. The allocator may reserve more space to speculatively
+ /// avoid frequent allocations. After calling `reserve`,
+ /// capacity will be greater than or equal to `self.len() + additional`.
+ /// Does nothing if capacity is already sufficient.
///
/// # Panics
///
/// Panics if the new capacity overflows [`usize`].
///
- /// [`reserve_exact`]: String::reserve_exact
- ///
/// # Examples
///
/// Basic usage:
/// s.push('a');
/// s.push('b');
///
- /// // s now has a length of 2 and a capacity of 10
+ /// // s now has a length of 2 and a capacity of at least 10
+ /// let capacity = s.capacity();
/// assert_eq!(2, s.len());
- /// assert_eq!(10, s.capacity());
+ /// assert!(capacity >= 10);
///
- /// // Since we already have an extra 8 capacity, calling this...
+ /// // Since we already have at least an extra 8 capacity, calling this...
/// s.reserve(8);
///
/// // ... doesn't actually increase.
- /// assert_eq!(10, s.capacity());
+ /// assert_eq!(capacity, s.capacity());
/// ```
#[cfg(not(no_global_oom_handling))]
#[inline]
self.vec.reserve(additional)
}
- /// Ensures that this `String`'s capacity is `additional` bytes
- /// larger than its length.
- ///
- /// Consider using the [`reserve`] method unless you absolutely know
- /// better than the allocator.
+ /// Reserves the minimum capacity for at least `additional` bytes more than
+ /// the current length. Unlike [`reserve`], this will not
+ /// deliberately over-allocate to speculatively avoid frequent allocations.
+ /// After calling `reserve_exact`, capacity will be greater than or equal to
+ /// `self.len() + additional`. Does nothing if the capacity is already
+ /// sufficient.
///
/// [`reserve`]: String::reserve
///
/// # Panics
///
- /// Panics if the new capacity overflows `usize`.
+ /// Panics if the new capacity overflows [`usize`].
///
/// # Examples
///
/// s.push('a');
/// s.push('b');
///
- /// // s now has a length of 2 and a capacity of 10
+ /// // s now has a length of 2 and a capacity of at least 10
+ /// let capacity = s.capacity();
/// assert_eq!(2, s.len());
- /// assert_eq!(10, s.capacity());
+ /// assert!(capacity >= 10);
///
- /// // Since we already have an extra 8 capacity, calling this...
+ /// // Since we already have at least an extra 8 capacity, calling this...
/// s.reserve_exact(8);
///
/// // ... doesn't actually increase.
- /// assert_eq!(10, s.capacity());
+ /// assert_eq!(capacity, s.capacity());
/// ```
#[cfg(not(no_global_oom_handling))]
#[inline]
self.vec.reserve_exact(additional)
}
- /// Tries to reserve capacity for at least `additional` more elements to be inserted
- /// in the given `String`. The collection may reserve more space to avoid
- /// frequent reallocations. After calling `reserve`, capacity will be
- /// greater than or equal to `self.len() + additional`. Does nothing if
- /// capacity is already sufficient.
+ /// Tries to reserve capacity for at least `additional` bytes more than the
+ /// current length. The allocator may reserve more space to speculatively
+ /// avoid frequent allocations. After calling `try_reserve`, capacity will be
+ /// greater than or equal to `self.len() + additional` if it returns
+ /// `Ok(())`. Does nothing if capacity is already sufficient.
///
/// # Errors
///
self.vec.try_reserve(additional)
}
- /// Tries to reserve the minimum capacity for exactly `additional` more elements to
- /// be inserted in the given `String`. After calling `try_reserve_exact`,
- /// capacity will be greater than or equal to `self.len() + additional`.
+ /// Tries to reserve the minimum capacity for at least `additional` bytes
+ /// more than the current length. Unlike [`try_reserve`], this will not
+ /// deliberately over-allocate to speculatively avoid frequent allocations.
+ /// After calling `try_reserve_exact`, capacity will be greater than or
+ /// equal to `self.len() + additional` if it returns `Ok(())`.
/// Does nothing if the capacity is already sufficient.
///
/// Note that the allocator may give the collection more space than it