From 0591ff7525d3d468244e102c4002b6663db5f5ad Mon Sep 17 00:00:00 2001 From: Lyndon Brown Date: Sat, 10 Nov 2018 06:59:42 +0000 Subject: [PATCH 1/2] OsString: mention storage form in discussion Helps users to understand capacity related values, which may surpise on Windows. Also is a step towards clarifying understanding of `OsStr`'s len() return value. --- src/libstd/ffi/os_str.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs index e9390630445a1..d5a51c02a4778 100644 --- a/src/libstd/ffi/os_str.rs +++ b/src/libstd/ffi/os_str.rs @@ -42,6 +42,13 @@ use sys_common::{AsInner, IntoInner, FromInner}; /// in each pair are owned strings; the latter are borrowed /// references. /// +/// Note, `OsString` and `OsStr` internally do not necessarily hold strings in +/// the form native to the platform; While on Unix, strings are stored as a +/// sequence of 8-bit values, on Windows, where strings are 16-bit value based +/// as just discussed, strings are also actually stored as a sequence of 8-bit +/// values, encoded in a less-strict variant of UTF-8. This is useful to +/// understand when handling capacity and length values. +/// /// # Creating an `OsString` /// /// **From a Rust string**: `OsString` implements From a1e9c7fc2e4806fe72c84178bf1116f645d18c43 Mon Sep 17 00:00:00 2001 From: Lyndon Brown Date: Sat, 10 Nov 2018 07:35:15 +0000 Subject: [PATCH 2/2] OsStr: clarify `len()` method documentation --- src/libstd/ffi/os_str.rs | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs index d5a51c02a4778..0edfd122ceff9 100644 --- a/src/libstd/ffi/os_str.rs +++ b/src/libstd/ffi/os_str.rs @@ -590,14 +590,19 @@ impl OsStr { /// Returns the length of this `OsStr`. /// - /// Note that this does **not** return the number of bytes in this string - /// as, for example, OS strings on Windows are encoded as a list of [`u16`] - /// rather than a list of bytes. This number is simply useful for passing to - /// other methods like [`OsString::with_capacity`] to avoid reallocations. + /// Note that this does **not** return the number of bytes in the string in + /// OS string form. /// - /// See `OsStr` introduction for more information about encoding. + /// The length returned is that of the underlying storage used by `OsStr`; + /// As discussed in the [`OsString`] introduction, [`OsString`] and `OsStr` + /// store strings in a form best suited for cheap inter-conversion between + /// native-platform and Rust string forms, which may differ significantly + /// from both of them, including in storage size and encoding. /// - /// [`u16`]: ../primitive.u16.html + /// This number is simply useful for passing to other methods, like + /// [`OsString::with_capacity`] to avoid reallocations. + /// + /// [`OsString`]: struct.OsString.html /// [`OsString::with_capacity`]: struct.OsString.html#method.with_capacity /// /// # Examples