Change:
The [documentation for ] says— The [documentation for § "Representations of non-Rust strings"] says— These statements led me to understand that— on Microsoft Windows, an would represent its text as "arbitrary sequences of non-zero 16-bit values", and not as UTF-8, and thus on Windows, an would reference such a non-UTF-8 sequence, and thus [] — which returns an al that (by my imperfect understanding of Rust reference rules) would have to reference the same thing as the — almost always would return on Windows (except for, e.g., empty strings), because a Windows string could not validly be read as a Rust . However, tells me that— "OsStr::tostr on Windows will succeed most of the time", stores its text in WTF-8 on Windows, and it's more accurate [than what the documentation says] to say that OsStr represents an owned string in a representation capable of handling any string received from the operating system Was my misinterpretation of the documentation unreasonable? If not, could the documentation be clarified on this point? [documentation for ]: [documentation for § "Representations of non-Rust strings"]: []:
Agreed on pretty much all points here. In addition, it would be really useful to have some guidance on the best way to convert an OsStr(ing) to an LPWSTR so that it can be actually used with windows apis. Either here or in winapi-rs, not sure where the best fit would be.
I would like to be able to losslessly transcode between a [] and an []. A [] may contain zeros, however. []: []:
may also contain zeros.

Discussion:
//! [`OsStr`] and Rust strings work similarly to those for [`CString`] //! and [`CStr`]. //! <del> //! * [`OsString`] represents an owned string in whatever //! representation the operating system prefers. In the Rust standard //! library, various APIs that transfer strings to/from the operating </del> <ins> //! * [`OsString`] losslessly represents an owned platform string. However, this //! representation is not necessarily in a form native to the platform. //! In the Rust standard library, various APIs that transfer strings to/from the operating </ins> //! system use [`OsString`] instead of plain strings. For example, //! [`env::var_os()`] is used to query environment variables; it //! returns an <code>[Option]<[OsString]></code>. If the environment variable

//! your code can detect errors in case the environment variable did //! not in fact contain valid Unicode data. //! <del> //! * [`OsStr`] represents a borrowed reference to a string in a //! format that can be passed to the operating system. It can be //! converted into a UTF-8 Rust string slice in a similar way to </del> <ins> //! * [`OsStr`] losslessly represents a borrowed reference to a platform string. //! However, this representation is not necessarily in a form native to the platform. //! It can be converted into a UTF-8 Rust string slice in a similar way to </ins> //! [`OsString`]. //! //! # Conversions

//! //! ## On Windows //! <ins> //! An [`OsStr`] can be losslessly converted to a native Windows string. And //! a native Windows string can be losslessly converted to an [`OsString`]. //! </ins> //! On Windows, [`OsStr`] implements the //! <code>std::os::windows::ffi::[OsStrExt][windows.OsStrExt]</code> trait, //! which provides an [`encode_wide`] method. This provides an <del> //! iterator that can be [`collect`]ed into a vector of [`u16`]. </del> <ins> //! iterator that can be [`collect`]ed into a vector of [`u16`]. After a nul //! characters is appended, this is the same as a native Windows string. </ins> //! //! Additionally, on Windows [`OsString`] implements the //! <code>std::os::windows:ffi::[OsStringExt][windows.OsStringExt]</code> <del> //! trait, which provides a [`from_wide`] method. The result of this //! method is an [`OsString`] which can be round-tripped to a Windows //! string losslessly. </del> <ins> //! trait, which provides a [`from_wide`] method to convert a native Windows //! string (without the terminating nul character) to an [`OsString`]. </ins> //! //! [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value //! [Unicode code point]: https://www.unicode.org/glossary/#code_point