Make performance of String::insert_str more precise

Author: hkBst

library/alloc/src/string.rs

@@ -1489,10 +1489,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
     ///
@@ -1678,10 +1679,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
     ///
@@ -1733,10 +1738,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
     ///