Rollup merge of #160595 - AbeZbm:clarify_str_split_doc, r=clarfonthey

Clarify `str::split_at` docs

Fixes #158990

The documentation currently describes the split position as an "index", which can be confusing because `mid` is a byte offset rather than an element index.

This change clarifies the relationship between `mid` and the returned slices by describing the length of the first slice. The first returned slice contains exactly `mid` bytes from the start of the string slice, and the second slice contains the remaining bytes.

Author: jhpratt

library/core/src/str/mod.rs

@@ -824,13 +824,13 @@ impl str {
         unsafe { &mut *(begin..end).get_unchecked_mut(self) }
     }
 
-    /// Divides one string slice into two at an index.
+    /// Divides one string slice into two at a byte offset.
     ///
     /// The argument, `mid`, should be a byte offset from the start of the
     /// string. It must also be on the boundary of a UTF-8 code point.
     ///
-    /// The two slices returned go from the start of the string slice to `mid`,
-    /// and from `mid` to the end of the string slice.
+    /// The first returned slice contains exactly the first `mid` bytes, and the
+    /// second contains all remaining bytes.
     ///
     /// To get mutable string slices instead, see the [`split_at_mut`]
     /// method.
@@ -864,13 +864,13 @@ impl str {
         }
     }
 
-    /// Divides one mutable string slice into two at an index.
+    /// Divides one mutable string slice into two at a byte offset.
     ///
     /// The argument, `mid`, should be a byte offset from the start of the
     /// string. It must also be on the boundary of a UTF-8 code point.
     ///
-    /// The two slices returned go from the start of the string slice to `mid`,
-    /// and from `mid` to the end of the string slice.
+    /// The first returned slice contains exactly the first `mid` bytes, and the
+    /// second contains all remaining bytes.
     ///
     /// To get immutable string slices instead, see the [`split_at`] method.
     ///
@@ -908,14 +908,14 @@ impl str {
         }
     }
 
-    /// Divides one string slice into two at an index.
+    /// Divides one string slice into two at a byte offset.
     ///
     /// The argument, `mid`, should be a valid byte offset from the start of the
     /// string. It must also be on the boundary of a UTF-8 code point. The
     /// method returns `None` if that’s not the case.
     ///
-    /// The two slices returned go from the start of the string slice to `mid`,
-    /// and from `mid` to the end of the string slice.
+    /// The first returned slice contains exactly the first `mid` bytes, and the
+    /// second contains all remaining bytes.
     ///
     /// To get mutable string slices instead, see the [`split_at_mut_checked`]
     /// method.
@@ -948,14 +948,14 @@ impl str {
         }
     }
 
-    /// Divides one mutable string slice into two at an index.
+    /// Divides one mutable string slice into two at a byte offset.
     ///
     /// The argument, `mid`, should be a valid byte offset from the start of the
     /// string. It must also be on the boundary of a UTF-8 code point. The
     /// method returns `None` if that’s not the case.
     ///
-    /// The two slices returned go from the start of the string slice to `mid`,
-    /// and from `mid` to the end of the string slice.
+    /// The first returned slice contains exactly the first `mid` bytes, and the
+    /// second contains all remaining bytes.
     ///
     /// To get immutable string slices instead, see the [`split_at_checked`] method.
     ///
@@ -989,7 +989,7 @@ impl str {
         }
     }
 
-    /// Divides one string slice into two at an index.
+    /// Divides one string slice into two at a byte offset.
     ///
     /// # Safety
     ///
@@ -1008,7 +1008,7 @@ impl str {
         }
     }
 
-    /// Divides one string slice into two at an index.
+    /// Divides one mutable string slice into two at a byte offset.
     ///
     /// # Safety
     ///