From 6506df7f65835c7215873f51f26740dc9fa6db0f Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Mon, 28 Mar 2022 10:25:35 +0800
Subject: [PATCH 1/3] std: Add capacity guarantees notes for OsString
Signed-off-by: Xuanwo <github@xuanwo.io>
---
library/std/src/ffi/os_str.rs | 35 +++++++++++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs
index ae13275e4b35d..87d0ca98079cc 100644
--- a/library/std/src/ffi/os_str.rs
+++ b/library/std/src/ffi/os_str.rs
@@ -45,6 +45,11 @@ 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 means UTF-8 byte size for OS strings which created from
+/// valid unicode, and not otherwise specified for other contents.
+///
/// # Creating an `OsString`
///
/// **From a Rust string**: `OsString` implements
@@ -188,6 +193,11 @@ impl OsString {
///
/// See main `OsString` documentation information about encoding.
///
+ /// # Notes
+ ///
+ /// Capacity means UTF-8 byte size for OS strings which created from
+ /// valid unicode, and not otherwise specified for other contents.
+ ///
/// # Examples
///
/// ```
@@ -231,6 +241,11 @@ impl OsString {
///
/// See `OsString` introduction for information about encoding.
///
+ /// # Notes
+ ///
+ /// Capacity means UTF-8 byte size for OS strings which created from
+ /// valid unicode, and not otherwise specified for other contents.
+ ///
/// # Examples
///
/// ```
@@ -272,6 +287,11 @@ impl OsString {
/// greater than or equal to `self.len() + additional`. Does nothing if
/// capacity is already sufficient.
///
+ /// # Notes
+ ///
+ /// Capacity means UTF-8 byte size for OS strings which created from
+ /// valid unicode, and not otherwise specified for other contents.
+ ///
/// # Errors
///
/// If the capacity overflows, or the allocator reports a failure, then an error
@@ -313,6 +333,11 @@ impl OsString {
///
/// [`reserve`]: OsString::reserve
///
+ /// # Notes
+ ///
+ /// Capacity means UTF-8 byte size for OS strings which created from
+ /// valid unicode, and not otherwise specified for other contents.
+ ///
/// # Examples
///
/// ```
@@ -340,6 +365,11 @@ impl OsString {
///
/// [`try_reserve`]: OsString::try_reserve
///
+ /// # Notes
+ ///
+ /// Capacity means UTF-8 byte size for OS strings which created from
+ /// valid unicode, and not otherwise specified for other contents.
+ ///
/// # Errors
///
/// If the capacity overflows, or the allocator reports a failure, then an error
@@ -399,6 +429,11 @@ impl OsString {
///
/// If the current capacity is less than the lower limit, this is a no-op.
///
+ /// # Notes
+ ///
+ /// Capacity means UTF-8 byte size for OS strings which created from
+ /// valid unicode, and not otherwise specified for other contents.
+ ///
/// # Examples
///
/// ```
From 81e21080b6a6419c093ef68d1a3943d946313d1d Mon Sep 17 00:00:00 2001
From: Josh Triplett <josh@joshtriplett.org>
Date: Thu, 19 May 2022 18:58:55 -0700
Subject: [PATCH 2/3] OsString: Consolidate all documentation about capacity in
top-level docs
---
library/std/src/ffi/os_str.rs | 40 +++++++++++------------------------
1 file changed, 12 insertions(+), 28 deletions(-)
diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs
index 87d0ca98079cc..ab02c424f6e55 100644
--- a/library/std/src/ffi/os_str.rs
+++ b/library/std/src/ffi/os_str.rs
@@ -191,12 +191,7 @@ impl OsString {
/// OS strings without reallocating. If `capacity` is 0, the string will not
/// allocate.
///
- /// See main `OsString` documentation information about encoding.
- ///
- /// # Notes
- ///
- /// Capacity means UTF-8 byte size for OS strings which created from
- /// valid unicode, and not otherwise specified for other contents.
+ /// See the main `OsString` documentation information about encoding and capacity units.
///
/// # Examples
///
@@ -239,12 +234,7 @@ impl OsString {
/// Returns the capacity this `OsString` can hold without reallocating.
///
- /// See `OsString` introduction for information about encoding.
- ///
- /// # Notes
- ///
- /// Capacity means UTF-8 byte size for OS strings which created from
- /// valid unicode, and not otherwise specified for other contents.
+ /// See the main `OsString` documentation information about encoding and capacity units.
///
/// # Examples
///
@@ -266,6 +256,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
///
/// ```
@@ -287,10 +279,7 @@ impl OsString {
/// greater than or equal to `self.len() + additional`. Does nothing if
/// capacity is already sufficient.
///
- /// # Notes
- ///
- /// Capacity means UTF-8 byte size for OS strings which created from
- /// valid unicode, and not otherwise specified for other contents.
+ /// See the main `OsString` documentation information about encoding and capacity units.
///
/// # Errors
///
@@ -333,10 +322,7 @@ impl OsString {
///
/// [`reserve`]: OsString::reserve
///
- /// # Notes
- ///
- /// Capacity means UTF-8 byte size for OS strings which created from
- /// valid unicode, and not otherwise specified for other contents.
+ /// See the main `OsString` documentation information about encoding and capacity units.
///
/// # Examples
///
@@ -365,10 +351,7 @@ impl OsString {
///
/// [`try_reserve`]: OsString::try_reserve
///
- /// # Notes
- ///
- /// Capacity means UTF-8 byte size for OS strings which created from
- /// valid unicode, and not otherwise specified for other contents.
+ /// See the main `OsString` documentation information about encoding and capacity units.
///
/// # Errors
///
@@ -403,6 +386,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
///
/// ```
@@ -429,10 +414,7 @@ impl OsString {
///
/// If the current capacity is less than the lower limit, this is a no-op.
///
- /// # Notes
- ///
- /// Capacity means UTF-8 byte size for OS strings which created from
- /// valid unicode, and not otherwise specified for other contents.
+ /// See the main `OsString` documentation information about encoding and capacity units.
///
/// # Examples
///
@@ -808,6 +790,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
///
/// ```
From 45582079bc24e85fb0c7b292311d84d1fa173542 Mon Sep 17 00:00:00 2001
From: Josh Triplett <josh@joshtriplett.org>
Date: Thu, 19 May 2022 19:06:05 -0700
Subject: [PATCH 3/3] Expand the explanation of OsString capacity
---
library/std/src/ffi/os_str.rs | 17 ++++++++++++++---
1 file changed, 14 insertions(+), 3 deletions(-)
diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs
index ab02c424f6e55..e37d314b3e893 100644
--- a/library/std/src/ffi/os_str.rs
+++ b/library/std/src/ffi/os_str.rs
@@ -45,10 +45,21 @@ 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 of `OsString`
///
-/// Capacity means UTF-8 byte size for OS strings which created from
-/// valid unicode, and not otherwise specified for other contents.
+/// 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`
///