From f785dd58bca34cfd04fbe3b360c1735aec3d4d1e Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Mon, 28 Mar 2022 10:25:35 +0800 Subject: [PATCH 1/3] std: Add capacity guarantees notes for OsString Signed-off-by: Xuanwo --- std/src/ffi/os_str.rs | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/std/src/ffi/os_str.rs b/std/src/ffi/os_str.rs index ae13275e4..87d0ca980 100644 --- a/std/src/ffi/os_str.rs +++ b/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 edf7aba351630330f4d9e18ea98ea2df9b4fbf72 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 19 May 2022 18:58:55 -0700 Subject: [PATCH 2/3] OsString: Consolidate all documentation about capacity in top-level docs --- std/src/ffi/os_str.rs | 40 ++++++++++++---------------------------- 1 file changed, 12 insertions(+), 28 deletions(-) diff --git a/std/src/ffi/os_str.rs b/std/src/ffi/os_str.rs index 87d0ca980..ab02c424f 100644 --- a/std/src/ffi/os_str.rs +++ b/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 cd947adda8c46d8d5455d98cca40aa10ff9bb762 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 19 May 2022 19:06:05 -0700 Subject: [PATCH 3/3] Expand the explanation of OsString capacity --- std/src/ffi/os_str.rs | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/std/src/ffi/os_str.rs b/std/src/ffi/os_str.rs index ab02c424f..e37d314b3 100644 --- a/std/src/ffi/os_str.rs +++ b/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` ///