mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #91467 - ChrisDenton:confusing-os-string, r=Mark-Simulacrum

Browse Source 
Emphasise that an OsStr[ing] is not necessarily a platform string

Fixes #53261

Since that issue was filed, #56141 added a further clarification to the `OsString` docs. However the ffi docs may still leave the impression that an `OsStr` is in the platform native form. This PR aims to further emphasise that an `OsStr` is not necessarily a platform string.
This commit is contained in:
Matthias Krüger 2021-12-08 11:08:58 +01:00 committed by GitHub
commit bb8a4ab6ae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 13 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
library/std/src/ffi/mod.rs
View File

@ -81,9 +81,9 @@
//! [`OsStr`] and Rust strings work similarly to those for [`CString`] //! [`OsStr`] and Rust strings work similarly to those for [`CString`]
//! and [`CStr`]. //! and [`CStr`].
//! //!
//! * [`OsString`] represents an owned string in whatever //! * [`OsString`] losslessly represents an owned platform string. However, this
//! representation the operating system prefers. In the Rust standard //! representation is not necessarily in a form native to the platform.
//! library, various APIs that transfer strings to/from the operating //! In the Rust standard library, various APIs that transfer strings to/from the operating
//! system use [`OsString`] instead of plain strings. For example, //! system use [`OsString`] instead of plain strings. For example,
//! [`env::var_os()`] is used to query environment variables; it //! [`env::var_os()`] is used to query environment variables; it
//! returns an <code>[Option]<[OsString]></code>. If the environment variable //! returns an <code>[Option]<[OsString]></code>. If the environment variable
@ -92,9 +92,9 @@
//! your code can detect errors in case the environment variable did //! your code can detect errors in case the environment variable did
//! not in fact contain valid Unicode data. //! not in fact contain valid Unicode data.
//! //!
//! * [`OsStr`] represents a borrowed reference to a string in a //! * [`OsStr`] losslessly represents a borrowed reference to a platform string.
//! format that can be passed to the operating system. It can be //! However, this representation is not necessarily in a form native to the platform.
//! converted into a UTF-8 Rust string slice in a similar way to //! It can be converted into a UTF-8 Rust string slice in a similar way to
//! [`OsString`]. //! [`OsString`].
//! //!
//! # Conversions //! # Conversions
@ -113,16 +113,19 @@
//! //!
//! ## On Windows //! ## On Windows
//! //!
//! An [`OsStr`] can be losslessly converted to a native Windows string. And
//! a native Windows string can be losslessly converted to an [`OsString`].
//!
//! On Windows, [`OsStr`] implements the //! On Windows, [`OsStr`] implements the
//! <code>std::os::windows::ffi::[OsStrExt][windows.OsStrExt]</code> trait, //! <code>std::os::windows::ffi::[OsStrExt][windows.OsStrExt]</code> trait,
//! which provides an [`encode_wide`] method. This provides an //! which provides an [`encode_wide`] method. This provides an
//! iterator that can be [`collect`]ed into a vector of [`u16`]. //! 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.
//! //!
//! Additionally, on Windows [`OsString`] implements the //! Additionally, on Windows [`OsString`] implements the
//! <code>std::os::windows:ffi::[OsStringExt][windows.OsStringExt]</code> //! <code>std::os::windows:ffi::[OsStringExt][windows.OsStringExt]</code>
//! trait, which provides a [`from_wide`] method. The result of this //! trait, which provides a [`from_wide`] method to convert a native Windows
//! method is an [`OsString`] which can be round-tripped to a Windows //! string (without the terminating nul character) to an [`OsString`].
//! string losslessly.
//! //!
//! [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value //! [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value
//! [Unicode code point]: https://www.unicode.org/glossary/#code_point //! [Unicode code point]: https://www.unicode.org/glossary/#code_point