library/std/src/path.rs

   1 //! Cross-platform path manipulation.
   2 //!
   3 //! This module provides two types, [`PathBuf`] and [`Path`] (akin to [`String`]
   4 //! and [`str`]), for working with paths abstractly. These types are thin wrappers
   5 //! around [`OsString`] and [`OsStr`] respectively, meaning that they work directly
   6 //! on strings according to the local platform's path syntax.
   7 //!
   8 //! Paths can be parsed into [`Component`]s by iterating over the structure
   9 //! returned by the [`components`] method on [`Path`]. [`Component`]s roughly
  10 //! correspond to the substrings between path separators (`/` or `\`). You can
  11 //! reconstruct an equivalent path from components with the [`push`] method on
  12 //! [`PathBuf`]; note that the paths may differ syntactically by the
  13 //! normalization described in the documentation for the [`components`] method.
  14 //!
  15 //! ## Simple usage
  16 //!
  17 //! Path manipulation includes both parsing components from slices and building
  18 //! new owned paths.
  19 //!
  20 //! To parse a path, you can create a [`Path`] slice from a [`str`]
  21 //! slice and start asking questions:
  22 //!
  23 //! ```
  24 //! use std::path::Path;
  25 //! use std::ffi::OsStr;
  26 //!
  27 //! let path = Path::new("/tmp/foo/bar.txt");
  28 //!
  29 //! let parent = path.parent();
  30 //! assert_eq!(parent, Some(Path::new("/tmp/foo")));
  31 //!
  32 //! let file_stem = path.file_stem();
  33 //! assert_eq!(file_stem, Some(OsStr::new("bar")));
  34 //!
  35 //! let extension = path.extension();
  36 //! assert_eq!(extension, Some(OsStr::new("txt")));
  37 //! ```
  38 //!
  39 //! To build or modify paths, use [`PathBuf`]:
  40 //!
  41 //! ```
  42 //! use std::path::PathBuf;
  43 //!
  44 //! // This way works...
  45 //! let mut path = PathBuf::from("c:\\");
  46 //!
  47 //! path.push("windows");
  48 //! path.push("system32");
  49 //!
  50 //! path.set_extension("dll");
  51 //!
  52 //! // ... but push is best used if you don't know everything up
  53 //! // front. If you do, this way is better:
  54 //! let path: PathBuf = ["c:\\", "windows", "system32.dll"].iter().collect();
  55 //! ```
  56 //!
  57 //! [`components`]: Path::components
  58 //! [`push`]: PathBuf::push
  59
  60 #![stable(feature = "rust1", since = "1.0.0")]
  61 #![deny(unsafe_op_in_unsafe_fn)]
  62
  63 #[cfg(test)]
  64 mod tests;
  65
  66 use crate::borrow::{Borrow, Cow};
  67 use crate::cmp;
  68 use crate::error::Error;
  69 use crate::fmt;
  70 use crate::fs;
  71 use crate::hash::{Hash, Hasher};
  72 use crate::io;
  73 use crate::iter::{self, FusedIterator};
  74 use crate::ops::{self, Deref};
  75 use crate::rc::Rc;
  76 use crate::str::FromStr;
  77 use crate::sync::Arc;
  78
  79 use crate::ffi::{OsStr, OsString};
  80
  81 use crate::sys::path::{is_sep_byte, is_verbatim_sep, parse_prefix, MAIN_SEP_STR};
  82
  83 ////////////////////////////////////////////////////////////////////////////////
  84 // GENERAL NOTES
  85 ////////////////////////////////////////////////////////////////////////////////
  86 //
  87 // Parsing in this module is done by directly transmuting OsStr to [u8] slices,
  88 // taking advantage of the fact that OsStr always encodes ASCII characters
  89 // as-is.  Eventually, this transmutation should be replaced by direct uses of
  90 // OsStr APIs for parsing, but it will take a while for those to become
  91 // available.
  92
  93 ////////////////////////////////////////////////////////////////////////////////
  94 // Windows Prefixes
  95 ////////////////////////////////////////////////////////////////////////////////
  96
  97 /// Windows path prefixes, e.g., `C:` or `\\server\share`.
  98 ///
  99 /// Windows uses a variety of path prefix styles, including references to drive
 100 /// volumes (like `C:`), network shared folders (like `\\server\share`), and
 101 /// others. In addition, some path prefixes are "verbatim" (i.e., prefixed with
 102 /// `\\?\`), in which case `/` is *not* treated as a separator and essentially
 103 /// no normalization is performed.
 104 ///
 105 /// # Examples
 106 ///
 107 /// ```
 108 /// use std::path::{Component, Path, Prefix};
 109 /// use std::path::Prefix::*;
 110 /// use std::ffi::OsStr;
 111 ///
 112 /// fn get_path_prefix(s: &str) -> Prefix {
 113 ///     let path = Path::new(s);
 114 ///     match path.components().next().unwrap() {
 115 ///         Component::Prefix(prefix_component) => prefix_component.kind(),
 116 ///         _ => panic!(),
 117 ///     }
 118 /// }
 119 ///
 120 /// # if cfg!(windows) {
 121 /// assert_eq!(Verbatim(OsStr::new("pictures")),
 122 ///            get_path_prefix(r"\\?\pictures\kittens"));
 123 /// assert_eq!(VerbatimUNC(OsStr::new("server"), OsStr::new("share")),
 124 ///            get_path_prefix(r"\\?\UNC\server\share"));
 125 /// assert_eq!(VerbatimDisk(b'C'), get_path_prefix(r"\\?\c:\"));
 126 /// assert_eq!(DeviceNS(OsStr::new("BrainInterface")),
 127 ///            get_path_prefix(r"\\.\BrainInterface"));
 128 /// assert_eq!(UNC(OsStr::new("server"), OsStr::new("share")),
 129 ///            get_path_prefix(r"\\server\share"));
 130 /// assert_eq!(Disk(b'C'), get_path_prefix(r"C:\Users\Rust\Pictures\Ferris"));
 131 /// # }
 132 /// ```
 133 #[derive(Copy, Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
 134 #[stable(feature = "rust1", since = "1.0.0")]
 135 pub enum Prefix<'a> {
 136     /// Verbatim prefix, e.g., `\\?\cat_pics`.
 137     ///
 138     /// Verbatim prefixes consist of `\\?\` immediately followed by the given
 139     /// component.
 140     #[stable(feature = "rust1", since = "1.0.0")]
 141     Verbatim(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr),
 142
 143     /// Verbatim prefix using Windows' _**U**niform **N**aming **C**onvention_,
 144     /// e.g., `\\?\UNC\server\share`.
 145     ///
 146     /// Verbatim UNC prefixes consist of `\\?\UNC\` immediately followed by the
 147     /// server's hostname and a share name.
 148     #[stable(feature = "rust1", since = "1.0.0")]
 149     VerbatimUNC(
 150         #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
 151         #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
 152     ),
 153
 154     /// Verbatim disk prefix, e.g., `\\?\C:`.
 155     ///
 156     /// Verbatim disk prefixes consist of `\\?\` immediately followed by the
 157     /// drive letter and `:`.
 158     #[stable(feature = "rust1", since = "1.0.0")]
 159     VerbatimDisk(#[stable(feature = "rust1", since = "1.0.0")] u8),
 160
 161     /// Device namespace prefix, e.g., `\\.\COM42`.
 162     ///
 163     /// Device namespace prefixes consist of `\\.\` immediately followed by the
 164     /// device name.
 165     #[stable(feature = "rust1", since = "1.0.0")]
 166     DeviceNS(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr),
 167
 168     /// Prefix using Windows' _**U**niform **N**aming **C**onvention_, e.g.
 169     /// `\\server\share`.
 170     ///
 171     /// UNC prefixes consist of the server's hostname and a share name.
 172     #[stable(feature = "rust1", since = "1.0.0")]
 173     UNC(
 174         #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
 175         #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr,
 176     ),
 177
 178     /// Prefix `C:` for the given disk drive.
 179     #[stable(feature = "rust1", since = "1.0.0")]
 180     Disk(#[stable(feature = "rust1", since = "1.0.0")] u8),
 181 }
 182
 183 impl<'a> Prefix<'a> {
 184     #[inline]
 185     fn len(&self) -> usize {
 186         use self::Prefix::*;
 187         fn os_str_len(s: &OsStr) -> usize {
 188             os_str_as_u8_slice(s).len()
 189         }
 190         match *self {
 191             Verbatim(x) => 4 + os_str_len(x),
 192             VerbatimUNC(x, y) => {
 193                 8 + os_str_len(x) + if os_str_len(y) > 0 { 1 + os_str_len(y) } else { 0 }
 194             }
 195             VerbatimDisk(_) => 6,
 196             UNC(x, y) => 2 + os_str_len(x) + if os_str_len(y) > 0 { 1 + os_str_len(y) } else { 0 },
 197             DeviceNS(x) => 4 + os_str_len(x),
 198             Disk(_) => 2,
 199         }
 200     }
 201
 202     /// Determines if the prefix is verbatim, i.e., begins with `\\?\`.
 203     ///
 204     /// # Examples
 205     ///
 206     /// ```
 207     /// use std::path::Prefix::*;
 208     /// use std::ffi::OsStr;
 209     ///
 210     /// assert!(Verbatim(OsStr::new("pictures")).is_verbatim());
 211     /// assert!(VerbatimUNC(OsStr::new("server"), OsStr::new("share")).is_verbatim());
 212     /// assert!(VerbatimDisk(b'C').is_verbatim());
 213     /// assert!(!DeviceNS(OsStr::new("BrainInterface")).is_verbatim());
 214     /// assert!(!UNC(OsStr::new("server"), OsStr::new("share")).is_verbatim());
 215     /// assert!(!Disk(b'C').is_verbatim());
 216     /// ```
 217     #[inline]
 218     #[stable(feature = "rust1", since = "1.0.0")]
 219     pub fn is_verbatim(&self) -> bool {
 220         use self::Prefix::*;
 221         matches!(*self, Verbatim(_) | VerbatimDisk(_) | VerbatimUNC(..))
 222     }
 223
 224     #[inline]
 225     fn is_drive(&self) -> bool {
 226         matches!(*self, Prefix::Disk(_))
 227     }
 228
 229     #[inline]
 230     fn has_implicit_root(&self) -> bool {
 231         !self.is_drive()
 232     }
 233 }
 234
 235 ////////////////////////////////////////////////////////////////////////////////
 236 // Exposed parsing helpers
 237 ////////////////////////////////////////////////////////////////////////////////
 238
 239 /// Determines whether the character is one of the permitted path
 240 /// separators for the current platform.
 241 ///
 242 /// # Examples
 243 ///
 244 /// ```
 245 /// use std::path;
 246 ///
 247 /// assert!(path::is_separator('/')); // '/' works for both Unix and Windows
 248 /// assert!(!path::is_separator('❤'));
 249 /// ```
 250 #[stable(feature = "rust1", since = "1.0.0")]
 251 pub fn is_separator(c: char) -> bool {
 252     c.is_ascii() && is_sep_byte(c as u8)
 253 }
 254
 255 /// The primary separator of path components for the current platform.
 256 ///
 257 /// For example, `/` on Unix and `\` on Windows.
 258 #[stable(feature = "rust1", since = "1.0.0")]
 259 pub const MAIN_SEPARATOR: char = crate::sys::path::MAIN_SEP;
 260
 261 ////////////////////////////////////////////////////////////////////////////////
 262 // Misc helpers
 263 ////////////////////////////////////////////////////////////////////////////////
 264
 265 // Iterate through `iter` while it matches `prefix`; return `None` if `prefix`
 266 // is not a prefix of `iter`, otherwise return `Some(iter_after_prefix)` giving
 267 // `iter` after having exhausted `prefix`.
 268 fn iter_after<'a, 'b, I, J>(mut iter: I, mut prefix: J) -> Option<I>
 269 where
 270     I: Iterator<Item = Component<'a>> + Clone,
 271     J: Iterator<Item = Component<'b>>,
 272 {
 273     loop {
 274         let mut iter_next = iter.clone();
 275         match (iter_next.next(), prefix.next()) {
 276             (Some(ref x), Some(ref y)) if x == y => (),
 277             (Some(_), Some(_)) => return None,
 278             (Some(_), None) => return Some(iter),
 279             (None, None) => return Some(iter),
 280             (None, Some(_)) => return None,
 281         }
 282         iter = iter_next;
 283     }
 284 }
 285
 286 // See note at the top of this module to understand why these are used:
 287 //
 288 // These casts are safe as OsStr is internally a wrapper around [u8] on all
 289 // platforms.
 290 //
 291 // Note that currently this relies on the special knowledge that libstd has;
 292 // these types are single-element structs but are not marked repr(transparent)
 293 // or repr(C) which would make these casts allowable outside std.
 294 fn os_str_as_u8_slice(s: &OsStr) -> &[u8] {
 295     unsafe { &*(s as *const OsStr as *const [u8]) }
 296 }
 297 unsafe fn u8_slice_as_os_str(s: &[u8]) -> &OsStr {
 298     // SAFETY: see the comment of `os_str_as_u8_slice`
 299     unsafe { &*(s as *const [u8] as *const OsStr) }
 300 }
 301
 302 // Detect scheme on Redox
 303 fn has_redox_scheme(s: &[u8]) -> bool {
 304     cfg!(target_os = "redox") && s.contains(&b':')
 305 }
 306
 307 ////////////////////////////////////////////////////////////////////////////////
 308 // Cross-platform, iterator-independent parsing
 309 ////////////////////////////////////////////////////////////////////////////////
 310
 311 /// Says whether the first byte after the prefix is a separator.
 312 fn has_physical_root(s: &[u8], prefix: Option<Prefix<'_>>) -> bool {
 313     let path = if let Some(p) = prefix { &s[p.len()..] } else { s };
 314     !path.is_empty() && is_sep_byte(path[0])
 315 }
 316
 317 // basic workhorse for splitting stem and extension
 318 fn rsplit_file_at_dot(file: &OsStr) -> (Option<&OsStr>, Option<&OsStr>) {
 319     if os_str_as_u8_slice(file) == b".." {
 320         return (Some(file), None);
 321     }
 322
 323     // The unsafety here stems from converting between &OsStr and &[u8]
 324     // and back. This is safe to do because (1) we only look at ASCII
 325     // contents of the encoding and (2) new &OsStr values are produced
 326     // only from ASCII-bounded slices of existing &OsStr values.
 327     let mut iter = os_str_as_u8_slice(file).rsplitn(2, |b| *b == b'.');
 328     let after = iter.next();
 329     let before = iter.next();
 330     if before == Some(b"") {
 331         (Some(file), None)
 332     } else {
 333         unsafe { (before.map(|s| u8_slice_as_os_str(s)), after.map(|s| u8_slice_as_os_str(s))) }
 334     }
 335 }
 336
 337 fn split_file_at_dot(file: &OsStr) -> (&OsStr, Option<&OsStr>) {
 338     let slice = os_str_as_u8_slice(file);
 339     if slice == b".." {
 340         return (file, None);
 341     }
 342
 343     // The unsafety here stems from converting between &OsStr and &[u8]
 344     // and back. This is safe to do because (1) we only look at ASCII
 345     // contents of the encoding and (2) new &OsStr values are produced
 346     // only from ASCII-bounded slices of existing &OsStr values.
 347     let i = match slice[1..].iter().position(|b| *b == b'.') {
 348         Some(i) => i + 1,
 349         None => return (file, None),
 350     };
 351     let before = &slice[..i];
 352     let after = &slice[i + 1..];
 353     unsafe { (u8_slice_as_os_str(before), Some(u8_slice_as_os_str(after))) }
 354 }
 355
 356 ////////////////////////////////////////////////////////////////////////////////
 357 // The core iterators
 358 ////////////////////////////////////////////////////////////////////////////////
 359
 360 /// Component parsing works by a double-ended state machine; the cursors at the
 361 /// front and back of the path each keep track of what parts of the path have
 362 /// been consumed so far.
 363 ///
 364 /// Going front to back, a path is made up of a prefix, a starting
 365 /// directory component, and a body (of normal components)
 366 #[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
 367 enum State {
 368     Prefix = 0,   // c:
 369     StartDir = 1, // / or . or nothing
 370     Body = 2,     // foo/bar/baz
 371     Done = 3,
 372 }
 373
 374 /// A structure wrapping a Windows path prefix as well as its unparsed string
 375 /// representation.
 376 ///
 377 /// In addition to the parsed [`Prefix`] information returned by [`kind`],
 378 /// `PrefixComponent` also holds the raw and unparsed [`OsStr`] slice,
 379 /// returned by [`as_os_str`].
 380 ///
 381 /// Instances of this `struct` can be obtained by matching against the
 382 /// [`Prefix` variant] on [`Component`].
 383 ///
 384 /// Does not occur on Unix.
 385 ///
 386 /// # Examples
 387 ///
 388 /// ```
 389 /// # if cfg!(windows) {
 390 /// use std::path::{Component, Path, Prefix};
 391 /// use std::ffi::OsStr;
 392 ///
 393 /// let path = Path::new(r"c:\you\later\");
 394 /// match path.components().next().unwrap() {
 395 ///     Component::Prefix(prefix_component) => {
 396 ///         assert_eq!(Prefix::Disk(b'C'), prefix_component.kind());
 397 ///         assert_eq!(OsStr::new("c:"), prefix_component.as_os_str());
 398 ///     }
 399 ///     _ => unreachable!(),
 400 /// }
 401 /// # }
 402 /// ```
 403 ///
 404 /// [`as_os_str`]: PrefixComponent::as_os_str
 405 /// [`kind`]: PrefixComponent::kind
 406 /// [`Prefix` variant]: Component::Prefix
 407 #[stable(feature = "rust1", since = "1.0.0")]
 408 #[derive(Copy, Clone, Eq, Debug)]
 409 pub struct PrefixComponent<'a> {
 410     /// The prefix as an unparsed `OsStr` slice.
 411     raw: &'a OsStr,
 412
 413     /// The parsed prefix data.
 414     parsed: Prefix<'a>,
 415 }
 416
 417 impl<'a> PrefixComponent<'a> {
 418     /// Returns the parsed prefix data.
 419     ///
 420     /// See [`Prefix`]'s documentation for more information on the different
 421     /// kinds of prefixes.
 422     #[stable(feature = "rust1", since = "1.0.0")]
 423     #[inline]
 424     pub fn kind(&self) -> Prefix<'a> {
 425         self.parsed
 426     }
 427
 428     /// Returns the raw [`OsStr`] slice for this prefix.
 429     #[stable(feature = "rust1", since = "1.0.0")]
 430     #[inline]
 431     pub fn as_os_str(&self) -> &'a OsStr {
 432         self.raw
 433     }
 434 }
 435
 436 #[stable(feature = "rust1", since = "1.0.0")]
 437 impl<'a> cmp::PartialEq for PrefixComponent<'a> {
 438     #[inline]
 439     fn eq(&self, other: &PrefixComponent<'a>) -> bool {
 440         cmp::PartialEq::eq(&self.parsed, &other.parsed)
 441     }
 442 }
 443
 444 #[stable(feature = "rust1", since = "1.0.0")]
 445 impl<'a> cmp::PartialOrd for PrefixComponent<'a> {
 446     #[inline]
 447     fn partial_cmp(&self, other: &PrefixComponent<'a>) -> Option<cmp::Ordering> {
 448         cmp::PartialOrd::partial_cmp(&self.parsed, &other.parsed)
 449     }
 450 }
 451
 452 #[stable(feature = "rust1", since = "1.0.0")]
 453 impl cmp::Ord for PrefixComponent<'_> {
 454     #[inline]
 455     fn cmp(&self, other: &Self) -> cmp::Ordering {
 456         cmp::Ord::cmp(&self.parsed, &other.parsed)
 457     }
 458 }
 459
 460 #[stable(feature = "rust1", since = "1.0.0")]
 461 impl Hash for PrefixComponent<'_> {
 462     fn hash<H: Hasher>(&self, h: &mut H) {
 463         self.parsed.hash(h);
 464     }
 465 }
 466
 467 /// A single component of a path.
 468 ///
 469 /// A `Component` roughly corresponds to a substring between path separators
 470 /// (`/` or `\`).
 471 ///
 472 /// This `enum` is created by iterating over [`Components`], which in turn is
 473 /// created by the [`components`](Path::components) method on [`Path`].
 474 ///
 475 /// # Examples
 476 ///
 477 /// ```rust
 478 /// use std::path::{Component, Path};
 479 ///
 480 /// let path = Path::new("/tmp/foo/bar.txt");
 481 /// let components = path.components().collect::<Vec<_>>();
 482 /// assert_eq!(&components, &[
 483 ///     Component::RootDir,
 484 ///     Component::Normal("tmp".as_ref()),
 485 ///     Component::Normal("foo".as_ref()),
 486 ///     Component::Normal("bar.txt".as_ref()),
 487 /// ]);
 488 /// ```
 489 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 490 #[stable(feature = "rust1", since = "1.0.0")]
 491 pub enum Component<'a> {
 492     /// A Windows path prefix, e.g., `C:` or `\\server\share`.
 493     ///
 494     /// There is a large variety of prefix types, see [`Prefix`]'s documentation
 495     /// for more.
 496     ///
 497     /// Does not occur on Unix.
 498     #[stable(feature = "rust1", since = "1.0.0")]
 499     Prefix(#[stable(feature = "rust1", since = "1.0.0")] PrefixComponent<'a>),
 500
 501     /// The root directory component, appears after any prefix and before anything else.
 502     ///
 503     /// It represents a separator that designates that a path starts from root.
 504     #[stable(feature = "rust1", since = "1.0.0")]
 505     RootDir,
 506
 507     /// A reference to the current directory, i.e., `.`.
 508     #[stable(feature = "rust1", since = "1.0.0")]
 509     CurDir,
 510
 511     /// A reference to the parent directory, i.e., `..`.
 512     #[stable(feature = "rust1", since = "1.0.0")]
 513     ParentDir,
 514
 515     /// A normal component, e.g., `a` and `b` in `a/b`.
 516     ///
 517     /// This variant is the most common one, it represents references to files
 518     /// or directories.
 519     #[stable(feature = "rust1", since = "1.0.0")]
 520     Normal(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr),
 521 }
 522
 523 impl<'a> Component<'a> {
 524     /// Extracts the underlying [`OsStr`] slice.
 525     ///
 526     /// # Examples
 527     ///
 528     /// ```
 529     /// use std::path::Path;
 530     ///
 531     /// let path = Path::new("./tmp/foo/bar.txt");
 532     /// let components: Vec<_> = path.components().map(|comp| comp.as_os_str()).collect();
 533     /// assert_eq!(&components, &[".", "tmp", "foo", "bar.txt"]);
 534     /// ```
 535     #[stable(feature = "rust1", since = "1.0.0")]
 536     pub fn as_os_str(self) -> &'a OsStr {
 537         match self {
 538             Component::Prefix(p) => p.as_os_str(),
 539             Component::RootDir => OsStr::new(MAIN_SEP_STR),
 540             Component::CurDir => OsStr::new("."),
 541             Component::ParentDir => OsStr::new(".."),
 542             Component::Normal(path) => path,
 543         }
 544     }
 545 }
 546
 547 #[stable(feature = "rust1", since = "1.0.0")]
 548 impl AsRef<OsStr> for Component<'_> {
 549     #[inline]
 550     fn as_ref(&self) -> &OsStr {
 551         self.as_os_str()
 552     }
 553 }
 554
 555 #[stable(feature = "path_component_asref", since = "1.25.0")]
 556 impl AsRef<Path> for Component<'_> {
 557     #[inline]
 558     fn as_ref(&self) -> &Path {
 559         self.as_os_str().as_ref()
 560     }
 561 }
 562
 563 /// An iterator over the [`Component`]s of a [`Path`].
 564 ///
 565 /// This `struct` is created by the [`components`] method on [`Path`].
 566 /// See its documentation for more.
 567 ///
 568 /// # Examples
 569 ///
 570 /// ```
 571 /// use std::path::Path;
 572 ///
 573 /// let path = Path::new("/tmp/foo/bar.txt");
 574 ///
 575 /// for component in path.components() {
 576 ///     println!("{:?}", component);
 577 /// }
 578 /// ```
 579 ///
 580 /// [`components`]: Path::components
 581 #[derive(Clone)]
 582 #[stable(feature = "rust1", since = "1.0.0")]
 583 pub struct Components<'a> {
 584     // The path left to parse components from
 585     path: &'a [u8],
 586
 587     // The prefix as it was originally parsed, if any
 588     prefix: Option<Prefix<'a>>,
 589
 590     // true if path *physically* has a root separator; for most Windows
 591     // prefixes, it may have a "logical" root separator for the purposes of
 592     // normalization, e.g.,  \\server\share == \\server\share\.
 593     has_physical_root: bool,
 594
 595     // The iterator is double-ended, and these two states keep track of what has
 596     // been produced from either end
 597     front: State,
 598     back: State,
 599 }
 600
 601 /// An iterator over the [`Component`]s of a [`Path`], as [`OsStr`] slices.
 602 ///
 603 /// This `struct` is created by the [`iter`] method on [`Path`].
 604 /// See its documentation for more.
 605 ///
 606 /// [`iter`]: Path::iter
 607 #[derive(Clone)]
 608 #[stable(feature = "rust1", since = "1.0.0")]
 609 pub struct Iter<'a> {
 610     inner: Components<'a>,
 611 }
 612
 613 #[stable(feature = "path_components_debug", since = "1.13.0")]
 614 impl fmt::Debug for Components<'_> {
 615     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 616         struct DebugHelper<'a>(&'a Path);
 617
 618         impl fmt::Debug for DebugHelper<'_> {
 619             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 620                 f.debug_list().entries(self.0.components()).finish()
 621             }
 622         }
 623
 624         f.debug_tuple("Components").field(&DebugHelper(self.as_path())).finish()
 625     }
 626 }
 627
 628 impl<'a> Components<'a> {
 629     // how long is the prefix, if any?
 630     #[inline]
 631     fn prefix_len(&self) -> usize {
 632         self.prefix.as_ref().map(Prefix::len).unwrap_or(0)
 633     }
 634
 635     #[inline]
 636     fn prefix_verbatim(&self) -> bool {
 637         self.prefix.as_ref().map(Prefix::is_verbatim).unwrap_or(false)
 638     }
 639
 640     /// how much of the prefix is left from the point of view of iteration?
 641     #[inline]
 642     fn prefix_remaining(&self) -> usize {
 643         if self.front == State::Prefix { self.prefix_len() } else { 0 }
 644     }
 645
 646     // Given the iteration so far, how much of the pre-State::Body path is left?
 647     #[inline]
 648     fn len_before_body(&self) -> usize {
 649         let root = if self.front <= State::StartDir && self.has_physical_root { 1 } else { 0 };
 650         let cur_dir = if self.front <= State::StartDir && self.include_cur_dir() { 1 } else { 0 };
 651         self.prefix_remaining() + root + cur_dir
 652     }
 653
 654     // is the iteration complete?
 655     #[inline]
 656     fn finished(&self) -> bool {
 657         self.front == State::Done || self.back == State::Done || self.front > self.back
 658     }
 659
 660     #[inline]
 661     fn is_sep_byte(&self, b: u8) -> bool {
 662         if self.prefix_verbatim() { is_verbatim_sep(b) } else { is_sep_byte(b) }
 663     }
 664
 665     /// Extracts a slice corresponding to the portion of the path remaining for iteration.
 666     ///
 667     /// # Examples
 668     ///
 669     /// ```
 670     /// use std::path::Path;
 671     ///
 672     /// let mut components = Path::new("/tmp/foo/bar.txt").components();
 673     /// components.next();
 674     /// components.next();
 675     ///
 676     /// assert_eq!(Path::new("foo/bar.txt"), components.as_path());
 677     /// ```
 678     #[stable(feature = "rust1", since = "1.0.0")]
 679     pub fn as_path(&self) -> &'a Path {
 680         let mut comps = self.clone();
 681         if comps.front == State::Body {
 682             comps.trim_left();
 683         }
 684         if comps.back == State::Body {
 685             comps.trim_right();
 686         }
 687         unsafe { Path::from_u8_slice(comps.path) }
 688     }
 689
 690     /// Is the *original* path rooted?
 691     fn has_root(&self) -> bool {
 692         if self.has_physical_root {
 693             return true;
 694         }
 695         if let Some(p) = self.prefix {
 696             if p.has_implicit_root() {
 697                 return true;
 698             }
 699         }
 700         false
 701     }
 702
 703     /// Should the normalized path include a leading . ?
 704     fn include_cur_dir(&self) -> bool {
 705         if self.has_root() {
 706             return false;
 707         }
 708         let mut iter = self.path[self.prefix_len()..].iter();
 709         match (iter.next(), iter.next()) {
 710             (Some(&b'.'), None) => true,
 711             (Some(&b'.'), Some(&b)) => self.is_sep_byte(b),
 712             _ => false,
 713         }
 714     }
 715
 716     // parse a given byte sequence into the corresponding path component
 717     fn parse_single_component<'b>(&self, comp: &'b [u8]) -> Option<Component<'b>> {
 718         match comp {
 719             b"." if self.prefix_verbatim() => Some(Component::CurDir),
 720             b"." => None, // . components are normalized away, except at
 721             // the beginning of a path, which is treated
 722             // separately via `include_cur_dir`
 723             b".." => Some(Component::ParentDir),
 724             b"" => None,
 725             _ => Some(Component::Normal(unsafe { u8_slice_as_os_str(comp) })),
 726         }
 727     }
 728
 729     // parse a component from the left, saying how many bytes to consume to
 730     // remove the component
 731     fn parse_next_component(&self) -> (usize, Option<Component<'a>>) {
 732         debug_assert!(self.front == State::Body);
 733         let (extra, comp) = match self.path.iter().position(|b| self.is_sep_byte(*b)) {
 734             None => (0, self.path),
 735             Some(i) => (1, &self.path[..i]),
 736         };
 737         (comp.len() + extra, self.parse_single_component(comp))
 738     }
 739
 740     // parse a component from the right, saying how many bytes to consume to
 741     // remove the component
 742     fn parse_next_component_back(&self) -> (usize, Option<Component<'a>>) {
 743         debug_assert!(self.back == State::Body);
 744         let start = self.len_before_body();
 745         let (extra, comp) = match self.path[start..].iter().rposition(|b| self.is_sep_byte(*b)) {
 746             None => (0, &self.path[start..]),
 747             Some(i) => (1, &self.path[start + i + 1..]),
 748         };
 749         (comp.len() + extra, self.parse_single_component(comp))
 750     }
 751
 752     // trim away repeated separators (i.e., empty components) on the left
 753     fn trim_left(&mut self) {
 754         while !self.path.is_empty() {
 755             let (size, comp) = self.parse_next_component();
 756             if comp.is_some() {
 757                 return;
 758             } else {
 759                 self.path = &self.path[size..];
 760             }
 761         }
 762     }
 763
 764     // trim away repeated separators (i.e., empty components) on the right
 765     fn trim_right(&mut self) {
 766         while self.path.len() > self.len_before_body() {
 767             let (size, comp) = self.parse_next_component_back();
 768             if comp.is_some() {
 769                 return;
 770             } else {
 771                 self.path = &self.path[..self.path.len() - size];
 772             }
 773         }
 774     }
 775 }
 776
 777 #[stable(feature = "rust1", since = "1.0.0")]
 778 impl AsRef<Path> for Components<'_> {
 779     #[inline]
 780     fn as_ref(&self) -> &Path {
 781         self.as_path()
 782     }
 783 }
 784
 785 #[stable(feature = "rust1", since = "1.0.0")]
 786 impl AsRef<OsStr> for Components<'_> {
 787     #[inline]
 788     fn as_ref(&self) -> &OsStr {
 789         self.as_path().as_os_str()
 790     }
 791 }
 792
 793 #[stable(feature = "path_iter_debug", since = "1.13.0")]
 794 impl fmt::Debug for Iter<'_> {
 795     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 796         struct DebugHelper<'a>(&'a Path);
 797
 798         impl fmt::Debug for DebugHelper<'_> {
 799             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 800                 f.debug_list().entries(self.0.iter()).finish()
 801             }
 802         }
 803
 804         f.debug_tuple("Iter").field(&DebugHelper(self.as_path())).finish()
 805     }
 806 }
 807
 808 impl<'a> Iter<'a> {
 809     /// Extracts a slice corresponding to the portion of the path remaining for iteration.
 810     ///
 811     /// # Examples
 812     ///
 813     /// ```
 814     /// use std::path::Path;
 815     ///
 816     /// let mut iter = Path::new("/tmp/foo/bar.txt").iter();
 817     /// iter.next();
 818     /// iter.next();
 819     ///
 820     /// assert_eq!(Path::new("foo/bar.txt"), iter.as_path());
 821     /// ```
 822     #[stable(feature = "rust1", since = "1.0.0")]
 823     #[inline]
 824     pub fn as_path(&self) -> &'a Path {
 825         self.inner.as_path()
 826     }
 827 }
 828
 829 #[stable(feature = "rust1", since = "1.0.0")]
 830 impl AsRef<Path> for Iter<'_> {
 831     #[inline]
 832     fn as_ref(&self) -> &Path {
 833         self.as_path()
 834     }
 835 }
 836
 837 #[stable(feature = "rust1", since = "1.0.0")]
 838 impl AsRef<OsStr> for Iter<'_> {
 839     #[inline]
 840     fn as_ref(&self) -> &OsStr {
 841         self.as_path().as_os_str()
 842     }
 843 }
 844
 845 #[stable(feature = "rust1", since = "1.0.0")]
 846 impl<'a> Iterator for Iter<'a> {
 847     type Item = &'a OsStr;
 848
 849     #[inline]
 850     fn next(&mut self) -> Option<&'a OsStr> {
 851         self.inner.next().map(Component::as_os_str)
 852     }
 853 }
 854
 855 #[stable(feature = "rust1", since = "1.0.0")]
 856 impl<'a> DoubleEndedIterator for Iter<'a> {
 857     #[inline]
 858     fn next_back(&mut self) -> Option<&'a OsStr> {
 859         self.inner.next_back().map(Component::as_os_str)
 860     }
 861 }
 862
 863 #[stable(feature = "fused", since = "1.26.0")]
 864 impl FusedIterator for Iter<'_> {}
 865
 866 #[stable(feature = "rust1", since = "1.0.0")]
 867 impl<'a> Iterator for Components<'a> {
 868     type Item = Component<'a>;
 869
 870     fn next(&mut self) -> Option<Component<'a>> {
 871         while !self.finished() {
 872             match self.front {
 873                 State::Prefix if self.prefix_len() > 0 => {
 874                     self.front = State::StartDir;
 875                     debug_assert!(self.prefix_len() <= self.path.len());
 876                     let raw = &self.path[..self.prefix_len()];
 877                     self.path = &self.path[self.prefix_len()..];
 878                     return Some(Component::Prefix(PrefixComponent {
 879                         raw: unsafe { u8_slice_as_os_str(raw) },
 880                         parsed: self.prefix.unwrap(),
 881                     }));
 882                 }
 883                 State::Prefix => {
 884                     self.front = State::StartDir;
 885                 }
 886                 State::StartDir => {
 887                     self.front = State::Body;
 888                     if self.has_physical_root {
 889                         debug_assert!(!self.path.is_empty());
 890                         self.path = &self.path[1..];
 891                         return Some(Component::RootDir);
 892                     } else if let Some(p) = self.prefix {
 893                         if p.has_implicit_root() && !p.is_verbatim() {
 894                             return Some(Component::RootDir);
 895                         }
 896                     } else if self.include_cur_dir() {
 897                         debug_assert!(!self.path.is_empty());
 898                         self.path = &self.path[1..];
 899                         return Some(Component::CurDir);
 900                     }
 901                 }
 902                 State::Body if !self.path.is_empty() => {
 903                     let (size, comp) = self.parse_next_component();
 904                     self.path = &self.path[size..];
 905                     if comp.is_some() {
 906                         return comp;
 907                     }
 908                 }
 909                 State::Body => {
 910                     self.front = State::Done;
 911                 }
 912                 State::Done => unreachable!(),
 913             }
 914         }
 915         None
 916     }
 917 }
 918
 919 #[stable(feature = "rust1", since = "1.0.0")]
 920 impl<'a> DoubleEndedIterator for Components<'a> {
 921     fn next_back(&mut self) -> Option<Component<'a>> {
 922         while !self.finished() {
 923             match self.back {
 924                 State::Body if self.path.len() > self.len_before_body() => {
 925                     let (size, comp) = self.parse_next_component_back();
 926                     self.path = &self.path[..self.path.len() - size];
 927                     if comp.is_some() {
 928                         return comp;
 929                     }
 930                 }
 931                 State::Body => {
 932                     self.back = State::StartDir;
 933                 }
 934                 State::StartDir => {
 935                     self.back = State::Prefix;
 936                     if self.has_physical_root {
 937                         self.path = &self.path[..self.path.len() - 1];
 938                         return Some(Component::RootDir);
 939                     } else if let Some(p) = self.prefix {
 940                         if p.has_implicit_root() && !p.is_verbatim() {
 941                             return Some(Component::RootDir);
 942                         }
 943                     } else if self.include_cur_dir() {
 944                         self.path = &self.path[..self.path.len() - 1];
 945                         return Some(Component::CurDir);
 946                     }
 947                 }
 948                 State::Prefix if self.prefix_len() > 0 => {
 949                     self.back = State::Done;
 950                     return Some(Component::Prefix(PrefixComponent {
 951                         raw: unsafe { u8_slice_as_os_str(self.path) },
 952                         parsed: self.prefix.unwrap(),
 953                     }));
 954                 }
 955                 State::Prefix => {
 956                     self.back = State::Done;
 957                     return None;
 958                 }
 959                 State::Done => unreachable!(),
 960             }
 961         }
 962         None
 963     }
 964 }
 965
 966 #[stable(feature = "fused", since = "1.26.0")]
 967 impl FusedIterator for Components<'_> {}
 968
 969 #[stable(feature = "rust1", since = "1.0.0")]
 970 impl<'a> cmp::PartialEq for Components<'a> {
 971     #[inline]
 972     fn eq(&self, other: &Components<'a>) -> bool {
 973         Iterator::eq(self.clone().rev(), other.clone().rev())
 974     }
 975 }
 976
 977 #[stable(feature = "rust1", since = "1.0.0")]
 978 impl cmp::Eq for Components<'_> {}
 979
 980 #[stable(feature = "rust1", since = "1.0.0")]
 981 impl<'a> cmp::PartialOrd for Components<'a> {
 982     #[inline]
 983     fn partial_cmp(&self, other: &Components<'a>) -> Option<cmp::Ordering> {
 984         Some(compare_components(self.clone(), other.clone()))
 985     }
 986 }
 987
 988 #[stable(feature = "rust1", since = "1.0.0")]
 989 impl cmp::Ord for Components<'_> {
 990     #[inline]
 991     fn cmp(&self, other: &Self) -> cmp::Ordering {
 992         compare_components(self.clone(), other.clone())
 993     }
 994 }
 995
 996 fn compare_components(mut left: Components<'_>, mut right: Components<'_>) -> cmp::Ordering {
 997     // Fast path for long shared prefixes
 998     //
 999     // - compare raw bytes to find first mismatch
1000     // - backtrack to find separator before mismatch to avoid ambiguous parsings of '.' or '..' characters
1001     // - if found update state to only do a component-wise comparison on the remainder,
1002     //   otherwise do it on the full path
1003     //
1004     // The fast path isn't taken for paths with a PrefixComponent to avoid backtracking into
1005     // the middle of one
1006     if left.prefix.is_none() && right.prefix.is_none() && left.front == right.front {
1007         // this might benefit from a [u8]::first_mismatch simd implementation, if it existed
1008         let first_difference =
1009             match left.path.iter().zip(right.path.iter()).position(|(&a, &b)| a != b) {
1010                 None if left.path.len() == right.path.len() => return cmp::Ordering::Equal,
1011                 None => left.path.len().min(right.path.len()),
1012                 Some(diff) => diff,
1013             };
1014
1015         if let Some(previous_sep) =
1016             left.path[..first_difference].iter().rposition(|&b| left.is_sep_byte(b))
1017         {
1018             let mismatched_component_start = previous_sep + 1;
1019             left.path = &left.path[mismatched_component_start..];
1020             left.front = State::Body;
1021             right.path = &right.path[mismatched_component_start..];
1022             right.front = State::Body;
1023         }
1024     }
1025
1026     Iterator::cmp(left, right)
1027 }
1028
1029 /// An iterator over [`Path`] and its ancestors.
1030 ///
1031 /// This `struct` is created by the [`ancestors`] method on [`Path`].
1032 /// See its documentation for more.
1033 ///
1034 /// # Examples
1035 ///
1036 /// ```
1037 /// use std::path::Path;
1038 ///
1039 /// let path = Path::new("/foo/bar");
1040 ///
1041 /// for ancestor in path.ancestors() {
1042 ///     println!("{}", ancestor.display());
1043 /// }
1044 /// ```
1045 ///
1046 /// [`ancestors`]: Path::ancestors
1047 #[derive(Copy, Clone, Debug)]
1048 #[stable(feature = "path_ancestors", since = "1.28.0")]
1049 pub struct Ancestors<'a> {
1050     next: Option<&'a Path>,
1051 }
1052
1053 #[stable(feature = "path_ancestors", since = "1.28.0")]
1054 impl<'a> Iterator for Ancestors<'a> {
1055     type Item = &'a Path;
1056
1057     #[inline]
1058     fn next(&mut self) -> Option<Self::Item> {
1059         let next = self.next;
1060         self.next = next.and_then(Path::parent);
1061         next
1062     }
1063 }
1064
1065 #[stable(feature = "path_ancestors", since = "1.28.0")]
1066 impl FusedIterator for Ancestors<'_> {}
1067
1068 ////////////////////////////////////////////////////////////////////////////////
1069 // Basic types and traits
1070 ////////////////////////////////////////////////////////////////////////////////
1071
1072 /// An owned, mutable path (akin to [`String`]).
1073 ///
1074 /// This type provides methods like [`push`] and [`set_extension`] that mutate
1075 /// the path in place. It also implements [`Deref`] to [`Path`], meaning that
1076 /// all methods on [`Path`] slices are available on `PathBuf` values as well.
1077 ///
1078 /// [`push`]: PathBuf::push
1079 /// [`set_extension`]: PathBuf::set_extension
1080 ///
1081 /// More details about the overall approach can be found in
1082 /// the [module documentation](self).
1083 ///
1084 /// # Examples
1085 ///
1086 /// You can use [`push`] to build up a `PathBuf` from
1087 /// components:
1088 ///
1089 /// ```
1090 /// use std::path::PathBuf;
1091 ///
1092 /// let mut path = PathBuf::new();
1093 ///
1094 /// path.push(r"C:\");
1095 /// path.push("windows");
1096 /// path.push("system32");
1097 ///
1098 /// path.set_extension("dll");
1099 /// ```
1100 ///
1101 /// However, [`push`] is best used for dynamic situations. This is a better way
1102 /// to do this when you know all of the components ahead of time:
1103 ///
1104 /// ```
1105 /// use std::path::PathBuf;
1106 ///
1107 /// let path: PathBuf = [r"C:\", "windows", "system32.dll"].iter().collect();
1108 /// ```
1109 ///
1110 /// We can still do better than this! Since these are all strings, we can use
1111 /// `From::from`:
1112 ///
1113 /// ```
1114 /// use std::path::PathBuf;
1115 ///
1116 /// let path = PathBuf::from(r"C:\windows\system32.dll");
1117 /// ```
1118 ///
1119 /// Which method works best depends on what kind of situation you're in.
1120 #[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")]
1121 #[stable(feature = "rust1", since = "1.0.0")]
1122 // FIXME:
1123 // `PathBuf::as_mut_vec` current implementation relies
1124 // on `PathBuf` being layout-compatible with `Vec<u8>`.
1125 // When attribute privacy is implemented, `PathBuf` should be annotated as `#[repr(transparent)]`.
1126 // Anyway, `PathBuf` representation and layout are considered implementation detail, are
1127 // not documented and must not be relied upon.
1128 pub struct PathBuf {
1129     inner: OsString,
1130 }
1131
1132 impl PathBuf {
1133     #[inline]
1134     fn as_mut_vec(&mut self) -> &mut Vec<u8> {
1135         unsafe { &mut *(self as *mut PathBuf as *mut Vec<u8>) }
1136     }
1137
1138     /// Allocates an empty `PathBuf`.
1139     ///
1140     /// # Examples
1141     ///
1142     /// ```
1143     /// use std::path::PathBuf;
1144     ///
1145     /// let path = PathBuf::new();
1146     /// ```
1147     #[stable(feature = "rust1", since = "1.0.0")]
1148     #[must_use]
1149     #[inline]
1150     pub fn new() -> PathBuf {
1151         PathBuf { inner: OsString::new() }
1152     }
1153
1154     /// Creates a new `PathBuf` with a given capacity used to create the
1155     /// internal [`OsString`]. See [`with_capacity`] defined on [`OsString`].
1156     ///
1157     /// # Examples
1158     ///
1159     /// ```
1160     /// use std::path::PathBuf;
1161     ///
1162     /// let mut path = PathBuf::with_capacity(10);
1163     /// let capacity = path.capacity();
1164     ///
1165     /// // This push is done without reallocating
1166     /// path.push(r"C:\");
1167     ///
1168     /// assert_eq!(capacity, path.capacity());
1169     /// ```
1170     ///
1171     /// [`with_capacity`]: OsString::with_capacity
1172     #[stable(feature = "path_buf_capacity", since = "1.44.0")]
1173     #[must_use]
1174     #[inline]
1175     pub fn with_capacity(capacity: usize) -> PathBuf {
1176         PathBuf { inner: OsString::with_capacity(capacity) }
1177     }
1178
1179     /// Coerces to a [`Path`] slice.
1180     ///
1181     /// # Examples
1182     ///
1183     /// ```
1184     /// use std::path::{Path, PathBuf};
1185     ///
1186     /// let p = PathBuf::from("/test");
1187     /// assert_eq!(Path::new("/test"), p.as_path());
1188     /// ```
1189     #[stable(feature = "rust1", since = "1.0.0")]
1190     #[inline]
1191     pub fn as_path(&self) -> &Path {
1192         self
1193     }
1194
1195     /// Extends `self` with `path`.
1196     ///
1197     /// If `path` is absolute, it replaces the current path.
1198     ///
1199     /// On Windows:
1200     ///
1201     /// * if `path` has a root but no prefix (e.g., `\windows`), it
1202     ///   replaces everything except for the prefix (if any) of `self`.
1203     /// * if `path` has a prefix but no root, it replaces `self`.
1204     ///
1205     /// # Examples
1206     ///
1207     /// Pushing a relative path extends the existing path:
1208     ///
1209     /// ```
1210     /// use std::path::PathBuf;
1211     ///
1212     /// let mut path = PathBuf::from("/tmp");
1213     /// path.push("file.bk");
1214     /// assert_eq!(path, PathBuf::from("/tmp/file.bk"));
1215     /// ```
1216     ///
1217     /// Pushing an absolute path replaces the existing path:
1218     ///
1219     /// ```
1220     /// use std::path::PathBuf;
1221     ///
1222     /// let mut path = PathBuf::from("/tmp");
1223     /// path.push("/etc");
1224     /// assert_eq!(path, PathBuf::from("/etc"));
1225     /// ```
1226     #[stable(feature = "rust1", since = "1.0.0")]
1227     pub fn push<P: AsRef<Path>>(&mut self, path: P) {
1228         self._push(path.as_ref())
1229     }
1230
1231     fn _push(&mut self, path: &Path) {
1232         // in general, a separator is needed if the rightmost byte is not a separator
1233         let mut need_sep = self.as_mut_vec().last().map(|c| !is_sep_byte(*c)).unwrap_or(false);
1234
1235         // in the special case of `C:` on Windows, do *not* add a separator
1236         let comps = self.components();
1237
1238         if comps.prefix_len() > 0
1239             && comps.prefix_len() == comps.path.len()
1240             && comps.prefix.unwrap().is_drive()
1241         {
1242             need_sep = false
1243         }
1244
1245         // absolute `path` replaces `self`
1246         if path.is_absolute() || path.prefix().is_some() {
1247             self.as_mut_vec().truncate(0);
1248
1249         // verbatim paths need . and .. removed
1250         } else if comps.prefix_verbatim() {
1251             let mut buf: Vec<_> = comps.collect();
1252             for c in path.components() {
1253                 match c {
1254                     Component::RootDir => {
1255                         buf.truncate(1);
1256                         buf.push(c);
1257                     }
1258                     Component::CurDir => (),
1259                     Component::ParentDir => {
1260                         if let Some(Component::Normal(_)) = buf.last() {
1261                             buf.pop();
1262                         }
1263                     }
1264                     _ => buf.push(c),
1265                 }
1266             }
1267
1268             let mut res = OsString::new();
1269             let mut need_sep = false;
1270
1271             for c in buf {
1272                 if need_sep && c != Component::RootDir {
1273                     res.push(MAIN_SEP_STR);
1274                 }
1275                 res.push(c.as_os_str());
1276
1277                 need_sep = match c {
1278                     Component::RootDir => false,
1279                     Component::Prefix(prefix) => {
1280                         !prefix.parsed.is_drive() && prefix.parsed.len() > 0
1281                     }
1282                     _ => true,
1283                 }
1284             }
1285
1286             self.inner = res;
1287             return;
1288
1289         // `path` has a root but no prefix, e.g., `\windows` (Windows only)
1290         } else if path.has_root() {
1291             let prefix_len = self.components().prefix_remaining();
1292             self.as_mut_vec().truncate(prefix_len);
1293
1294         // `path` is a pure relative path
1295         } else if need_sep {
1296             self.inner.push(MAIN_SEP_STR);
1297         }
1298
1299         self.inner.push(path);
1300     }
1301
1302     /// Truncates `self` to [`self.parent`].
1303     ///
1304     /// Returns `false` and does nothing if [`self.parent`] is [`None`].
1305     /// Otherwise, returns `true`.
1306     ///
1307     /// [`self.parent`]: Path::parent
1308     ///
1309     /// # Examples
1310     ///
1311     /// ```
1312     /// use std::path::{Path, PathBuf};
1313     ///
1314     /// let mut p = PathBuf::from("/spirited/away.rs");
1315     ///
1316     /// p.pop();
1317     /// assert_eq!(Path::new("/spirited"), p);
1318     /// p.pop();
1319     /// assert_eq!(Path::new("/"), p);
1320     /// ```
1321     #[stable(feature = "rust1", since = "1.0.0")]
1322     pub fn pop(&mut self) -> bool {
1323         match self.parent().map(|p| p.as_u8_slice().len()) {
1324             Some(len) => {
1325                 self.as_mut_vec().truncate(len);
1326                 true
1327             }
1328             None => false,
1329         }
1330     }
1331
1332     /// Updates [`self.file_name`] to `file_name`.
1333     ///
1334     /// If [`self.file_name`] was [`None`], this is equivalent to pushing
1335     /// `file_name`.
1336     ///
1337     /// Otherwise it is equivalent to calling [`pop`] and then pushing
1338     /// `file_name`. The new path will be a sibling of the original path.
1339     /// (That is, it will have the same parent.)
1340     ///
1341     /// [`self.file_name`]: Path::file_name
1342     /// [`pop`]: PathBuf::pop
1343     ///
1344     /// # Examples
1345     ///
1346     /// ```
1347     /// use std::path::PathBuf;
1348     ///
1349     /// let mut buf = PathBuf::from("/");
1350     /// assert!(buf.file_name() == None);
1351     /// buf.set_file_name("bar");
1352     /// assert!(buf == PathBuf::from("/bar"));
1353     /// assert!(buf.file_name().is_some());
1354     /// buf.set_file_name("baz.txt");
1355     /// assert!(buf == PathBuf::from("/baz.txt"));
1356     /// ```
1357     #[stable(feature = "rust1", since = "1.0.0")]
1358     pub fn set_file_name<S: AsRef<OsStr>>(&mut self, file_name: S) {
1359         self._set_file_name(file_name.as_ref())
1360     }
1361
1362     fn _set_file_name(&mut self, file_name: &OsStr) {
1363         if self.file_name().is_some() {
1364             let popped = self.pop();
1365             debug_assert!(popped);
1366         }
1367         self.push(file_name);
1368     }
1369
1370     /// Updates [`self.extension`] to `extension`.
1371     ///
1372     /// Returns `false` and does nothing if [`self.file_name`] is [`None`],
1373     /// returns `true` and updates the extension otherwise.
1374     ///
1375     /// If [`self.extension`] is [`None`], the extension is added; otherwise
1376     /// it is replaced.
1377     ///
1378     /// [`self.file_name`]: Path::file_name
1379     /// [`self.extension`]: Path::extension
1380     ///
1381     /// # Examples
1382     ///
1383     /// ```
1384     /// use std::path::{Path, PathBuf};
1385     ///
1386     /// let mut p = PathBuf::from("/feel/the");
1387     ///
1388     /// p.set_extension("force");
1389     /// assert_eq!(Path::new("/feel/the.force"), p.as_path());
1390     ///
1391     /// p.set_extension("dark_side");
1392     /// assert_eq!(Path::new("/feel/the.dark_side"), p.as_path());
1393     /// ```
1394     #[stable(feature = "rust1", since = "1.0.0")]
1395     pub fn set_extension<S: AsRef<OsStr>>(&mut self, extension: S) -> bool {
1396         self._set_extension(extension.as_ref())
1397     }
1398
1399     fn _set_extension(&mut self, extension: &OsStr) -> bool {
1400         let file_stem = match self.file_stem() {
1401             None => return false,
1402             Some(f) => os_str_as_u8_slice(f),
1403         };
1404
1405         // truncate until right after the file stem
1406         let end_file_stem = file_stem[file_stem.len()..].as_ptr() as usize;
1407         let start = os_str_as_u8_slice(&self.inner).as_ptr() as usize;
1408         let v = self.as_mut_vec();
1409         v.truncate(end_file_stem.wrapping_sub(start));
1410
1411         // add the new extension, if any
1412         let new = os_str_as_u8_slice(extension);
1413         if !new.is_empty() {
1414             v.reserve_exact(new.len() + 1);
1415             v.push(b'.');
1416             v.extend_from_slice(new);
1417         }
1418
1419         true
1420     }
1421
1422     /// Consumes the `PathBuf`, yielding its internal [`OsString`] storage.
1423     ///
1424     /// # Examples
1425     ///
1426     /// ```
1427     /// use std::path::PathBuf;
1428     ///
1429     /// let p = PathBuf::from("/the/head");
1430     /// let os_str = p.into_os_string();
1431     /// ```
1432     #[stable(feature = "rust1", since = "1.0.0")]
1433     #[inline]
1434     pub fn into_os_string(self) -> OsString {
1435         self.inner
1436     }
1437
1438     /// Converts this `PathBuf` into a [boxed](Box) [`Path`].
1439     #[stable(feature = "into_boxed_path", since = "1.20.0")]
1440     #[inline]
1441     pub fn into_boxed_path(self) -> Box<Path> {
1442         let rw = Box::into_raw(self.inner.into_boxed_os_str()) as *mut Path;
1443         unsafe { Box::from_raw(rw) }
1444     }
1445
1446     /// Invokes [`capacity`] on the underlying instance of [`OsString`].
1447     ///
1448     /// [`capacity`]: OsString::capacity
1449     #[stable(feature = "path_buf_capacity", since = "1.44.0")]
1450     #[inline]
1451     pub fn capacity(&self) -> usize {
1452         self.inner.capacity()
1453     }
1454
1455     /// Invokes [`clear`] on the underlying instance of [`OsString`].
1456     ///
1457     /// [`clear`]: OsString::clear
1458     #[stable(feature = "path_buf_capacity", since = "1.44.0")]
1459     #[inline]
1460     pub fn clear(&mut self) {
1461         self.inner.clear()
1462     }
1463
1464     /// Invokes [`reserve`] on the underlying instance of [`OsString`].
1465     ///
1466     /// [`reserve`]: OsString::reserve
1467     #[stable(feature = "path_buf_capacity", since = "1.44.0")]
1468     #[inline]
1469     pub fn reserve(&mut self, additional: usize) {
1470         self.inner.reserve(additional)
1471     }
1472
1473     /// Invokes [`reserve_exact`] on the underlying instance of [`OsString`].
1474     ///
1475     /// [`reserve_exact`]: OsString::reserve_exact
1476     #[stable(feature = "path_buf_capacity", since = "1.44.0")]
1477     #[inline]
1478     pub fn reserve_exact(&mut self, additional: usize) {
1479         self.inner.reserve_exact(additional)
1480     }
1481
1482     /// Invokes [`shrink_to_fit`] on the underlying instance of [`OsString`].
1483     ///
1484     /// [`shrink_to_fit`]: OsString::shrink_to_fit
1485     #[stable(feature = "path_buf_capacity", since = "1.44.0")]
1486     #[inline]
1487     pub fn shrink_to_fit(&mut self) {
1488         self.inner.shrink_to_fit()
1489     }
1490
1491     /// Invokes [`shrink_to`] on the underlying instance of [`OsString`].
1492     ///
1493     /// [`shrink_to`]: OsString::shrink_to
1494     #[stable(feature = "shrink_to", since = "1.56.0")]
1495     #[inline]
1496     pub fn shrink_to(&mut self, min_capacity: usize) {
1497         self.inner.shrink_to(min_capacity)
1498     }
1499 }
1500
1501 #[stable(feature = "rust1", since = "1.0.0")]
1502 impl Clone for PathBuf {
1503     #[inline]
1504     fn clone(&self) -> Self {
1505         PathBuf { inner: self.inner.clone() }
1506     }
1507
1508     #[inline]
1509     fn clone_from(&mut self, source: &Self) {
1510         self.inner.clone_from(&source.inner)
1511     }
1512 }
1513
1514 #[stable(feature = "box_from_path", since = "1.17.0")]
1515 impl From<&Path> for Box<Path> {
1516     /// Creates a boxed [`Path`] from a reference.
1517     ///
1518     /// This will allocate and clone `path` to it.
1519     fn from(path: &Path) -> Box<Path> {
1520         let boxed: Box<OsStr> = path.inner.into();
1521         let rw = Box::into_raw(boxed) as *mut Path;
1522         unsafe { Box::from_raw(rw) }
1523     }
1524 }
1525
1526 #[stable(feature = "box_from_cow", since = "1.45.0")]
1527 impl From<Cow<'_, Path>> for Box<Path> {
1528     /// Creates a boxed [`Path`] from a clone-on-write pointer.
1529     ///
1530     /// Converting from a `Cow::Owned` does not clone or allocate.
1531     #[inline]
1532     fn from(cow: Cow<'_, Path>) -> Box<Path> {
1533         match cow {
1534             Cow::Borrowed(path) => Box::from(path),
1535             Cow::Owned(path) => Box::from(path),
1536         }
1537     }
1538 }
1539
1540 #[stable(feature = "path_buf_from_box", since = "1.18.0")]
1541 impl From<Box<Path>> for PathBuf {
1542     /// Converts a `Box<Path>` into a `PathBuf`
1543     ///
1544     /// This conversion does not allocate or copy memory.
1545     #[inline]
1546     fn from(boxed: Box<Path>) -> PathBuf {
1547         boxed.into_path_buf()
1548     }
1549 }
1550
1551 #[stable(feature = "box_from_path_buf", since = "1.20.0")]
1552 impl From<PathBuf> for Box<Path> {
1553     /// Converts a `PathBuf` into a `Box<Path>`
1554     ///
1555     /// This conversion currently should not allocate memory,
1556     /// but this behavior is not guaranteed on all platforms or in all future versions.
1557     #[inline]
1558     fn from(p: PathBuf) -> Box<Path> {
1559         p.into_boxed_path()
1560     }
1561 }
1562
1563 #[stable(feature = "more_box_slice_clone", since = "1.29.0")]
1564 impl Clone for Box<Path> {
1565     #[inline]
1566     fn clone(&self) -> Self {
1567         self.to_path_buf().into_boxed_path()
1568     }
1569 }
1570
1571 #[stable(feature = "rust1", since = "1.0.0")]
1572 impl<T: ?Sized + AsRef<OsStr>> From<&T> for PathBuf {
1573     /// Converts a borrowed `OsStr` to a `PathBuf`.
1574     ///
1575     /// Allocates a [`PathBuf`] and copies the data into it.
1576     #[inline]
1577     fn from(s: &T) -> PathBuf {
1578         PathBuf::from(s.as_ref().to_os_string())
1579     }
1580 }
1581
1582 #[stable(feature = "rust1", since = "1.0.0")]
1583 impl From<OsString> for PathBuf {
1584     /// Converts an [`OsString`] into a [`PathBuf`]
1585     ///
1586     /// This conversion does not allocate or copy memory.
1587     #[inline]
1588     fn from(s: OsString) -> PathBuf {
1589         PathBuf { inner: s }
1590     }
1591 }
1592
1593 #[stable(feature = "from_path_buf_for_os_string", since = "1.14.0")]
1594 impl From<PathBuf> for OsString {
1595     /// Converts a [`PathBuf`] into an [`OsString`]
1596     ///
1597     /// This conversion does not allocate or copy memory.
1598     #[inline]
1599     fn from(path_buf: PathBuf) -> OsString {
1600         path_buf.inner
1601     }
1602 }
1603
1604 #[stable(feature = "rust1", since = "1.0.0")]
1605 impl From<String> for PathBuf {
1606     /// Converts a [`String`] into a [`PathBuf`]
1607     ///
1608     /// This conversion does not allocate or copy memory.
1609     #[inline]
1610     fn from(s: String) -> PathBuf {
1611         PathBuf::from(OsString::from(s))
1612     }
1613 }
1614
1615 #[stable(feature = "path_from_str", since = "1.32.0")]
1616 impl FromStr for PathBuf {
1617     type Err = core::convert::Infallible;
1618
1619     #[inline]
1620     fn from_str(s: &str) -> Result<Self, Self::Err> {
1621         Ok(PathBuf::from(s))
1622     }
1623 }
1624
1625 #[stable(feature = "rust1", since = "1.0.0")]
1626 impl<P: AsRef<Path>> iter::FromIterator<P> for PathBuf {
1627     fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> PathBuf {
1628         let mut buf = PathBuf::new();
1629         buf.extend(iter);
1630         buf
1631     }
1632 }
1633
1634 #[stable(feature = "rust1", since = "1.0.0")]
1635 impl<P: AsRef<Path>> iter::Extend<P> for PathBuf {
1636     fn extend<I: IntoIterator<Item = P>>(&mut self, iter: I) {
1637         iter.into_iter().for_each(move |p| self.push(p.as_ref()));
1638     }
1639
1640     #[inline]
1641     fn extend_one(&mut self, p: P) {
1642         self.push(p.as_ref());
1643     }
1644 }
1645
1646 #[stable(feature = "rust1", since = "1.0.0")]
1647 impl fmt::Debug for PathBuf {
1648     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1649         fmt::Debug::fmt(&**self, formatter)
1650     }
1651 }
1652
1653 #[stable(feature = "rust1", since = "1.0.0")]
1654 impl ops::Deref for PathBuf {
1655     type Target = Path;
1656     #[inline]
1657     fn deref(&self) -> &Path {
1658         Path::new(&self.inner)
1659     }
1660 }
1661
1662 #[stable(feature = "rust1", since = "1.0.0")]
1663 impl Borrow<Path> for PathBuf {
1664     #[inline]
1665     fn borrow(&self) -> &Path {
1666         self.deref()
1667     }
1668 }
1669
1670 #[stable(feature = "default_for_pathbuf", since = "1.17.0")]
1671 impl Default for PathBuf {
1672     #[inline]
1673     fn default() -> Self {
1674         PathBuf::new()
1675     }
1676 }
1677
1678 #[stable(feature = "cow_from_path", since = "1.6.0")]
1679 impl<'a> From<&'a Path> for Cow<'a, Path> {
1680     /// Creates a clone-on-write pointer from a reference to
1681     /// [`Path`].
1682     ///
1683     /// This conversion does not clone or allocate.
1684     #[inline]
1685     fn from(s: &'a Path) -> Cow<'a, Path> {
1686         Cow::Borrowed(s)
1687     }
1688 }
1689
1690 #[stable(feature = "cow_from_path", since = "1.6.0")]
1691 impl<'a> From<PathBuf> for Cow<'a, Path> {
1692     /// Creates a clone-on-write pointer from an owned
1693     /// instance of [`PathBuf`].
1694     ///
1695     /// This conversion does not clone or allocate.
1696     #[inline]
1697     fn from(s: PathBuf) -> Cow<'a, Path> {
1698         Cow::Owned(s)
1699     }
1700 }
1701
1702 #[stable(feature = "cow_from_pathbuf_ref", since = "1.28.0")]
1703 impl<'a> From<&'a PathBuf> for Cow<'a, Path> {
1704     /// Creates a clone-on-write pointer from a reference to
1705     /// [`PathBuf`].
1706     ///
1707     /// This conversion does not clone or allocate.
1708     #[inline]
1709     fn from(p: &'a PathBuf) -> Cow<'a, Path> {
1710         Cow::Borrowed(p.as_path())
1711     }
1712 }
1713
1714 #[stable(feature = "pathbuf_from_cow_path", since = "1.28.0")]
1715 impl<'a> From<Cow<'a, Path>> for PathBuf {
1716     /// Converts a clone-on-write pointer to an owned path.
1717     ///
1718     /// Converting from a `Cow::Owned` does not clone or allocate.
1719     #[inline]
1720     fn from(p: Cow<'a, Path>) -> Self {
1721         p.into_owned()
1722     }
1723 }
1724
1725 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
1726 impl From<PathBuf> for Arc<Path> {
1727     /// Converts a [`PathBuf`] into an [`Arc`] by moving the [`PathBuf`] data into a new [`Arc`] buffer.
1728     #[inline]
1729     fn from(s: PathBuf) -> Arc<Path> {
1730         let arc: Arc<OsStr> = Arc::from(s.into_os_string());
1731         unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Path) }
1732     }
1733 }
1734
1735 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
1736 impl From<&Path> for Arc<Path> {
1737     /// Converts a [`Path`] into an [`Arc`] by copying the [`Path`] data into a new [`Arc`] buffer.
1738     #[inline]
1739     fn from(s: &Path) -> Arc<Path> {
1740         let arc: Arc<OsStr> = Arc::from(s.as_os_str());
1741         unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Path) }
1742     }
1743 }
1744
1745 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
1746 impl From<PathBuf> for Rc<Path> {
1747     /// Converts a [`PathBuf`] into an [`Rc`] by moving the [`PathBuf`] data into a new `Rc` buffer.
1748     #[inline]
1749     fn from(s: PathBuf) -> Rc<Path> {
1750         let rc: Rc<OsStr> = Rc::from(s.into_os_string());
1751         unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Path) }
1752     }
1753 }
1754
1755 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
1756 impl From<&Path> for Rc<Path> {
1757     /// Converts a [`Path`] into an [`Rc`] by copying the [`Path`] data into a new `Rc` buffer.
1758     #[inline]
1759     fn from(s: &Path) -> Rc<Path> {
1760         let rc: Rc<OsStr> = Rc::from(s.as_os_str());
1761         unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Path) }
1762     }
1763 }
1764
1765 #[stable(feature = "rust1", since = "1.0.0")]
1766 impl ToOwned for Path {
1767     type Owned = PathBuf;
1768     #[inline]
1769     fn to_owned(&self) -> PathBuf {
1770         self.to_path_buf()
1771     }
1772     #[inline]
1773     fn clone_into(&self, target: &mut PathBuf) {
1774         self.inner.clone_into(&mut target.inner);
1775     }
1776 }
1777
1778 #[stable(feature = "rust1", since = "1.0.0")]
1779 impl cmp::PartialEq for PathBuf {
1780     #[inline]
1781     fn eq(&self, other: &PathBuf) -> bool {
1782         self.components() == other.components()
1783     }
1784 }
1785
1786 #[stable(feature = "rust1", since = "1.0.0")]
1787 impl Hash for PathBuf {
1788     fn hash<H: Hasher>(&self, h: &mut H) {
1789         self.as_path().hash(h)
1790     }
1791 }
1792
1793 #[stable(feature = "rust1", since = "1.0.0")]
1794 impl cmp::Eq for PathBuf {}
1795
1796 #[stable(feature = "rust1", since = "1.0.0")]
1797 impl cmp::PartialOrd for PathBuf {
1798     #[inline]
1799     fn partial_cmp(&self, other: &PathBuf) -> Option<cmp::Ordering> {
1800         Some(compare_components(self.components(), other.components()))
1801     }
1802 }
1803
1804 #[stable(feature = "rust1", since = "1.0.0")]
1805 impl cmp::Ord for PathBuf {
1806     #[inline]
1807     fn cmp(&self, other: &PathBuf) -> cmp::Ordering {
1808         compare_components(self.components(), other.components())
1809     }
1810 }
1811
1812 #[stable(feature = "rust1", since = "1.0.0")]
1813 impl AsRef<OsStr> for PathBuf {
1814     #[inline]
1815     fn as_ref(&self) -> &OsStr {
1816         &self.inner[..]
1817     }
1818 }
1819
1820 /// A slice of a path (akin to [`str`]).
1821 ///
1822 /// This type supports a number of operations for inspecting a path, including
1823 /// breaking the path into its components (separated by `/` on Unix and by either
1824 /// `/` or `\` on Windows), extracting the file name, determining whether the path
1825 /// is absolute, and so on.
1826 ///
1827 /// This is an *unsized* type, meaning that it must always be used behind a
1828 /// pointer like `&` or [`Box`]. For an owned version of this type,
1829 /// see [`PathBuf`].
1830 ///
1831 /// More details about the overall approach can be found in
1832 /// the [module documentation](self).
1833 ///
1834 /// # Examples
1835 ///
1836 /// ```
1837 /// use std::path::Path;
1838 /// use std::ffi::OsStr;
1839 ///
1840 /// // Note: this example does work on Windows
1841 /// let path = Path::new("./foo/bar.txt");
1842 ///
1843 /// let parent = path.parent();
1844 /// assert_eq!(parent, Some(Path::new("./foo")));
1845 ///
1846 /// let file_stem = path.file_stem();
1847 /// assert_eq!(file_stem, Some(OsStr::new("bar")));
1848 ///
1849 /// let extension = path.extension();
1850 /// assert_eq!(extension, Some(OsStr::new("txt")));
1851 /// ```
1852 #[cfg_attr(not(test), rustc_diagnostic_item = "Path")]
1853 #[stable(feature = "rust1", since = "1.0.0")]
1854 // FIXME:
1855 // `Path::new` current implementation relies
1856 // on `Path` being layout-compatible with `OsStr`.
1857 // When attribute privacy is implemented, `Path` should be annotated as `#[repr(transparent)]`.
1858 // Anyway, `Path` representation and layout are considered implementation detail, are
1859 // not documented and must not be relied upon.
1860 pub struct Path {
1861     inner: OsStr,
1862 }
1863
1864 /// An error returned from [`Path::strip_prefix`] if the prefix was not found.
1865 ///
1866 /// This `struct` is created by the [`strip_prefix`] method on [`Path`].
1867 /// See its documentation for more.
1868 ///
1869 /// [`strip_prefix`]: Path::strip_prefix
1870 #[derive(Debug, Clone, PartialEq, Eq)]
1871 #[stable(since = "1.7.0", feature = "strip_prefix")]
1872 pub struct StripPrefixError(());
1873
1874 impl Path {
1875     // The following (private!) function allows construction of a path from a u8
1876     // slice, which is only safe when it is known to follow the OsStr encoding.
1877     unsafe fn from_u8_slice(s: &[u8]) -> &Path {
1878         unsafe { Path::new(u8_slice_as_os_str(s)) }
1879     }
1880     // The following (private!) function reveals the byte encoding used for OsStr.
1881     fn as_u8_slice(&self) -> &[u8] {
1882         os_str_as_u8_slice(&self.inner)
1883     }
1884
1885     /// Directly wraps a string slice as a `Path` slice.
1886     ///
1887     /// This is a cost-free conversion.
1888     ///
1889     /// # Examples
1890     ///
1891     /// ```
1892     /// use std::path::Path;
1893     ///
1894     /// Path::new("foo.txt");
1895     /// ```
1896     ///
1897     /// You can create `Path`s from `String`s, or even other `Path`s:
1898     ///
1899     /// ```
1900     /// use std::path::Path;
1901     ///
1902     /// let string = String::from("foo.txt");
1903     /// let from_string = Path::new(&string);
1904     /// let from_path = Path::new(&from_string);
1905     /// assert_eq!(from_string, from_path);
1906     /// ```
1907     #[stable(feature = "rust1", since = "1.0.0")]
1908     pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &Path {
1909         unsafe { &*(s.as_ref() as *const OsStr as *const Path) }
1910     }
1911
1912     /// Yields the underlying [`OsStr`] slice.
1913     ///
1914     /// # Examples
1915     ///
1916     /// ```
1917     /// use std::path::Path;
1918     ///
1919     /// let os_str = Path::new("foo.txt").as_os_str();
1920     /// assert_eq!(os_str, std::ffi::OsStr::new("foo.txt"));
1921     /// ```
1922     #[stable(feature = "rust1", since = "1.0.0")]
1923     #[inline]
1924     pub fn as_os_str(&self) -> &OsStr {
1925         &self.inner
1926     }
1927
1928     /// Yields a [`&str`] slice if the `Path` is valid unicode.
1929     ///
1930     /// This conversion may entail doing a check for UTF-8 validity.
1931     /// Note that validation is performed because non-UTF-8 strings are
1932     /// perfectly valid for some OS.
1933     ///
1934     /// [`&str`]: str
1935     ///
1936     /// # Examples
1937     ///
1938     /// ```
1939     /// use std::path::Path;
1940     ///
1941     /// let path = Path::new("foo.txt");
1942     /// assert_eq!(path.to_str(), Some("foo.txt"));
1943     /// ```
1944     #[stable(feature = "rust1", since = "1.0.0")]
1945     #[inline]
1946     pub fn to_str(&self) -> Option<&str> {
1947         self.inner.to_str()
1948     }
1949
1950     /// Converts a `Path` to a [`Cow<str>`].
1951     ///
1952     /// Any non-Unicode sequences are replaced with
1953     /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD].
1954     ///
1955     /// [U+FFFD]: super::char::REPLACEMENT_CHARACTER
1956     ///
1957     /// # Examples
1958     ///
1959     /// Calling `to_string_lossy` on a `Path` with valid unicode:
1960     ///
1961     /// ```
1962     /// use std::path::Path;
1963     ///
1964     /// let path = Path::new("foo.txt");
1965     /// assert_eq!(path.to_string_lossy(), "foo.txt");
1966     /// ```
1967     ///
1968     /// Had `path` contained invalid unicode, the `to_string_lossy` call might
1969     /// have returned `"fo�.txt"`.
1970     #[stable(feature = "rust1", since = "1.0.0")]
1971     #[inline]
1972     pub fn to_string_lossy(&self) -> Cow<'_, str> {
1973         self.inner.to_string_lossy()
1974     }
1975
1976     /// Converts a `Path` to an owned [`PathBuf`].
1977     ///
1978     /// # Examples
1979     ///
1980     /// ```
1981     /// use std::path::Path;
1982     ///
1983     /// let path_buf = Path::new("foo.txt").to_path_buf();
1984     /// assert_eq!(path_buf, std::path::PathBuf::from("foo.txt"));
1985     /// ```
1986     #[rustc_conversion_suggestion]
1987     #[stable(feature = "rust1", since = "1.0.0")]
1988     pub fn to_path_buf(&self) -> PathBuf {
1989         PathBuf::from(self.inner.to_os_string())
1990     }
1991
1992     /// Returns `true` if the `Path` is absolute, i.e., if it is independent of
1993     /// the current directory.
1994     ///
1995     /// * On Unix, a path is absolute if it starts with the root, so
1996     /// `is_absolute` and [`has_root`] are equivalent.
1997     ///
1998     /// * On Windows, a path is absolute if it has a prefix and starts with the
1999     /// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not.
2000     ///
2001     /// # Examples
2002     ///
2003     /// ```
2004     /// use std::path::Path;
2005     ///
2006     /// assert!(!Path::new("foo.txt").is_absolute());
2007     /// ```
2008     ///
2009     /// [`has_root`]: Path::has_root
2010     #[stable(feature = "rust1", since = "1.0.0")]
2011     #[allow(deprecated)]
2012     pub fn is_absolute(&self) -> bool {
2013         if cfg!(target_os = "redox") {
2014             // FIXME: Allow Redox prefixes
2015             self.has_root() || has_redox_scheme(self.as_u8_slice())
2016         } else {
2017             self.has_root() && (cfg!(any(unix, target_os = "wasi")) || self.prefix().is_some())
2018         }
2019     }
2020
2021     /// Returns `true` if the `Path` is relative, i.e., not absolute.
2022     ///
2023     /// See [`is_absolute`]'s documentation for more details.
2024     ///
2025     /// # Examples
2026     ///
2027     /// ```
2028     /// use std::path::Path;
2029     ///
2030     /// assert!(Path::new("foo.txt").is_relative());
2031     /// ```
2032     ///
2033     /// [`is_absolute`]: Path::is_absolute
2034     #[stable(feature = "rust1", since = "1.0.0")]
2035     #[inline]
2036     pub fn is_relative(&self) -> bool {
2037         !self.is_absolute()
2038     }
2039
2040     fn prefix(&self) -> Option<Prefix<'_>> {
2041         self.components().prefix
2042     }
2043
2044     /// Returns `true` if the `Path` has a root.
2045     ///
2046     /// * On Unix, a path has a root if it begins with `/`.
2047     ///
2048     /// * On Windows, a path has a root if it:
2049     ///     * has no prefix and begins with a separator, e.g., `\windows`
2050     ///     * has a prefix followed by a separator, e.g., `c:\windows` but not `c:windows`
2051     ///     * has any non-disk prefix, e.g., `\\server\share`
2052     ///
2053     /// # Examples
2054     ///
2055     /// ```
2056     /// use std::path::Path;
2057     ///
2058     /// assert!(Path::new("/etc/passwd").has_root());
2059     /// ```
2060     #[stable(feature = "rust1", since = "1.0.0")]
2061     #[inline]
2062     pub fn has_root(&self) -> bool {
2063         self.components().has_root()
2064     }
2065
2066     /// Returns the `Path` without its final component, if there is one.
2067     ///
2068     /// Returns [`None`] if the path terminates in a root or prefix.
2069     ///
2070     /// # Examples
2071     ///
2072     /// ```
2073     /// use std::path::Path;
2074     ///
2075     /// let path = Path::new("/foo/bar");
2076     /// let parent = path.parent().unwrap();
2077     /// assert_eq!(parent, Path::new("/foo"));
2078     ///
2079     /// let grand_parent = parent.parent().unwrap();
2080     /// assert_eq!(grand_parent, Path::new("/"));
2081     /// assert_eq!(grand_parent.parent(), None);
2082     /// ```
2083     #[stable(feature = "rust1", since = "1.0.0")]
2084     pub fn parent(&self) -> Option<&Path> {
2085         let mut comps = self.components();
2086         let comp = comps.next_back();
2087         comp.and_then(|p| match p {
2088             Component::Normal(_) | Component::CurDir | Component::ParentDir => {
2089                 Some(comps.as_path())
2090             }
2091             _ => None,
2092         })
2093     }
2094
2095     /// Produces an iterator over `Path` and its ancestors.
2096     ///
2097     /// The iterator will yield the `Path` that is returned if the [`parent`] method is used zero
2098     /// or more times. That means, the iterator will yield `&self`, `&self.parent().unwrap()`,
2099     /// `&self.parent().unwrap().parent().unwrap()` and so on. If the [`parent`] method returns
2100     /// [`None`], the iterator will do likewise. The iterator will always yield at least one value,
2101     /// namely `&self`.
2102     ///
2103     /// # Examples
2104     ///
2105     /// ```
2106     /// use std::path::Path;
2107     ///
2108     /// let mut ancestors = Path::new("/foo/bar").ancestors();
2109     /// assert_eq!(ancestors.next(), Some(Path::new("/foo/bar")));
2110     /// assert_eq!(ancestors.next(), Some(Path::new("/foo")));
2111     /// assert_eq!(ancestors.next(), Some(Path::new("/")));
2112     /// assert_eq!(ancestors.next(), None);
2113     ///
2114     /// let mut ancestors = Path::new("../foo/bar").ancestors();
2115     /// assert_eq!(ancestors.next(), Some(Path::new("../foo/bar")));
2116     /// assert_eq!(ancestors.next(), Some(Path::new("../foo")));
2117     /// assert_eq!(ancestors.next(), Some(Path::new("..")));
2118     /// assert_eq!(ancestors.next(), Some(Path::new("")));
2119     /// assert_eq!(ancestors.next(), None);
2120     /// ```
2121     ///
2122     /// [`parent`]: Path::parent
2123     #[stable(feature = "path_ancestors", since = "1.28.0")]
2124     #[inline]
2125     pub fn ancestors(&self) -> Ancestors<'_> {
2126         Ancestors { next: Some(&self) }
2127     }
2128
2129     /// Returns the final component of the `Path`, if there is one.
2130     ///
2131     /// If the path is a normal file, this is the file name. If it's the path of a directory, this
2132     /// is the directory name.
2133     ///
2134     /// Returns [`None`] if the path terminates in `..`.
2135     ///
2136     /// # Examples
2137     ///
2138     /// ```
2139     /// use std::path::Path;
2140     /// use std::ffi::OsStr;
2141     ///
2142     /// assert_eq!(Some(OsStr::new("bin")), Path::new("/usr/bin/").file_name());
2143     /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("tmp/foo.txt").file_name());
2144     /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.").file_name());
2145     /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.//").file_name());
2146     /// assert_eq!(None, Path::new("foo.txt/..").file_name());
2147     /// assert_eq!(None, Path::new("/").file_name());
2148     /// ```
2149     #[stable(feature = "rust1", since = "1.0.0")]
2150     pub fn file_name(&self) -> Option<&OsStr> {
2151         self.components().next_back().and_then(|p| match p {
2152             Component::Normal(p) => Some(p),
2153             _ => None,
2154         })
2155     }
2156
2157     /// Returns a path that, when joined onto `base`, yields `self`.
2158     ///
2159     /// # Errors
2160     ///
2161     /// If `base` is not a prefix of `self` (i.e., [`starts_with`]
2162     /// returns `false`), returns [`Err`].
2163     ///
2164     /// [`starts_with`]: Path::starts_with
2165     ///
2166     /// # Examples
2167     ///
2168     /// ```
2169     /// use std::path::{Path, PathBuf};
2170     ///
2171     /// let path = Path::new("/test/haha/foo.txt");
2172     ///
2173     /// assert_eq!(path.strip_prefix("/"), Ok(Path::new("test/haha/foo.txt")));
2174     /// assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt")));
2175     /// assert_eq!(path.strip_prefix("/test/"), Ok(Path::new("haha/foo.txt")));
2176     /// assert_eq!(path.strip_prefix("/test/haha/foo.txt"), Ok(Path::new("")));
2177     /// assert_eq!(path.strip_prefix("/test/haha/foo.txt/"), Ok(Path::new("")));
2178     ///
2179     /// assert!(path.strip_prefix("test").is_err());
2180     /// assert!(path.strip_prefix("/haha").is_err());
2181     ///
2182     /// let prefix = PathBuf::from("/test/");
2183     /// assert_eq!(path.strip_prefix(prefix), Ok(Path::new("haha/foo.txt")));
2184     /// ```
2185     #[stable(since = "1.7.0", feature = "path_strip_prefix")]
2186     pub fn strip_prefix<P>(&self, base: P) -> Result<&Path, StripPrefixError>
2187     where
2188         P: AsRef<Path>,
2189     {
2190         self._strip_prefix(base.as_ref())
2191     }
2192
2193     fn _strip_prefix(&self, base: &Path) -> Result<&Path, StripPrefixError> {
2194         iter_after(self.components(), base.components())
2195             .map(|c| c.as_path())
2196             .ok_or(StripPrefixError(()))
2197     }
2198
2199     /// Determines whether `base` is a prefix of `self`.
2200     ///
2201     /// Only considers whole path components to match.
2202     ///
2203     /// # Examples
2204     ///
2205     /// ```
2206     /// use std::path::Path;
2207     ///
2208     /// let path = Path::new("/etc/passwd");
2209     ///
2210     /// assert!(path.starts_with("/etc"));
2211     /// assert!(path.starts_with("/etc/"));
2212     /// assert!(path.starts_with("/etc/passwd"));
2213     /// assert!(path.starts_with("/etc/passwd/")); // extra slash is okay
2214     /// assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay
2215     ///
2216     /// assert!(!path.starts_with("/e"));
2217     /// assert!(!path.starts_with("/etc/passwd.txt"));
2218     ///
2219     /// assert!(!Path::new("/etc/foo.rs").starts_with("/etc/foo"));
2220     /// ```
2221     #[stable(feature = "rust1", since = "1.0.0")]
2222     pub fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool {
2223         self._starts_with(base.as_ref())
2224     }
2225
2226     fn _starts_with(&self, base: &Path) -> bool {
2227         iter_after(self.components(), base.components()).is_some()
2228     }
2229
2230     /// Determines whether `child` is a suffix of `self`.
2231     ///
2232     /// Only considers whole path components to match.
2233     ///
2234     /// # Examples
2235     ///
2236     /// ```
2237     /// use std::path::Path;
2238     ///
2239     /// let path = Path::new("/etc/resolv.conf");
2240     ///
2241     /// assert!(path.ends_with("resolv.conf"));
2242     /// assert!(path.ends_with("etc/resolv.conf"));
2243     /// assert!(path.ends_with("/etc/resolv.conf"));
2244     ///
2245     /// assert!(!path.ends_with("/resolv.conf"));
2246     /// assert!(!path.ends_with("conf")); // use .extension() instead
2247     /// ```
2248     #[stable(feature = "rust1", since = "1.0.0")]
2249     pub fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool {
2250         self._ends_with(child.as_ref())
2251     }
2252
2253     fn _ends_with(&self, child: &Path) -> bool {
2254         iter_after(self.components().rev(), child.components().rev()).is_some()
2255     }
2256
2257     /// Extracts the stem (non-extension) portion of [`self.file_name`].
2258     ///
2259     /// [`self.file_name`]: Path::file_name
2260     ///
2261     /// The stem is:
2262     ///
2263     /// * [`None`], if there is no file name;
2264     /// * The entire file name if there is no embedded `.`;
2265     /// * The entire file name if the file name begins with `.` and has no other `.`s within;
2266     /// * Otherwise, the portion of the file name before the final `.`
2267     ///
2268     /// # Examples
2269     ///
2270     /// ```
2271     /// use std::path::Path;
2272     ///
2273     /// assert_eq!("foo", Path::new("foo.rs").file_stem().unwrap());
2274     /// assert_eq!("foo.tar", Path::new("foo.tar.gz").file_stem().unwrap());
2275     /// ```
2276     ///
2277     /// # See Also
2278     /// This method is similar to [`Path::file_prefix`], which extracts the portion of the file name
2279     /// before the *first* `.`
2280     ///
2281     /// [`Path::file_prefix`]: Path::file_prefix
2282     ///
2283     #[stable(feature = "rust1", since = "1.0.0")]
2284     pub fn file_stem(&self) -> Option<&OsStr> {
2285         self.file_name().map(rsplit_file_at_dot).and_then(|(before, after)| before.or(after))
2286     }
2287
2288     /// Extracts the prefix of [`self.file_name`].
2289     ///
2290     /// The prefix is:
2291     ///
2292     /// * [`None`], if there is no file name;
2293     /// * The entire file name if there is no embedded `.`;
2294     /// * The portion of the file name before the first non-beginning `.`;
2295     /// * The entire file name if the file name begins with `.` and has no other `.`s within;
2296     /// * The portion of the file name before the second `.` if the file name begins with `.`
2297     ///
2298     /// [`self.file_name`]: Path::file_name
2299     ///
2300     /// # Examples
2301     ///
2302     /// ```
2303     /// # #![feature(path_file_prefix)]
2304     /// use std::path::Path;
2305     ///
2306     /// assert_eq!("foo", Path::new("foo.rs").file_prefix().unwrap());
2307     /// assert_eq!("foo", Path::new("foo.tar.gz").file_prefix().unwrap());
2308     /// ```
2309     ///
2310     /// # See Also
2311     /// This method is similar to [`Path::file_stem`], which extracts the portion of the file name
2312     /// before the *last* `.`
2313     ///
2314     /// [`Path::file_stem`]: Path::file_stem
2315     ///
2316     #[unstable(feature = "path_file_prefix", issue = "86319")]
2317     pub fn file_prefix(&self) -> Option<&OsStr> {
2318         self.file_name().map(split_file_at_dot).and_then(|(before, _after)| Some(before))
2319     }
2320
2321     /// Extracts the extension of [`self.file_name`], if possible.
2322     ///
2323     /// The extension is:
2324     ///
2325     /// * [`None`], if there is no file name;
2326     /// * [`None`], if there is no embedded `.`;
2327     /// * [`None`], if the file name begins with `.` and has no other `.`s within;
2328     /// * Otherwise, the portion of the file name after the final `.`
2329     ///
2330     /// [`self.file_name`]: Path::file_name
2331     ///
2332     /// # Examples
2333     ///
2334     /// ```
2335     /// use std::path::Path;
2336     ///
2337     /// assert_eq!("rs", Path::new("foo.rs").extension().unwrap());
2338     /// assert_eq!("gz", Path::new("foo.tar.gz").extension().unwrap());
2339     /// ```
2340     #[stable(feature = "rust1", since = "1.0.0")]
2341     pub fn extension(&self) -> Option<&OsStr> {
2342         self.file_name().map(rsplit_file_at_dot).and_then(|(before, after)| before.and(after))
2343     }
2344
2345     /// Creates an owned [`PathBuf`] with `path` adjoined to `self`.
2346     ///
2347     /// See [`PathBuf::push`] for more details on what it means to adjoin a path.
2348     ///
2349     /// # Examples
2350     ///
2351     /// ```
2352     /// use std::path::{Path, PathBuf};
2353     ///
2354     /// assert_eq!(Path::new("/etc").join("passwd"), PathBuf::from("/etc/passwd"));
2355     /// ```
2356     #[stable(feature = "rust1", since = "1.0.0")]
2357     #[must_use]
2358     pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf {
2359         self._join(path.as_ref())
2360     }
2361
2362     fn _join(&self, path: &Path) -> PathBuf {
2363         let mut buf = self.to_path_buf();
2364         buf.push(path);
2365         buf
2366     }
2367
2368     /// Creates an owned [`PathBuf`] like `self` but with the given file name.
2369     ///
2370     /// See [`PathBuf::set_file_name`] for more details.
2371     ///
2372     /// # Examples
2373     ///
2374     /// ```
2375     /// use std::path::{Path, PathBuf};
2376     ///
2377     /// let path = Path::new("/tmp/foo.txt");
2378     /// assert_eq!(path.with_file_name("bar.txt"), PathBuf::from("/tmp/bar.txt"));
2379     ///
2380     /// let path = Path::new("/tmp");
2381     /// assert_eq!(path.with_file_name("var"), PathBuf::from("/var"));
2382     /// ```
2383     #[stable(feature = "rust1", since = "1.0.0")]
2384     pub fn with_file_name<S: AsRef<OsStr>>(&self, file_name: S) -> PathBuf {
2385         self._with_file_name(file_name.as_ref())
2386     }
2387
2388     fn _with_file_name(&self, file_name: &OsStr) -> PathBuf {
2389         let mut buf = self.to_path_buf();
2390         buf.set_file_name(file_name);
2391         buf
2392     }
2393
2394     /// Creates an owned [`PathBuf`] like `self` but with the given extension.
2395     ///
2396     /// See [`PathBuf::set_extension`] for more details.
2397     ///
2398     /// # Examples
2399     ///
2400     /// ```
2401     /// use std::path::{Path, PathBuf};
2402     ///
2403     /// let path = Path::new("foo.rs");
2404     /// assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt"));
2405     ///
2406     /// let path = Path::new("foo.tar.gz");
2407     /// assert_eq!(path.with_extension(""), PathBuf::from("foo.tar"));
2408     /// assert_eq!(path.with_extension("xz"), PathBuf::from("foo.tar.xz"));
2409     /// assert_eq!(path.with_extension("").with_extension("txt"), PathBuf::from("foo.txt"));
2410     /// ```
2411     #[stable(feature = "rust1", since = "1.0.0")]
2412     pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {
2413         self._with_extension(extension.as_ref())
2414     }
2415
2416     fn _with_extension(&self, extension: &OsStr) -> PathBuf {
2417         let mut buf = self.to_path_buf();
2418         buf.set_extension(extension);
2419         buf
2420     }
2421
2422     /// Produces an iterator over the [`Component`]s of the path.
2423     ///
2424     /// When parsing the path, there is a small amount of normalization:
2425     ///
2426     /// * Repeated separators are ignored, so `a/b` and `a//b` both have
2427     ///   `a` and `b` as components.
2428     ///
2429     /// * Occurrences of `.` are normalized away, except if they are at the
2430     ///   beginning of the path. For example, `a/./b`, `a/b/`, `a/b/.` and
2431     ///   `a/b` all have `a` and `b` as components, but `./a/b` starts with
2432     ///   an additional [`CurDir`] component.
2433     ///
2434     /// * A trailing slash is normalized away, `/a/b` and `/a/b/` are equivalent.
2435     ///
2436     /// Note that no other normalization takes place; in particular, `a/c`
2437     /// and `a/b/../c` are distinct, to account for the possibility that `b`
2438     /// is a symbolic link (so its parent isn't `a`).
2439     ///
2440     /// # Examples
2441     ///
2442     /// ```
2443     /// use std::path::{Path, Component};
2444     /// use std::ffi::OsStr;
2445     ///
2446     /// let mut components = Path::new("/tmp/foo.txt").components();
2447     ///
2448     /// assert_eq!(components.next(), Some(Component::RootDir));
2449     /// assert_eq!(components.next(), Some(Component::Normal(OsStr::new("tmp"))));
2450     /// assert_eq!(components.next(), Some(Component::Normal(OsStr::new("foo.txt"))));
2451     /// assert_eq!(components.next(), None)
2452     /// ```
2453     ///
2454     /// [`CurDir`]: Component::CurDir
2455     #[stable(feature = "rust1", since = "1.0.0")]
2456     pub fn components(&self) -> Components<'_> {
2457         let prefix = parse_prefix(self.as_os_str());
2458         Components {
2459             path: self.as_u8_slice(),
2460             prefix,
2461             has_physical_root: has_physical_root(self.as_u8_slice(), prefix)
2462                 || has_redox_scheme(self.as_u8_slice()),
2463             front: State::Prefix,
2464             back: State::Body,
2465         }
2466     }
2467
2468     /// Produces an iterator over the path's components viewed as [`OsStr`]
2469     /// slices.
2470     ///
2471     /// For more information about the particulars of how the path is separated
2472     /// into components, see [`components`].
2473     ///
2474     /// [`components`]: Path::components
2475     ///
2476     /// # Examples
2477     ///
2478     /// ```
2479     /// use std::path::{self, Path};
2480     /// use std::ffi::OsStr;
2481     ///
2482     /// let mut it = Path::new("/tmp/foo.txt").iter();
2483     /// assert_eq!(it.next(), Some(OsStr::new(&path::MAIN_SEPARATOR.to_string())));
2484     /// assert_eq!(it.next(), Some(OsStr::new("tmp")));
2485     /// assert_eq!(it.next(), Some(OsStr::new("foo.txt")));
2486     /// assert_eq!(it.next(), None)
2487     /// ```
2488     #[stable(feature = "rust1", since = "1.0.0")]
2489     #[inline]
2490     pub fn iter(&self) -> Iter<'_> {
2491         Iter { inner: self.components() }
2492     }
2493
2494     /// Returns an object that implements [`Display`] for safely printing paths
2495     /// that may contain non-Unicode data. This may perform lossy conversion,
2496     /// depending on the platform.  If you would like an implementation which
2497     /// escapes the path please use [`Debug`] instead.
2498     ///
2499     /// [`Display`]: fmt::Display
2500     ///
2501     /// # Examples
2502     ///
2503     /// ```
2504     /// use std::path::Path;
2505     ///
2506     /// let path = Path::new("/tmp/foo.rs");
2507     ///
2508     /// println!("{}", path.display());
2509     /// ```
2510     #[stable(feature = "rust1", since = "1.0.0")]
2511     #[inline]
2512     pub fn display(&self) -> Display<'_> {
2513         Display { path: self }
2514     }
2515
2516     /// Queries the file system to get information about a file, directory, etc.
2517     ///
2518     /// This function will traverse symbolic links to query information about the
2519     /// destination file.
2520     ///
2521     /// This is an alias to [`fs::metadata`].
2522     ///
2523     /// # Examples
2524     ///
2525     /// ```no_run
2526     /// use std::path::Path;
2527     ///
2528     /// let path = Path::new("/Minas/tirith");
2529     /// let metadata = path.metadata().expect("metadata call failed");
2530     /// println!("{:?}", metadata.file_type());
2531     /// ```
2532     #[stable(feature = "path_ext", since = "1.5.0")]
2533     #[inline]
2534     pub fn metadata(&self) -> io::Result<fs::Metadata> {
2535         fs::metadata(self)
2536     }
2537
2538     /// Queries the metadata about a file without following symlinks.
2539     ///
2540     /// This is an alias to [`fs::symlink_metadata`].
2541     ///
2542     /// # Examples
2543     ///
2544     /// ```no_run
2545     /// use std::path::Path;
2546     ///
2547     /// let path = Path::new("/Minas/tirith");
2548     /// let metadata = path.symlink_metadata().expect("symlink_metadata call failed");
2549     /// println!("{:?}", metadata.file_type());
2550     /// ```
2551     #[stable(feature = "path_ext", since = "1.5.0")]
2552     #[inline]
2553     pub fn symlink_metadata(&self) -> io::Result<fs::Metadata> {
2554         fs::symlink_metadata(self)
2555     }
2556
2557     /// Returns the canonical, absolute form of the path with all intermediate
2558     /// components normalized and symbolic links resolved.
2559     ///
2560     /// This is an alias to [`fs::canonicalize`].
2561     ///
2562     /// # Examples
2563     ///
2564     /// ```no_run
2565     /// use std::path::{Path, PathBuf};
2566     ///
2567     /// let path = Path::new("/foo/test/../test/bar.rs");
2568     /// assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs"));
2569     /// ```
2570     #[stable(feature = "path_ext", since = "1.5.0")]
2571     #[inline]
2572     pub fn canonicalize(&self) -> io::Result<PathBuf> {
2573         fs::canonicalize(self)
2574     }
2575
2576     /// Reads a symbolic link, returning the file that the link points to.
2577     ///
2578     /// This is an alias to [`fs::read_link`].
2579     ///
2580     /// # Examples
2581     ///
2582     /// ```no_run
2583     /// use std::path::Path;
2584     ///
2585     /// let path = Path::new("/laputa/sky_castle.rs");
2586     /// let path_link = path.read_link().expect("read_link call failed");
2587     /// ```
2588     #[stable(feature = "path_ext", since = "1.5.0")]
2589     #[inline]
2590     pub fn read_link(&self) -> io::Result<PathBuf> {
2591         fs::read_link(self)
2592     }
2593
2594     /// Returns an iterator over the entries within a directory.
2595     ///
2596     /// The iterator will yield instances of <code>[io::Result]<[fs::DirEntry]></code>. New
2597     /// errors may be encountered after an iterator is initially constructed.
2598     ///
2599     /// This is an alias to [`fs::read_dir`].
2600     ///
2601     /// # Examples
2602     ///
2603     /// ```no_run
2604     /// use std::path::Path;
2605     ///
2606     /// let path = Path::new("/laputa");
2607     /// for entry in path.read_dir().expect("read_dir call failed") {
2608     ///     if let Ok(entry) = entry {
2609     ///         println!("{:?}", entry.path());
2610     ///     }
2611     /// }
2612     /// ```
2613     #[stable(feature = "path_ext", since = "1.5.0")]
2614     #[inline]
2615     pub fn read_dir(&self) -> io::Result<fs::ReadDir> {
2616         fs::read_dir(self)
2617     }
2618
2619     /// Returns `true` if the path points at an existing entity.
2620     ///
2621     /// This function will traverse symbolic links to query information about the
2622     /// destination file.
2623     ///
2624     /// If you cannot access the metadata of the file, e.g. because of a
2625     /// permission error or broken symbolic links, this will return `false`.
2626     ///
2627     /// # Examples
2628     ///
2629     /// ```no_run
2630     /// use std::path::Path;
2631     /// assert!(!Path::new("does_not_exist.txt").exists());
2632     /// ```
2633     ///
2634     /// # See Also
2635     ///
2636     /// This is a convenience function that coerces errors to false. If you want to
2637     /// check errors, call [`fs::metadata`].
2638     #[stable(feature = "path_ext", since = "1.5.0")]
2639     #[inline]
2640     pub fn exists(&self) -> bool {
2641         fs::metadata(self).is_ok()
2642     }
2643
2644     /// Returns `Ok(true)` if the path points at an existing entity.
2645     ///
2646     /// This function will traverse symbolic links to query information about the
2647     /// destination file. In case of broken symbolic links this will return `Ok(false)`.
2648     ///
2649     /// As opposed to the `exists()` method, this one doesn't silently ignore errors
2650     /// unrelated to the path not existing. (E.g. it will return `Err(_)` in case of permission
2651     /// denied on some of the parent directories.)
2652     ///
2653     /// # Examples
2654     ///
2655     /// ```no_run
2656     /// #![feature(path_try_exists)]
2657     ///
2658     /// use std::path::Path;
2659     /// assert!(!Path::new("does_not_exist.txt").try_exists().expect("Can't check existence of file does_not_exist.txt"));
2660     /// assert!(Path::new("/root/secret_file.txt").try_exists().is_err());
2661     /// ```
2662     // FIXME: stabilization should modify documentation of `exists()` to recommend this method
2663     // instead.
2664     #[unstable(feature = "path_try_exists", issue = "83186")]
2665     #[inline]
2666     pub fn try_exists(&self) -> io::Result<bool> {
2667         fs::try_exists(self)
2668     }
2669
2670     /// Returns `true` if the path exists on disk and is pointing at a regular file.
2671     ///
2672     /// This function will traverse symbolic links to query information about the
2673     /// destination file.
2674     ///
2675     /// If you cannot access the metadata of the file, e.g. because of a
2676     /// permission error or broken symbolic links, this will return `false`.
2677     ///
2678     /// # Examples
2679     ///
2680     /// ```no_run
2681     /// use std::path::Path;
2682     /// assert_eq!(Path::new("./is_a_directory/").is_file(), false);
2683     /// assert_eq!(Path::new("a_file.txt").is_file(), true);
2684     /// ```
2685     ///
2686     /// # See Also
2687     ///
2688     /// This is a convenience function that coerces errors to false. If you want to
2689     /// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
2690     /// [`fs::Metadata::is_file`] if it was [`Ok`].
2691     ///
2692     /// When the goal is simply to read from (or write to) the source, the most
2693     /// reliable way to test the source can be read (or written to) is to open
2694     /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on
2695     /// a Unix-like system for example. See [`fs::File::open`] or
2696     /// [`fs::OpenOptions::open`] for more information.
2697     #[stable(feature = "path_ext", since = "1.5.0")]
2698     pub fn is_file(&self) -> bool {
2699         fs::metadata(self).map(|m| m.is_file()).unwrap_or(false)
2700     }
2701
2702     /// Returns `true` if the path exists on disk and is pointing at a directory.
2703     ///
2704     /// This function will traverse symbolic links to query information about the
2705     /// destination file.
2706     ///
2707     /// If you cannot access the metadata of the file, e.g. because of a
2708     /// permission error or broken symbolic links, this will return `false`.
2709     ///
2710     /// # Examples
2711     ///
2712     /// ```no_run
2713     /// use std::path::Path;
2714     /// assert_eq!(Path::new("./is_a_directory/").is_dir(), true);
2715     /// assert_eq!(Path::new("a_file.txt").is_dir(), false);
2716     /// ```
2717     ///
2718     /// # See Also
2719     ///
2720     /// This is a convenience function that coerces errors to false. If you want to
2721     /// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
2722     /// [`fs::Metadata::is_dir`] if it was [`Ok`].
2723     #[stable(feature = "path_ext", since = "1.5.0")]
2724     pub fn is_dir(&self) -> bool {
2725         fs::metadata(self).map(|m| m.is_dir()).unwrap_or(false)
2726     }
2727
2728     /// Returns true if the path exists on disk and is pointing at a symbolic link.
2729     ///
2730     /// This function will not traverse symbolic links.
2731     /// In case of a broken symbolic link this will also return true.
2732     ///
2733     /// If you cannot access the directory containing the file, e.g., because of a
2734     /// permission error, this will return false.
2735     ///
2736     /// # Examples
2737     ///
2738     #[cfg_attr(unix, doc = "```no_run")]
2739     #[cfg_attr(not(unix), doc = "```ignore")]
2740     /// #![feature(is_symlink)]
2741     /// use std::path::Path;
2742     /// use std::os::unix::fs::symlink;
2743     ///
2744     /// let link_path = Path::new("link");
2745     /// symlink("/origin_does_not_exists/", link_path).unwrap();
2746     /// assert_eq!(link_path.is_symlink(), true);
2747     /// assert_eq!(link_path.exists(), false);
2748     /// ```
2749     #[unstable(feature = "is_symlink", issue = "85748")]
2750     pub fn is_symlink(&self) -> bool {
2751         fs::symlink_metadata(self).map(|m| m.is_symlink()).unwrap_or(false)
2752     }
2753
2754     /// Converts a [`Box<Path>`](Box) into a [`PathBuf`] without copying or
2755     /// allocating.
2756     #[stable(feature = "into_boxed_path", since = "1.20.0")]
2757     pub fn into_path_buf(self: Box<Path>) -> PathBuf {
2758         let rw = Box::into_raw(self) as *mut OsStr;
2759         let inner = unsafe { Box::from_raw(rw) };
2760         PathBuf { inner: OsString::from(inner) }
2761     }
2762 }
2763
2764 #[stable(feature = "rust1", since = "1.0.0")]
2765 impl AsRef<OsStr> for Path {
2766     #[inline]
2767     fn as_ref(&self) -> &OsStr {
2768         &self.inner
2769     }
2770 }
2771
2772 #[stable(feature = "rust1", since = "1.0.0")]
2773 impl fmt::Debug for Path {
2774     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2775         fmt::Debug::fmt(&self.inner, formatter)
2776     }
2777 }
2778
2779 /// Helper struct for safely printing paths with [`format!`] and `{}`.
2780 ///
2781 /// A [`Path`] might contain non-Unicode data. This `struct` implements the
2782 /// [`Display`] trait in a way that mitigates that. It is created by the
2783 /// [`display`](Path::display) method on [`Path`]. This may perform lossy
2784 /// conversion, depending on the platform. If you would like an implementation
2785 /// which escapes the path please use [`Debug`] instead.
2786 ///
2787 /// # Examples
2788 ///
2789 /// ```
2790 /// use std::path::Path;
2791 ///
2792 /// let path = Path::new("/tmp/foo.rs");
2793 ///
2794 /// println!("{}", path.display());
2795 /// ```
2796 ///
2797 /// [`Display`]: fmt::Display
2798 /// [`format!`]: crate::format
2799 #[stable(feature = "rust1", since = "1.0.0")]
2800 pub struct Display<'a> {
2801     path: &'a Path,
2802 }
2803
2804 #[stable(feature = "rust1", since = "1.0.0")]
2805 impl fmt::Debug for Display<'_> {
2806     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2807         fmt::Debug::fmt(&self.path, f)
2808     }
2809 }
2810
2811 #[stable(feature = "rust1", since = "1.0.0")]
2812 impl fmt::Display for Display<'_> {
2813     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2814         self.path.inner.display(f)
2815     }
2816 }
2817
2818 #[stable(feature = "rust1", since = "1.0.0")]
2819 impl cmp::PartialEq for Path {
2820     #[inline]
2821     fn eq(&self, other: &Path) -> bool {
2822         self.components() == other.components()
2823     }
2824 }
2825
2826 #[stable(feature = "rust1", since = "1.0.0")]
2827 impl Hash for Path {
2828     fn hash<H: Hasher>(&self, h: &mut H) {
2829         for component in self.components() {
2830             component.hash(h);
2831         }
2832     }
2833 }
2834
2835 #[stable(feature = "rust1", since = "1.0.0")]
2836 impl cmp::Eq for Path {}
2837
2838 #[stable(feature = "rust1", since = "1.0.0")]
2839 impl cmp::PartialOrd for Path {
2840     #[inline]
2841     fn partial_cmp(&self, other: &Path) -> Option<cmp::Ordering> {
2842         Some(compare_components(self.components(), other.components()))
2843     }
2844 }
2845
2846 #[stable(feature = "rust1", since = "1.0.0")]
2847 impl cmp::Ord for Path {
2848     #[inline]
2849     fn cmp(&self, other: &Path) -> cmp::Ordering {
2850         compare_components(self.components(), other.components())
2851     }
2852 }
2853
2854 #[stable(feature = "rust1", since = "1.0.0")]
2855 impl AsRef<Path> for Path {
2856     #[inline]
2857     fn as_ref(&self) -> &Path {
2858         self
2859     }
2860 }
2861
2862 #[stable(feature = "rust1", since = "1.0.0")]
2863 impl AsRef<Path> for OsStr {
2864     #[inline]
2865     fn as_ref(&self) -> &Path {
2866         Path::new(self)
2867     }
2868 }
2869
2870 #[stable(feature = "cow_os_str_as_ref_path", since = "1.8.0")]
2871 impl AsRef<Path> for Cow<'_, OsStr> {
2872     #[inline]
2873     fn as_ref(&self) -> &Path {
2874         Path::new(self)
2875     }
2876 }
2877
2878 #[stable(feature = "rust1", since = "1.0.0")]
2879 impl AsRef<Path> for OsString {
2880     #[inline]
2881     fn as_ref(&self) -> &Path {
2882         Path::new(self)
2883     }
2884 }
2885
2886 #[stable(feature = "rust1", since = "1.0.0")]
2887 impl AsRef<Path> for str {
2888     #[inline]
2889     fn as_ref(&self) -> &Path {
2890         Path::new(self)
2891     }
2892 }
2893
2894 #[stable(feature = "rust1", since = "1.0.0")]
2895 impl AsRef<Path> for String {
2896     #[inline]
2897     fn as_ref(&self) -> &Path {
2898         Path::new(self)
2899     }
2900 }
2901
2902 #[stable(feature = "rust1", since = "1.0.0")]
2903 impl AsRef<Path> for PathBuf {
2904     #[inline]
2905     fn as_ref(&self) -> &Path {
2906         self
2907     }
2908 }
2909
2910 #[stable(feature = "path_into_iter", since = "1.6.0")]
2911 impl<'a> IntoIterator for &'a PathBuf {
2912     type Item = &'a OsStr;
2913     type IntoIter = Iter<'a>;
2914     #[inline]
2915     fn into_iter(self) -> Iter<'a> {
2916         self.iter()
2917     }
2918 }
2919
2920 #[stable(feature = "path_into_iter", since = "1.6.0")]
2921 impl<'a> IntoIterator for &'a Path {
2922     type Item = &'a OsStr;
2923     type IntoIter = Iter<'a>;
2924     #[inline]
2925     fn into_iter(self) -> Iter<'a> {
2926         self.iter()
2927     }
2928 }
2929
2930 macro_rules! impl_cmp {
2931     ($lhs:ty, $rhs: ty) => {
2932         #[stable(feature = "partialeq_path", since = "1.6.0")]
2933         impl<'a, 'b> PartialEq<$rhs> for $lhs {
2934             #[inline]
2935             fn eq(&self, other: &$rhs) -> bool {
2936                 <Path as PartialEq>::eq(self, other)
2937             }
2938         }
2939
2940         #[stable(feature = "partialeq_path", since = "1.6.0")]
2941         impl<'a, 'b> PartialEq<$lhs> for $rhs {
2942             #[inline]
2943             fn eq(&self, other: &$lhs) -> bool {
2944                 <Path as PartialEq>::eq(self, other)
2945             }
2946         }
2947
2948         #[stable(feature = "cmp_path", since = "1.8.0")]
2949         impl<'a, 'b> PartialOrd<$rhs> for $lhs {
2950             #[inline]
2951             fn partial_cmp(&self, other: &$rhs) -> Option<cmp::Ordering> {
2952                 <Path as PartialOrd>::partial_cmp(self, other)
2953             }
2954         }
2955
2956         #[stable(feature = "cmp_path", since = "1.8.0")]
2957         impl<'a, 'b> PartialOrd<$lhs> for $rhs {
2958             #[inline]
2959             fn partial_cmp(&self, other: &$lhs) -> Option<cmp::Ordering> {
2960                 <Path as PartialOrd>::partial_cmp(self, other)
2961             }
2962         }
2963     };
2964 }
2965
2966 impl_cmp!(PathBuf, Path);
2967 impl_cmp!(PathBuf, &'a Path);
2968 impl_cmp!(Cow<'a, Path>, Path);
2969 impl_cmp!(Cow<'a, Path>, &'b Path);
2970 impl_cmp!(Cow<'a, Path>, PathBuf);
2971
2972 macro_rules! impl_cmp_os_str {
2973     ($lhs:ty, $rhs: ty) => {
2974         #[stable(feature = "cmp_path", since = "1.8.0")]
2975         impl<'a, 'b> PartialEq<$rhs> for $lhs {
2976             #[inline]
2977             fn eq(&self, other: &$rhs) -> bool {
2978                 <Path as PartialEq>::eq(self, other.as_ref())
2979             }
2980         }
2981
2982         #[stable(feature = "cmp_path", since = "1.8.0")]
2983         impl<'a, 'b> PartialEq<$lhs> for $rhs {
2984             #[inline]
2985             fn eq(&self, other: &$lhs) -> bool {
2986                 <Path as PartialEq>::eq(self.as_ref(), other)
2987             }
2988         }
2989
2990         #[stable(feature = "cmp_path", since = "1.8.0")]
2991         impl<'a, 'b> PartialOrd<$rhs> for $lhs {
2992             #[inline]
2993             fn partial_cmp(&self, other: &$rhs) -> Option<cmp::Ordering> {
2994                 <Path as PartialOrd>::partial_cmp(self, other.as_ref())
2995             }
2996         }
2997
2998         #[stable(feature = "cmp_path", since = "1.8.0")]
2999         impl<'a, 'b> PartialOrd<$lhs> for $rhs {
3000             #[inline]
3001             fn partial_cmp(&self, other: &$lhs) -> Option<cmp::Ordering> {
3002                 <Path as PartialOrd>::partial_cmp(self.as_ref(), other)
3003             }
3004         }
3005     };
3006 }
3007
3008 impl_cmp_os_str!(PathBuf, OsStr);
3009 impl_cmp_os_str!(PathBuf, &'a OsStr);
3010 impl_cmp_os_str!(PathBuf, Cow<'a, OsStr>);
3011 impl_cmp_os_str!(PathBuf, OsString);
3012 impl_cmp_os_str!(Path, OsStr);
3013 impl_cmp_os_str!(Path, &'a OsStr);
3014 impl_cmp_os_str!(Path, Cow<'a, OsStr>);
3015 impl_cmp_os_str!(Path, OsString);
3016 impl_cmp_os_str!(&'a Path, OsStr);
3017 impl_cmp_os_str!(&'a Path, Cow<'b, OsStr>);
3018 impl_cmp_os_str!(&'a Path, OsString);
3019 impl_cmp_os_str!(Cow<'a, Path>, OsStr);
3020 impl_cmp_os_str!(Cow<'a, Path>, &'b OsStr);
3021 impl_cmp_os_str!(Cow<'a, Path>, OsString);
3022
3023 #[stable(since = "1.7.0", feature = "strip_prefix")]
3024 impl fmt::Display for StripPrefixError {
3025     #[allow(deprecated, deprecated_in_future)]
3026     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3027         self.description().fmt(f)
3028     }
3029 }
3030
3031 #[stable(since = "1.7.0", feature = "strip_prefix")]
3032 impl Error for StripPrefixError {
3033     #[allow(deprecated)]
3034     fn description(&self) -> &str {
3035         "prefix not found"
3036     }
3037 }