From 22ffa3d384f6de1906d6e17de40db84487d9126a Mon Sep 17 00:00:00 2001 From: Chris Jefferson Date: Mon, 13 May 2024 13:35:54 +0800 Subject: [PATCH 1/2] Expand PathBuf documentation Mention that some methods do not sanitize their input fully --- std/src/path.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/std/src/path.rs b/std/src/path.rs index 506ad445b6bed..e7fd2e4ddee22 100644 --- a/std/src/path.rs +++ b/std/src/path.rs @@ -1153,6 +1153,21 @@ impl FusedIterator for Ancestors<'_> {} /// ``` /// /// Which method works best depends on what kind of situation you're in. +/// +/// Note that `PathBuf`` does not always sanitize arguments, for example +/// [`push`] allows paths built from strings which include separators: +/// +/// use std::path::PathBuf; +/// +/// let mut path = PathBuf::new(); +/// +/// path.push(r"C:\"); +/// path.push("windows"); +/// path.push(r"..\otherdir"); +/// path.push("system32"); +/// +/// The behaviour of `PathBuf` may be changed to a panic on such inputs +/// in the future. The [`extend`] method should be used to add multi-part paths. #[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")] #[stable(feature = "rust1", since = "1.0.0")] pub struct PathBuf { @@ -1391,6 +1406,9 @@ impl PathBuf { /// `file_name`. The new path will be a sibling of the original path. /// (That is, it will have the same parent.) /// + /// The argument is not sanitized, so can include separators. This + /// behaviour may be changed to a panic in the future. + /// /// [`self.file_name`]: Path::file_name /// [`pop`]: PathBuf::pop /// @@ -1411,6 +1429,12 @@ impl PathBuf { /// /// buf.set_file_name("baz"); /// assert!(buf == PathBuf::from("/baz")); + /// + /// buf.set_file_name("../b/c.txt"); + /// assert!(buf == PathBuf::from("/../b/c.txt")); + /// + /// buf.set_file_name("baz"); + /// assert!(buf == PathBuf::from("/../b/baz")); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn set_file_name>(&mut self, file_name: S) { From 34e4b6d8f7e97a3419b8aa252981439c26ab1641 Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Wed, 11 Sep 2024 22:46:06 -0700 Subject: [PATCH 2/2] Fixup docs for PathBuf --- std/src/path.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/std/src/path.rs b/std/src/path.rs index e7fd2e4ddee22..c94df9b5366be 100644 --- a/std/src/path.rs +++ b/std/src/path.rs @@ -1154,7 +1154,7 @@ impl FusedIterator for Ancestors<'_> {} /// /// Which method works best depends on what kind of situation you're in. /// -/// Note that `PathBuf`` does not always sanitize arguments, for example +/// Note that `PathBuf` does not always sanitize arguments, for example /// [`push`] allows paths built from strings which include separators: /// /// use std::path::PathBuf; @@ -1167,7 +1167,7 @@ impl FusedIterator for Ancestors<'_> {} /// path.push("system32"); /// /// The behaviour of `PathBuf` may be changed to a panic on such inputs -/// in the future. The [`extend`] method should be used to add multi-part paths. +/// in the future. [`Extend::extend`] should be used to add multi-part paths. #[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")] #[stable(feature = "rust1", since = "1.0.0")] pub struct PathBuf {