Make performance of String::insert_str more precise

Author: hkBst

library/alloc/src/string.rs

@@ -1486,10 +1486,11 @@ impl String {
         Some(ch)
     }
 
-    /// Removes a [`char`] from this `String` at a byte position and returns it.
+    /// Removes a [`char`] from this `String` at byte position `idx` and returns it.
     ///
-    /// This is an *O*(*n*) operation, as it requires copying every element in the
-    /// buffer.
+    /// Copies all bytes after the removed char to new positions.
+    ///
+    /// NB Calling this in a loop can result in quadratic behavior.
     ///
     /// # Panics
     ///
@@ -1675,10 +1676,14 @@ impl String {
         drop(guard);
     }
 
-    /// Inserts a character into this `String` at a byte position.
+    /// Inserts a character into this `String` at byte position `idx`.
+    ///
+    /// Reallocates if `self.capacity()` is insufficient,
+    /// which may involve copying all `self.capacity()` bytes.
+    /// Makes space for the insertion,
+    /// by copying all bytes of `&self[idx..]` to new positions.
     ///
-    /// This is an *O*(*n*) operation as it requires copying every element in the
-    /// buffer.
+    /// NB Calling this in a loop can result in quadratic behavior.
     ///
     /// # Panics
     ///
@@ -1723,10 +1728,14 @@ impl String {
         }
     }
 
-    /// Inserts a string slice into this `String` at a byte position.
+    /// Inserts a string slice into this `String` at byte position `idx`.
+    ///
+    /// Reallocates if `self.capacity()` is insufficient,
+    /// which may involve copying all `self.capacity()` bytes.
+    /// Makes space for the insertion,
+    /// by copying all bytes of `&self[idx..]` to new positions.
     ///
-    /// This is an *O*(*n*) operation as it requires copying every element in the
-    /// buffer.
+    /// NB Calling this in a loop can result in quadratic behavior.
     ///
     /// # Panics
     ///