Rollup merge of #97202 - joshtriplett:os-str-capacity-documentation, …

…r=dtolnay

os str capacity documentation

This is based on rust-lang/rust#95394 , with expansion and consolidation
to address comments from `@dtolnay` and other `@rust-lang/libs-api` team members.

std/src/ffi/os_str.rs

@@ -45,6 +45,22 @@ use crate::sys_common::{AsInner, FromInner, IntoInner};
 /// values, encoded in a less-strict variant of UTF-8. This is useful to
 /// understand when handling capacity and length values.
 ///
+/// # Capacity of `OsString`
+///
+/// Capacity uses units of UTF-8 bytes for OS strings which were created from valid unicode, and
+/// uses units of bytes in an unspecified encoding for other contents. On a given target, all
+/// `OsString` and `OsStr` values use the same units for capacity, so the following will work:
+/// ```
+/// use std::ffi::{OsStr, OsString};
+///
+/// fn concat_os_strings(a: &OsStr, b: &OsStr) -> OsString {
+///     let mut ret = OsString::with_capacity(a.len() + b.len()); // This will allocate
+///     ret.push(a); // This will not allocate further
+///     ret.push(b); // This will not allocate further
+///     ret
+/// }
+/// ```
+///
 /// # Creating an `OsString`
 ///
 /// **From a Rust string**: `OsString` implements
@@ -186,7 +202,7 @@ impl OsString {
     /// OS strings without reallocating. If `capacity` is 0, the string will not
     /// allocate.
     ///
-    /// See main `OsString` documentation information about encoding.
+    /// See the main `OsString` documentation information about encoding and capacity units.
     ///
     /// # Examples
     ///
@@ -229,7 +245,7 @@ impl OsString {
 
     /// Returns the capacity this `OsString` can hold without reallocating.
     ///
-    /// See `OsString` introduction for information about encoding.
+    /// See the main `OsString` documentation information about encoding and capacity units.
     ///
     /// # Examples
     ///
@@ -251,6 +267,8 @@ impl OsString {
     ///
     /// The collection may reserve more space to avoid frequent reallocations.
     ///
+    /// See the main `OsString` documentation information about encoding and capacity units.
+    ///
     /// # Examples
     ///
     /// ```
@@ -272,6 +290,8 @@ impl OsString {
     /// greater than or equal to `self.len() + additional`. Does nothing if
     /// capacity is already sufficient.
     ///
+    /// See the main `OsString` documentation information about encoding and capacity units.
+    ///
     /// # Errors
     ///
     /// If the capacity overflows, or the allocator reports a failure, then an error
@@ -313,6 +333,8 @@ impl OsString {
     ///
     /// [`reserve`]: OsString::reserve
     ///
+    /// See the main `OsString` documentation information about encoding and capacity units.
+    ///
     /// # Examples
     ///
     /// ```
@@ -340,6 +362,8 @@ impl OsString {
     ///
     /// [`try_reserve`]: OsString::try_reserve
     ///
+    /// See the main `OsString` documentation information about encoding and capacity units.
+    ///
     /// # Errors
     ///
     /// If the capacity overflows, or the allocator reports a failure, then an error
@@ -373,6 +397,8 @@ impl OsString {
 
     /// Shrinks the capacity of the `OsString` to match its length.
     ///
+    /// See the main `OsString` documentation information about encoding and capacity units.
+    ///
     /// # Examples
     ///
     /// ```
@@ -399,6 +425,8 @@ impl OsString {
     ///
     /// If the current capacity is less than the lower limit, this is a no-op.
     ///
+    /// See the main `OsString` documentation information about encoding and capacity units.
+    ///
     /// # Examples
     ///
     /// ```
@@ -773,6 +801,8 @@ impl OsStr {
     /// This number is simply useful for passing to other methods, like
     /// [`OsString::with_capacity`] to avoid reallocations.
     ///
+    /// See the main `OsString` documentation information about encoding and capacity units.
+    ///
     /// # Examples
     ///
     /// ```