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