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