/// item's ordering relative to any other item, as determined by the [`Ord`]
/// trait, changes while it is in the heap. This is normally only possible
/// through [`Cell`], [`RefCell`], global state, I/O, or unsafe code. The
-/// behavior resulting from such a logic error is not specified (it
-/// could include panics, incorrect results, aborts, memory leaks, or
-/// non-termination) but will not be undefined behavior.
+/// behavior resulting from such a logic error is not specified, but will
+/// be encapsulated to the `BinaryHeap` that observed the logic error and not
+/// result in undefined behavior. This could include panics, incorrect results,
+/// aborts, memory leaks, and non-termination.
///
/// # Examples
///
BinaryHeap { data: vec![] }
}
- /// Creates an empty `BinaryHeap` with a specific capacity.
- /// This preallocates enough memory for `capacity` elements,
- /// so that the `BinaryHeap` does not have to be reallocated
- /// until it contains at least that many values.
+ /// Creates an empty `BinaryHeap` with at least the specified capacity.
+ ///
+ /// The binary heap 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 binary heap will not allocate.
///
/// # Examples
///
self.data.capacity()
}
- /// Reserves the minimum capacity for exactly `additional` more elements to be inserted in the
- /// given `BinaryHeap`. Does nothing if the capacity is already sufficient.
+ /// Reserves the minimum capacity for at least `additional` elements 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.
///
- /// Note that the allocator may give the collection more space than it requests. Therefore
- /// capacity can not be relied upon to be precisely minimal. Prefer [`reserve`] if future
- /// insertions are expected.
+ /// [`reserve`]: BinaryHeap::reserve
///
/// # Panics
///
- /// Panics if the new capacity overflows `usize`.
+ /// Panics if the new capacity overflows [`usize`].
///
/// # Examples
///
self.data.reserve_exact(additional);
}
- /// Reserves capacity for at least `additional` more elements to be inserted in the
- /// `BinaryHeap`. The collection may reserve more space to avoid frequent reallocations.
+ /// Reserves capacity for at least `additional` elements 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`.
+ /// Panics if the new capacity overflows [`usize`].
///
/// # Examples
///
self.data.reserve(additional);
}
- /// Tries to reserve the minimum capacity for exactly `additional`
- /// elements to be inserted in the given `BinaryHeap<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
+ /// 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
/// # Examples
///
/// ```
- /// #![feature(try_reserve_2)]
/// use std::collections::BinaryHeap;
/// use std::collections::TryReserveError;
///
/// }
/// # find_max_slow(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
/// ```
- #[unstable(feature = "try_reserve_2", issue = "91789")]
+ #[stable(feature = "try_reserve_2", since = "1.63.0")]
pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> {
self.data.try_reserve_exact(additional)
}
- /// Tries to reserve capacity for at least `additional` more elements to be inserted
- /// in the given `BinaryHeap<T>`. The collection may reserve more space to 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.
+ /// Tries to reserve capacity for at least `additional` elements 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
///
/// # Examples
///
/// ```
- /// #![feature(try_reserve_2)]
/// use std::collections::BinaryHeap;
/// use std::collections::TryReserveError;
///
/// }
/// # find_max_slow(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
/// ```
- #[unstable(feature = "try_reserve_2", issue = "91789")]
+ #[stable(feature = "try_reserve_2", since = "1.63.0")]
pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> {
self.data.try_reserve(additional)
}
projects / rustc.git / blobdiff