diff --git a/library/std/src/ffi/mod.rs b/library/std/src/ffi/mod.rs index 97e78d1778677..125c5d652f3ff 100644 --- a/library/std/src/ffi/mod.rs +++ b/library/std/src/ffi/mod.rs @@ -181,4 +181,5 @@ pub use core::ffi::c_void; )] 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 81973182148ef..dd4993be64022 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 @@ impl OsStr { 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 @@ impl fmt::Debug for OsStr { } } -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 60562f64c90d9..20cac9f2a3c22 100644 --- a/library/std/src/path.rs +++ b/library/std/src/path.rs @@ -84,7 +84,7 @@ use crate::rc::Rc; 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 @@ impl Path { 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 @@ impl fmt::Debug for Path { /// [`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) } }