docs: clarify String/Vec docs related to capacity

* adds a note to String::shrink_to_fit to match the same note on Vec regarding
  additional capacity
* change asserts in docs to treat capacity as a lower bound

Author: Swatinem

src/libcollections/string.rs

@@ -763,7 +763,11 @@ impl String {
         self.vec.reserve_exact(additional)
     }
 
-    /// Shrinks the capacity of this string buffer to match its length.
+    /// Shrinks the capacity of this string buffer to match its length as much
+    /// as possible.
+    ///
+    /// It will drop down as close as possible to the length but the allocator
+    /// may still inform the string that there is space for a few more bytes.
     ///
     /// # Examples
     ///
@@ -772,7 +776,7 @@ impl String {
     /// s.reserve(100);
     /// assert!(s.capacity() >= 100);
     /// s.shrink_to_fit();
-    /// assert_eq!(s.capacity(), 3);
+    /// assert!(s.capacity() >= 3);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]

src/libcollections/vec.rs

@@ -273,10 +273,13 @@ impl<T> Vec<T> {
     /// assert_eq!(vec.len(), 0);
     ///
     /// // These are all done without reallocating...
+    /// let cap = vec.capacity();
     /// for i in 0..10 {
     ///     vec.push(i);
     /// }
     ///
+    /// assert_eq!(vec.capacity(), cap);
+    ///
     /// // ...but this may make the vector reallocate
     /// vec.push(11);
     /// ```
@@ -349,7 +352,7 @@ impl<T> Vec<T> {
     ///
     /// ```
     /// let vec: Vec<i32> = Vec::with_capacity(10);
-    /// assert_eq!(vec.capacity(), 10);
+    /// assert!(vec.capacity() >= 10);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -411,7 +414,7 @@ impl<T> Vec<T> {
     /// ```
     /// let mut vec = Vec::with_capacity(10);
     /// vec.extend([1, 2, 3].iter().cloned());
-    /// assert_eq!(vec.capacity(), 10);
+    /// assert!(vec.capacity() >= 10);
     /// vec.shrink_to_fit();
     /// assert!(vec.capacity() >= 3);
     /// ```