From a0fcc8ebc0793afd66be06db3c338b0b4d43fe3c Mon Sep 17 00:00:00 2001 From: riverbl <94326797+riverbl@users.noreply.github.com> Date: Sun, 7 Jan 2024 13:58:39 +0000 Subject: [PATCH] Add `display` method to `OsStr` Add `display` method to `OsStr` for lossy display of an `OsStr` which may contain invalid unicode. Invalid Unicode sequences are replaced with `U+FFFD REPLACEMENT CHARACTER`. This change also makes the `std::ffi::os_str` module public. --- library/std/src/ffi/mod.rs | 4 +- library/std/src/ffi/os_str.rs | 67 +++++++++++++++++++++- library/std/src/path.rs | 10 ++-- tests/rustdoc-js-std/osstring-to-string.js | 2 +- 4 files changed, 73 insertions(+), 10 deletions(-) diff --git a/library/std/src/ffi/mod.rs b/library/std/src/ffi/mod.rs index 97e78d17786..1622308d9f5 100644 --- a/library/std/src/ffi/mod.rs +++ b/library/std/src/ffi/mod.rs @@ -162,6 +162,7 @@ pub use core::ffi::{CStr, FromBytesWithNulError}; #[stable(feature = "rust1", since = "1.0.0")] +#[doc(inline)] pub use self::os_str::{OsStr, OsString}; #[stable(feature = "core_ffi_c", since = "1.64.0")] @@ -181,4 +182,5 @@ )] pub use core::ffi::{VaList, VaListImpl}; -mod os_str; +#[unstable(feature = "os_str_display", issue = "120048")] +pub mod os_str; diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs index 81973182148..cd954f9e802 100644 --- a/library/std/src/ffi/os_str.rs +++ b/library/std/src/ffi/os_str.rs @@ -1,3 +1,5 @@ +//! The [`OsStr`] and [`OsString`] types and associated utilities. + #[cfg(test)] mod tests; @@ -1173,6 +1175,32 @@ pub fn is_ascii(&self) -> bool { pub fn eq_ignore_ascii_case>(&self, other: S) -> bool { self.inner.eq_ignore_ascii_case(&other.as_ref().inner) } + + /// Returns an object that implements [`Display`] for safely printing an + /// [`OsStr`] that may contain non-Unicode data. This may perform lossy + /// conversion, depending on the platform. If you would like an + /// implementation which escapes the [`OsStr`] please use [`Debug`] + /// instead. + /// + /// [`Display`]: fmt::Display + /// [`Debug`]: fmt::Debug + /// + /// # Examples + /// + /// ``` + /// #![feature(os_str_display)] + /// use std::ffi::OsStr; + /// + /// let s = OsStr::new("Hello, world!"); + /// println!("{}", s.display()); + /// ``` + #[unstable(feature = "os_str_display", issue = "120048")] + #[must_use = "this does not display the `OsStr`; \ + it returns an object that can be displayed"] + #[inline] + pub fn display(&self) -> Display<'_> { + Display { os_str: self } + } } #[stable(feature = "box_from_os_str", since = "1.17.0")] @@ -1467,9 +1495,42 @@ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { } } -impl OsStr { - pub(crate) fn display(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.inner, formatter) +/// Helper struct for safely printing an [`OsStr`] with [`format!`] and `{}`. +/// +/// An [`OsStr`] might contain non-Unicode data. This `struct` implements the +/// [`Display`] trait in a way that mitigates that. It is created by the +/// [`display`](OsStr::display) method on [`OsStr`]. This may perform lossy +/// conversion, depending on the platform. If you would like an implementation +/// which escapes the [`OsStr`] please use [`Debug`] instead. +/// +/// # Examples +/// +/// ``` +/// #![feature(os_str_display)] +/// use std::ffi::OsStr; +/// +/// let s = OsStr::new("Hello, world!"); +/// println!("{}", s.display()); +/// ``` +/// +/// [`Display`]: fmt::Display +/// [`format!`]: crate::format +#[unstable(feature = "os_str_display", issue = "120048")] +pub struct Display<'a> { + os_str: &'a OsStr, +} + +#[unstable(feature = "os_str_display", issue = "120048")] +impl fmt::Debug for Display<'_> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + fmt::Debug::fmt(&self.os_str, f) + } +} + +#[unstable(feature = "os_str_display", issue = "120048")] +impl fmt::Display for Display<'_> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + fmt::Display::fmt(&self.os_str.inner, f) } } diff --git a/library/std/src/path.rs b/library/std/src/path.rs index 60562f64c90..20cac9f2a3c 100644 --- a/library/std/src/path.rs +++ b/library/std/src/path.rs @@ -84,7 +84,7 @@ use crate::str::FromStr; use crate::sync::Arc; -use crate::ffi::{OsStr, OsString}; +use crate::ffi::{os_str, OsStr, OsString}; use crate::sys; use crate::sys::path::{is_sep_byte, is_verbatim_sep, parse_prefix, MAIN_SEP_STR}; @@ -2725,7 +2725,7 @@ pub fn iter(&self) -> Iter<'_> { it returns an object that can be displayed"] #[inline] pub fn display(&self) -> Display<'_> { - Display { path: self } + Display { inner: self.inner.display() } } /// Queries the file system to get information about a file, directory, etc. @@ -3032,20 +3032,20 @@ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { /// [`format!`]: crate::format #[stable(feature = "rust1", since = "1.0.0")] pub struct Display<'a> { - path: &'a Path, + inner: os_str::Display<'a>, } #[stable(feature = "rust1", since = "1.0.0")] impl fmt::Debug for Display<'_> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.path, f) + fmt::Debug::fmt(&self.inner, f) } } #[stable(feature = "rust1", since = "1.0.0")] impl fmt::Display for Display<'_> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.path.inner.display(f) + fmt::Display::fmt(&self.inner, f) } } diff --git a/tests/rustdoc-js-std/osstring-to-string.js b/tests/rustdoc-js-std/osstring-to-string.js index 17bb602a502..3fdc0b9f24a 100644 --- a/tests/rustdoc-js-std/osstring-to-string.js +++ b/tests/rustdoc-js-std/osstring-to-string.js @@ -4,6 +4,6 @@ const EXPECTED = { 'query': 'OsString -> String', 'others': [ - { 'path': 'std::ffi::OsString', 'name': 'into_string' }, + { 'path': 'std::ffi::os_str::OsString', 'name': 'into_string' }, ] };