From b3937ea862e15321e85537ac6bd63ad51099c23f Mon Sep 17 00:00:00 2001 From: Sean Griffin Date: Thu, 9 Feb 2017 13:58:48 -0500 Subject: [PATCH] Explicitly mention that `Vec::reserve` is based on len not capacity I spent a good chunk of time tracking down a buffer overrun bug that resulted from me mistakenly thinking that `reserve` was based on the current capacity not the current length. It would be helpful if this were called out explicitly in the docs. --- src/libcollections/vec.rs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index dc0f33d9bc3..3873b3535a0 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -437,7 +437,9 @@ impl Vec { /// Reserves capacity for at least `additional` more elements to be inserted /// in the given `Vec`. The collection may reserve more space to avoid - /// frequent reallocations. + /// frequent reallocations. After calling `reserve`, capacity will be + /// greater than or equal to `self.len() + additional`. Does nothing if + /// capacity is already sufficient. /// /// # Panics /// @@ -456,8 +458,9 @@ impl Vec { } /// Reserves the minimum capacity for exactly `additional` more elements to - /// be inserted in the given `Vec`. Does nothing if the capacity is already - /// sufficient. + /// be inserted in the given `Vec`. 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