Skip to content

Commit 3ff5f48

Browse files
Expand PathBuf documentation
Mention that some methods do not sanitize their input fully
1 parent 865eaf9 commit 3ff5f48

File tree

1 file changed

+24
-0
lines changed

1 file changed

+24
-0
lines changed

library/std/src/path.rs

+24
Original file line numberDiff line numberDiff line change
@@ -1156,6 +1156,21 @@ impl FusedIterator for Ancestors<'_> {}
11561156
/// ```
11571157
///
11581158
/// Which method works best depends on what kind of situation you're in.
1159+
///
1160+
/// Note that `PathBuf`` does not always sanitize arguments, for example
1161+
/// [`push`] allows paths built from strings which include separators:
1162+
///
1163+
/// use std::path::PathBuf;
1164+
///
1165+
/// let mut path = PathBuf::new();
1166+
///
1167+
/// path.push(r"C:\");
1168+
/// path.push("windows");
1169+
/// path.push(r"..\otherdir");
1170+
/// path.push("system32");
1171+
///
1172+
/// The behaviour of `PathBuf` may be changed to a panic on such inputs
1173+
/// in the future. The [`extend`] method should be used to add multi-part paths.
11591174
#[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")]
11601175
#[stable(feature = "rust1", since = "1.0.0")]
11611176
pub struct PathBuf {
@@ -1379,6 +1394,9 @@ impl PathBuf {
13791394
/// `file_name`. The new path will be a sibling of the original path.
13801395
/// (That is, it will have the same parent.)
13811396
///
1397+
/// The argument is not sanitized, so can include separators. This
1398+
/// behaviour may be changed to a panic in the future.
1399+
///
13821400
/// [`self.file_name`]: Path::file_name
13831401
/// [`pop`]: PathBuf::pop
13841402
///
@@ -1399,6 +1417,12 @@ impl PathBuf {
13991417
///
14001418
/// buf.set_file_name("baz");
14011419
/// assert!(buf == PathBuf::from("/baz"));
1420+
///
1421+
/// buf.set_file_name("../b/c.txt");
1422+
/// assert!(buf == PathBuf::from("/../b/c.txt"));
1423+
///
1424+
/// buf.set_file_name("baz");
1425+
/// assert!(buf == PathBuf::from("/../b/baz"));
14021426
/// ```
14031427
#[stable(feature = "rust1", since = "1.0.0")]
14041428
pub fn set_file_name<S: AsRef<OsStr>>(&mut self, file_name: S) {

0 commit comments

Comments
 (0)