bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Fix documentation for with_capacity and reserve families of methods

Browse source 
Documentation for the following methods

    with_capacity
    with_capacity_in
    with_capacity_and_hasher
    reserve
    reserve_exact
    try_reserve
    try_reserve_exact

was inconsistent and often not entirely correct where they existed on the following types

    Vec
    VecDeque
    String
    OsString
    PathBuf
    BinaryHeap
    HashSet
    HashMap
    BufWriter
    LineWriter

since the allocator is allowed to allocate more than the requested capacity in all such cases, and will frequently "allocate" much more in the case of zero-sized types (I also checked BufReader, but there the docs appear to be accurate as it appears to actually allocate the exact capacity).

Some effort was made to make the documentation more consistent between types as well.

Fix with_capacity* methods for Vec

Fix *reserve*  methods for Vec

Fix docs for *reserve* methods of VecDeque

Fix docs for String::with_capacity

Fix docs for *reserve* methods of String

Fix docs for OsString::with_capacity

Fix docs for *reserve* methods on OsString

Fix docs for with_capacity* methods on HashSet

Fix docs for *reserve methods of HashSet

Fix docs for with_capacity* methods of HashMap

Fix docs for *reserve methods on HashMap

Fix expect messages about OOM in doctests

Fix docs for BinaryHeap::with_capacity

Fix docs for *reserve* methods of BinaryHeap

Fix typos

Fix docs for with_capacity on BufWriter and LineWriter

Fix consistent use of `hasher` between `HashMap` and `HashSet`

Fix warning in doc test

Add test for capacity of vec with ZST

Fix doc test error
This commit is contained in:
jmaargh 2022-04-09 16:42:26 +01:00
parent 68d0b29098
commit 95dc353006
10 changed files with 191 additions and 130 deletions
Download patch file Download diff file Expand all files Collapse all files

85
library/alloc/src/vec/mod.rs
View file

@ -425,17 +425,25 @@ impl<T> Vec<T> {
Vec { buf: RawVec::NEW, len: 0 }
}
/// Constructs a new, empty `Vec<T>` with the specified capacity.
/// Constructs a new, empty `Vec<T>` with at least the specified capacity.
///
/// The vector will be able to hold exactly `capacity` elements without
/// reallocating. If `capacity` is 0, the vector will not allocate.
/// The vector will be able to hold at least `capacity` elements without
/// reallocating. This method is allowed to allocate for more elements than
/// `capacity`. If `capacity` is 0, the vector will not allocate.
///
/// It is important to note that although the returned vector has the
/// *capacity* specified, the vector will have a zero *length*. For an
/// explanation of the difference between length and capacity, see
/// minimum *capacity* specified, the vector will have a zero *length*. For
/// an explanation of the difference between length and capacity, see
/// *[Capacity and reallocation]*.
///
/// If it is imporant to know the exact allocated capacity of a `Vec`,
/// always use the [`capacity`] method after construction.
///
/// For `Vec<T>` where `T` is a zero-sized type, there will be no allocation
/// and the capacity will always be `usize::MAX`.
///
/// [Capacity and reallocation]: #capacity-and-reallocation
/// [`capacity`]: Vec::capacity
///
/// # Panics
///
@ -448,19 +456,24 @@ impl<T> Vec<T> {
///
/// // The vector contains no items, even though it has capacity for more
/// assert_eq!(vec.len(), 0);
/// assert_eq!(vec.capacity(), 10);
/// assert!(vec.capacity() >= 10);
///
/// // These are all done without reallocating...
/// for i in 0..10 {
/// vec.push(i);
/// }
/// assert_eq!(vec.len(), 10);
/// assert_eq!(vec.capacity(), 10);
/// assert!(vec.capacity() >= 10);
///
/// // ...but this may make the vector reallocate
/// vec.push(11);
/// assert_eq!(vec.len(), 11);
/// assert!(vec.capacity() >= 11);
///
/// // A vector of a zero-sized type will always over-allocate, since no
/// // allocation is necessary
/// let vec_units = Vec::<()>::with_capacity(10);
/// assert_eq!(vec_units.capacity(), usize::MAX);
/// ```
#[cfg(not(no_global_oom_handling))]
#[inline]
@ -566,18 +579,26 @@ impl<T, A: Allocator> Vec<T, A> {
Vec { buf: RawVec::new_in(alloc), len: 0 }
}
/// Constructs a new, empty `Vec<T, A>` with the specified capacity with the provided
/// allocator.
/// Constructs a new, empty `Vec<T, A>` with at least the specified capacity
/// with the provided allocator.
///
/// The vector will be able to hold exactly `capacity` elements without
/// reallocating. If `capacity` is 0, the vector will not allocate.
/// The vector will be able to hold at least `capacity` elements without
/// reallocating. This method is allowed to allocate for more elements than
/// `capacity`. If `capacity` is 0, the vector will not allocate.
///
/// It is important to note that although the returned vector has the
/// *capacity* specified, the vector will have a zero *length*. For an
/// explanation of the difference between length and capacity, see
/// minimum *capacity* specified, the vector will have a zero *length*. For
/// an explanation of the difference between length and capacity, see
/// *[Capacity and reallocation]*.
///
/// If it is imporant to know the exact allocated capacity of a `Vec`,
/// always use the [`capacity`] method after construction.
///
/// For `Vec<T, A>` where `T` is a zero-sized type, there will be no allocation
/// and the capacity will always be `usize::MAX`.
///
/// [Capacity and reallocation]: #capacity-and-reallocation
/// [`capacity`]: Vec::capacity
///
/// # Panics
///
@ -607,6 +628,11 @@ impl<T, A: Allocator> Vec<T, A> {
/// vec.push(11);
/// assert_eq!(vec.len(), 11);
/// assert!(vec.capacity() >= 11);
///
/// // A vector of a zero-sized type will always over-allocate, since no
/// // allocation is necessary
/// let vec_units = Vec::<(), System>::with_capacity_in(10, System);
/// assert_eq!(vec_units.capacity(), usize::MAX);
/// ```
#[cfg(not(no_global_oom_handling))]
#[inline]
@ -793,10 +819,10 @@ impl<T, A: Allocator> Vec<T, A> {
}
/// Reserves capacity for at least `additional` more elements to be inserted
/// in the given `Vec<T>`. 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.
/// in the given `Vec<T>`. The collection may reserve more space to
/// speculatively avoid frequent reallocations. After calling `reserve`,
/// capacity will be greater than or equal to `self.len() + additional`.
/// Does nothing if capacity is already sufficient.
///
/// # Panics
///
@ -815,10 +841,12 @@ impl<T, A: Allocator> Vec<T, A> {
self.buf.reserve(self.len, additional);
}
/// Reserves the minimum capacity for exactly `additional` more elements to
/// be inserted in the given `Vec<T>`. After calling `reserve_exact`,
/// capacity will be greater than or equal to `self.len() + additional`.
/// Does nothing if the capacity is already sufficient.
/// Reserves the minimum capacity for at least `additional` more elements to
/// be inserted in the given `Vec<T>`. 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.
///
/// Note that the allocator may give the collection more space than it
/// requests. Therefore, capacity can not be relied upon to be precisely
@ -844,10 +872,10 @@ impl<T, A: Allocator> Vec<T, A> {
}
/// Tries to reserve capacity for at least `additional` more elements to be inserted
/// in the given `Vec<T>`. The collection may reserve more space to avoid
/// in the given `Vec<T>`. The collection may reserve more space to speculatively avoid
/// frequent reallocations. After calling `try_reserve`, capacity will be
/// greater than or equal to `self.len() + additional`. Does nothing if
/// capacity is already sufficient.
/// greater than or equal to `self.len() + additional` if it returns
/// `Ok(())`. Does nothing if capacity is already sufficient.
///
/// # Errors
///
@ -879,10 +907,11 @@ impl<T, A: Allocator> Vec<T, A> {
self.buf.try_reserve(self.len, additional)
}
/// Tries to reserve the minimum capacity for exactly `additional`
/// elements to be inserted in the given `Vec<T>`. After calling
/// `try_reserve_exact`, capacity will be greater than or equal to
/// `self.len() + additional` if it returns `Ok(())`.
/// Tries to reserve the minimum capacity for at least `additional`
/// elements to be inserted in the given `Vec<T>`. 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