@@ -1156,6 +1156,21 @@ impl FusedIterator for Ancestors<'_> {}
1156
1156
/// ```
1157
1157
///
1158
1158
/// 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.
1159
1174
#[ cfg_attr( not( test) , rustc_diagnostic_item = "PathBuf" ) ]
1160
1175
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1161
1176
pub struct PathBuf {
@@ -1379,6 +1394,9 @@ impl PathBuf {
1379
1394
/// `file_name`. The new path will be a sibling of the original path.
1380
1395
/// (That is, it will have the same parent.)
1381
1396
///
1397
+ /// The argument is not sanitized, so can include separators. This
1398
+ /// behaviour may be changed to a panic in the future.
1399
+ ///
1382
1400
/// [`self.file_name`]: Path::file_name
1383
1401
/// [`pop`]: PathBuf::pop
1384
1402
///
@@ -1399,6 +1417,12 @@ impl PathBuf {
1399
1417
///
1400
1418
/// buf.set_file_name("baz");
1401
1419
/// 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"));
1402
1426
/// ```
1403
1427
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1404
1428
pub fn set_file_name < S : AsRef < OsStr > > ( & mut self , file_name : S ) {
0 commit comments