src/libstd/path.rs

   1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Cross-platform path manipulation.
  12 //!
  13 //! This module provides two types, `PathBuf` and `Path` (akin to `String` and
  14 //! `str`), for working with paths abstractly. These types are thin wrappers
  15 //! around `OsString` and `OsStr` respectively, meaning that they work directly
  16 //! on strings according to the local platform's path syntax.
  17 //!
  18 //! ## Simple usage
  19 //!
  20 //! Path manipulation includes both parsing components from slices and building
  21 //! new owned paths.
  22 //!
  23 //! To parse a path, you can create a `Path` slice from a `str`
  24 //! slice and start asking questions:
  25 //!
  26 //! ```rust
  27 //! use std::path::Path;
  28 //!
  29 //! let path = Path::new("/tmp/foo/bar.txt");
  30 //! let file = path.file_name();
  31 //! let extension = path.extension();
  32 //! let parent_dir = path.parent();
  33 //! ```
  34 //!
  35 //! To build or modify paths, use `PathBuf`:
  36 //!
  37 //! ```rust
  38 //! use std::path::PathBuf;
  39 //!
  40 //! let mut path = PathBuf::new("c:\\");
  41 //! path.push("windows");
  42 //! path.push("system32");
  43 //! path.set_extension("dll");
  44 //! ```
  45 //!
  46 //! ## Path components and normalization
  47 //!
  48 //! The path APIs are built around the notion of "components", which roughly
  49 //! correspond to the substrings between path separators (`/` and, on Windows,
  50 //! `\`). The APIs for path parsing are largely specified in terms of the path's
  51 //! components, so it's important to clearly understand how those are determined.
  52 //!
  53 //! A path can always be reconstructed into an *equivalent* path by
  54 //! putting together its components via `push`. Syntactically, the
  55 //! paths may differ by the normalization described below.
  56 //!
  57 //! ### Component types
  58 //!
  59 //! Components come in several types:
  60 //!
  61 //! * Normal components are the default: standard references to files or
  62 //! directories. The path `a/b` has two normal components, `a` and `b`.
  63 //!
  64 //! * Current directory components represent the `.` character. For example,
  65 //! `./a` has a current directory component and a normal component `a`.
  66 //!
  67 //! * The root directory component represents a separator that designates
  68 //!   starting from root. For example, `/a/b` has a root directory component
  69 //!   followed by normal components `a` and `b`.
  70 //!
  71 //! On Windows, an additional component type comes into play:
  72 //!
  73 //! * Prefix components, of which there is a large variety. For example, `C:`
  74 //! and `\\server\share` are prefixes. The path `C:windows` has a prefix
  75 //! component `C:` and a normal component `windows`; the path `C:\windows` has a
  76 //! prefix component `C:`, a root directory component, and a normal component
  77 //! `windows`.
  78 //!
  79 //! ### Normalization
  80 //!
  81 //! Aside from splitting on the separator(s), there is a small amount of
  82 //! "normalization":
  83 //!
  84 //! * Repeated separators are ignored: `a/b` and `a//b` both have components `a`
  85 //!   and `b`.
  86 //!
  87 //! * Occurrences of `.` are normalized away, *except* if they are at
  88 //! the beginning of the path (in which case they are often meaningful
  89 //! in terms of path searching). So, for example, `a/./b`, `a/b/`,
  90 //! `/a/b/.` and `a/b` all have components `a` and `b`, but `./a/b`
  91 //! has a leading current directory component.
  92 //!
  93 //! No other normalization takes place by default. In particular,
  94 //! `a/c` and `a/b/../c` are distinct, to account for the possibility
  95 //! that `b` is a symbolic link (so its parent isn't `a`). Further
  96 //! normalization is possible to build on top of the components APIs,
  97 //! and will be included in this library in the near future.
  98
  99 #![stable(feature = "rust1", since = "1.0.0")]
 100
 101 use core::prelude::*;
 102
 103 use ascii::*;
 104 use borrow::{Borrow, IntoCow, ToOwned, Cow};
 105 use cmp;
 106 use iter::{self, IntoIterator};
 107 use mem;
 108 use ops::{self, Deref};
 109 use vec::Vec;
 110 use fmt;
 111
 112 use ffi::{OsStr, OsString, AsOsStr};
 113
 114 use self::platform::{is_sep_byte, is_verbatim_sep, MAIN_SEP_STR, parse_prefix};
 115
 116 ////////////////////////////////////////////////////////////////////////////////
 117 // GENERAL NOTES
 118 ////////////////////////////////////////////////////////////////////////////////
 119 //
 120 // Parsing in this module is done by directly transmuting OsStr to [u8] slices,
 121 // taking advantage of the fact that OsStr always encodes ASCII characters
 122 // as-is.  Eventually, this transmutation should be replaced by direct uses of
 123 // OsStr APIs for parsing, but it will take a while for those to become
 124 // available.
 125
 126 ////////////////////////////////////////////////////////////////////////////////
 127 // Platform-specific definitions
 128 ////////////////////////////////////////////////////////////////////////////////
 129
 130 // The following modules give the most basic tools for parsing paths on various
 131 // platforms. The bulk of the code is devoted to parsing prefixes on Windows.
 132
 133 #[cfg(unix)]
 134 mod platform {
 135     use super::Prefix;
 136     use core::prelude::*;
 137     use ffi::OsStr;
 138
 139     #[inline]
 140     pub fn is_sep_byte(b: u8) -> bool {
 141         b == b'/'
 142     }
 143
 144     #[inline]
 145     pub fn is_verbatim_sep(b: u8) -> bool {
 146         b == b'/'
 147     }
 148
 149     pub fn parse_prefix(_: &OsStr) -> Option<Prefix> {
 150         None
 151     }
 152
 153     pub const MAIN_SEP_STR: &'static str = "/";
 154     pub const MAIN_SEP: char = '/';
 155 }
 156
 157 #[cfg(windows)]
 158 mod platform {
 159     use core::prelude::*;
 160     use ascii::*;
 161
 162     use char::CharExt as UnicodeCharExt;
 163     use super::{os_str_as_u8_slice, u8_slice_as_os_str, Prefix};
 164     use ffi::OsStr;
 165
 166     #[inline]
 167     pub fn is_sep_byte(b: u8) -> bool {
 168         b == b'/' || b == b'\\'
 169     }
 170
 171     #[inline]
 172     pub fn is_verbatim_sep(b: u8) -> bool {
 173         b == b'\\'
 174     }
 175
 176     pub fn parse_prefix<'a>(path: &'a OsStr) -> Option<Prefix> {
 177         use super::Prefix::*;
 178         unsafe {
 179             // The unsafety here stems from converting between &OsStr and &[u8]
 180             // and back. This is safe to do because (1) we only look at ASCII
 181             // contents of the encoding and (2) new &OsStr values are produced
 182             // only from ASCII-bounded slices of existing &OsStr values.
 183             let mut path = os_str_as_u8_slice(path);
 184
 185             if path.starts_with(br"\\") {
 186                 // \\
 187                 path = &path[2..];
 188                 if path.starts_with(br"?\") {
 189                     // \\?\
 190                     path = &path[2..];
 191                     if path.starts_with(br"UNC\") {
 192                         // \\?\UNC\server\share
 193                         path = &path[4..];
 194                         let (server, share) = match parse_two_comps(path, is_verbatim_sep) {
 195                             Some((server, share)) => (u8_slice_as_os_str(server),
 196                                                       u8_slice_as_os_str(share)),
 197                             None => (u8_slice_as_os_str(path),
 198                                      u8_slice_as_os_str(&[])),
 199                         };
 200                         return Some(VerbatimUNC(server, share));
 201                     } else {
 202                         // \\?\path
 203                         let idx = path.position_elem(&b'\\');
 204                         if idx == Some(2) && path[1] == b':' {
 205                             let c = path[0];
 206                             if c.is_ascii() && (c as char).is_alphabetic() {
 207                                 // \\?\C:\ path
 208                                 return Some(VerbatimDisk(c.to_ascii_uppercase()));
 209                             }
 210                         }
 211                         let slice = &path[.. idx.unwrap_or(path.len())];
 212                         return Some(Verbatim(u8_slice_as_os_str(slice)));
 213                     }
 214                 } else if path.starts_with(b".\\") {
 215                     // \\.\path
 216                     path = &path[2..];
 217                     let slice = &path[.. path.position_elem(&b'\\').unwrap_or(path.len())];
 218                     return Some(DeviceNS(u8_slice_as_os_str(slice)));
 219                 }
 220                 match parse_two_comps(path, is_sep_byte) {
 221                     Some((server, share)) if server.len() > 0 && share.len() > 0 => {
 222                         // \\server\share
 223                         return Some(UNC(u8_slice_as_os_str(server),
 224                                         u8_slice_as_os_str(share)));
 225                     }
 226                     _ => ()
 227                 }
 228             } else if path.len() > 1 && path[1] == b':' {
 229                 // C:
 230                 let c = path[0];
 231                 if c.is_ascii() && (c as char).is_alphabetic() {
 232                     return Some(Disk(c.to_ascii_uppercase()));
 233                 }
 234             }
 235             return None;
 236         }
 237
 238         fn parse_two_comps(mut path: &[u8], f: fn(u8) -> bool) -> Option<(&[u8], &[u8])> {
 239             let first = match path.iter().position(|x| f(*x)) {
 240                 None => return None,
 241                 Some(x) => &path[.. x]
 242             };
 243             path = &path[(first.len()+1)..];
 244             let idx = path.iter().position(|x| f(*x));
 245             let second = &path[.. idx.unwrap_or(path.len())];
 246             Some((first, second))
 247         }
 248     }
 249
 250     pub const MAIN_SEP_STR: &'static str = "\\";
 251     pub const MAIN_SEP: char = '\\';
 252 }
 253
 254 ////////////////////////////////////////////////////////////////////////////////
 255 // Windows Prefixes
 256 ////////////////////////////////////////////////////////////////////////////////
 257
 258 /// Path prefixes (Windows only).
 259 ///
 260 /// Windows uses a variety of path styles, including references to drive
 261 /// volumes (like `C:`), network shared (like `\\server\share`) and
 262 /// others. In addition, some path prefixes are "verbatim", in which case
 263 /// `/` is *not* treated as a separator and essentially no normalization is
 264 /// performed.
 265 #[derive(Copy, Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
 266 #[stable(feature = "rust1", since = "1.0.0")]
 267 pub enum Prefix<'a> {
 268     /// Prefix `\\?\`, together with the given component immediately following it.
 269     #[stable(feature = "rust1", since = "1.0.0")]
 270     Verbatim(&'a OsStr),
 271
 272     /// Prefix `\\?\UNC\`, with the "server" and "share" components following it.
 273     #[stable(feature = "rust1", since = "1.0.0")]
 274     VerbatimUNC(&'a OsStr, &'a OsStr),
 275
 276     /// Prefix like `\\?\C:\`, for the given drive letter
 277     #[stable(feature = "rust1", since = "1.0.0")]
 278     VerbatimDisk(u8),
 279
 280     /// Prefix `\\.\`, together with the given component immediately following it.
 281     #[stable(feature = "rust1", since = "1.0.0")]
 282     DeviceNS(&'a OsStr),
 283
 284     /// Prefix `\\server\share`, with the given "server" and "share" components.
 285     #[stable(feature = "rust1", since = "1.0.0")]
 286     UNC(&'a OsStr, &'a OsStr),
 287
 288     /// Prefix `C:` for the given disk drive.
 289     #[stable(feature = "rust1", since = "1.0.0")]
 290     Disk(u8),
 291 }
 292
 293 impl<'a> Prefix<'a> {
 294     #[inline]
 295     fn len(&self) -> usize {
 296         use self::Prefix::*;
 297         fn os_str_len(s: &OsStr) -> usize {
 298             os_str_as_u8_slice(s).len()
 299         }
 300         match *self {
 301             Verbatim(x) => 4 + os_str_len(x),
 302             VerbatimUNC(x,y) => 8 + os_str_len(x) +
 303                 if os_str_len(y) > 0 { 1 + os_str_len(y) }
 304                 else { 0 },
 305             VerbatimDisk(_) => 6,
 306             UNC(x,y) => 2 + os_str_len(x) +
 307                 if os_str_len(y) > 0 { 1 + os_str_len(y) }
 308                 else { 0 },
 309             DeviceNS(x) => 4 + os_str_len(x),
 310             Disk(_) => 2
 311         }
 312
 313     }
 314
 315     /// Determine if the prefix is verbatim, i.e. begins `\\?\`.
 316     #[inline]
 317     #[stable(feature = "rust1", since = "1.0.0")]
 318     pub fn is_verbatim(&self) -> bool {
 319         use self::Prefix::*;
 320         match *self {
 321             Verbatim(_) | VerbatimDisk(_) | VerbatimUNC(_, _) => true,
 322             _ => false
 323         }
 324     }
 325
 326     #[inline]
 327     fn is_drive(&self) -> bool {
 328         match *self {
 329             Prefix::Disk(_) => true,
 330             _ => false,
 331         }
 332     }
 333
 334     #[inline]
 335     fn has_implicit_root(&self) -> bool {
 336         !self.is_drive()
 337     }
 338 }
 339
 340 ////////////////////////////////////////////////////////////////////////////////
 341 // Exposed parsing helpers
 342 ////////////////////////////////////////////////////////////////////////////////
 343
 344 /// Determine whether the character is one of the permitted path
 345 /// separators for the current platform.
 346 #[stable(feature = "rust1", since = "1.0.0")]
 347 pub fn is_separator(c: char) -> bool {
 348     use ascii::*;
 349     c.is_ascii() && is_sep_byte(c as u8)
 350 }
 351
 352 /// The primary sperator for the current platform
 353 #[stable(feature = "rust1", since = "1.0.0")]
 354 pub const MAIN_SEPARATOR: char = platform::MAIN_SEP;
 355
 356 ////////////////////////////////////////////////////////////////////////////////
 357 // Misc helpers
 358 ////////////////////////////////////////////////////////////////////////////////
 359
 360 // Iterate through `iter` while it matches `prefix`; return `None` if `prefix`
 361 // is not a prefix of `iter`, otherwise return `Some(iter_after_prefix)` giving
 362 // `iter` after having exhausted `prefix`.
 363 fn iter_after<A, I, J>(mut iter: I, mut prefix: J) -> Option<I> where
 364     I: Iterator<Item=A> + Clone, J: Iterator<Item=A>, A: PartialEq
 365 {
 366     loop {
 367         let mut iter_next = iter.clone();
 368         match (iter_next.next(), prefix.next()) {
 369             (Some(x), Some(y)) => {
 370                 if x != y { return None }
 371             }
 372             (Some(_), None) => return Some(iter),
 373             (None, None) => return Some(iter),
 374             (None, Some(_)) => return None,
 375         }
 376         iter = iter_next;
 377     }
 378 }
 379
 380 // See note at the top of this module to understand why these are used:
 381 fn os_str_as_u8_slice(s: &OsStr) -> &[u8] {
 382     unsafe { mem::transmute(s) }
 383 }
 384 unsafe fn u8_slice_as_os_str(s: &[u8]) -> &OsStr {
 385     mem::transmute(s)
 386 }
 387
 388 ////////////////////////////////////////////////////////////////////////////////
 389 // Cross-platform, iterator-independent parsing
 390 ////////////////////////////////////////////////////////////////////////////////
 391
 392 /// Says whether the first byte after the prefix is a separator.
 393 fn has_physical_root(s: &[u8], prefix: Option<Prefix>) -> bool {
 394     let path = if let Some(p) = prefix { &s[p.len()..] } else { s };
 395     path.len() > 0 && is_sep_byte(path[0])
 396 }
 397
 398 // basic workhorse for splitting stem and extension
 399 #[allow(unused_unsafe)] // FIXME
 400 fn split_file_at_dot(file: &OsStr) -> (Option<&OsStr>, Option<&OsStr>) {
 401     unsafe {
 402         if os_str_as_u8_slice(file) == b".." { return (Some(file), None) }
 403
 404         // The unsafety here stems from converting between &OsStr and &[u8]
 405         // and back. This is safe to do because (1) we only look at ASCII
 406         // contents of the encoding and (2) new &OsStr values are produced
 407         // only from ASCII-bounded slices of existing &OsStr values.
 408
 409         let mut iter = os_str_as_u8_slice(file).rsplitn(1, |b| *b == b'.');
 410         let after = iter.next();
 411         let before = iter.next();
 412         if before == Some(b"") {
 413             (Some(file), None)
 414         } else {
 415             (before.map(|s| u8_slice_as_os_str(s)),
 416              after.map(|s| u8_slice_as_os_str(s)))
 417         }
 418     }
 419 }
 420
 421 ////////////////////////////////////////////////////////////////////////////////
 422 // The core iterators
 423 ////////////////////////////////////////////////////////////////////////////////
 424
 425 /// Component parsing works by a double-ended state machine; the cursors at the
 426 /// front and back of the path each keep track of what parts of the path have
 427 /// been consumed so far.
 428 ///
 429 /// Going front to back, a path is made up of a prefix, a starting
 430 /// directory component, and a body (of normal components)
 431 #[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
 432 enum State {
 433     Prefix = 0,         // c:
 434     StartDir = 1,       // / or . or nothing
 435     Body = 2,           // foo/bar/baz
 436     Done = 3,
 437 }
 438
 439 /// A Windows path prefix, e.g. `C:` or `\server\share`.
 440 ///
 441 /// Does not occur on Unix.
 442 #[stable(feature = "rust1", since = "1.0.0")]
 443 #[derive(Copy, Clone, Eq, Hash, Debug)]
 444 pub struct PrefixComponent<'a> {
 445     /// The prefix as an unparsed `OsStr` slice.
 446     raw: &'a OsStr,
 447
 448     /// The parsed prefix data.
 449     parsed: Prefix<'a>,
 450 }
 451
 452 impl<'a> PrefixComponent<'a> {
 453     /// The parsed prefix data.
 454     #[stable(feature = "rust1", since = "1.0.0")]
 455     pub fn kind(&self) -> Prefix<'a> {
 456         self.parsed
 457     }
 458
 459     /// The raw `OsStr` slice for this prefix.
 460     #[stable(feature = "rust1", since = "1.0.0")]
 461     pub fn as_os_str(&self) -> &'a OsStr {
 462         self.raw
 463     }
 464 }
 465
 466 #[stable(feature = "rust1", since = "1.0.0")]
 467 impl<'a> cmp::PartialEq for PrefixComponent<'a> {
 468     fn eq(&self, other: &PrefixComponent<'a>) -> bool {
 469         cmp::PartialEq::eq(&self.parsed, &other.parsed)
 470     }
 471 }
 472
 473 #[stable(feature = "rust1", since = "1.0.0")]
 474 impl<'a> cmp::PartialOrd for PrefixComponent<'a> {
 475     fn partial_cmp(&self, other: &PrefixComponent<'a>) -> Option<cmp::Ordering> {
 476         cmp::PartialOrd::partial_cmp(&self.parsed, &other.parsed)
 477     }
 478 }
 479
 480 #[stable(feature = "rust1", since = "1.0.0")]
 481 impl<'a> cmp::Ord for PrefixComponent<'a> {
 482     fn cmp(&self, other: &PrefixComponent<'a>) -> cmp::Ordering {
 483         cmp::Ord::cmp(&self.parsed, &other.parsed)
 484     }
 485 }
 486
 487 /// A single component of a path.
 488 ///
 489 /// See the module documentation for an in-depth explanation of components and
 490 /// their role in the API.
 491 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 492 #[stable(feature = "rust1", since = "1.0.0")]
 493 pub enum Component<'a> {
 494     /// A Windows path prefix, e.g. `C:` or `\server\share`.
 495     ///
 496     /// Does not occur on Unix.
 497     #[stable(feature = "rust1", since = "1.0.0")]
 498     Prefix(PrefixComponent<'a>),
 499
 500     /// The root directory component, appears after any prefix and before anything else
 501     #[stable(feature = "rust1", since = "1.0.0")]
 502     RootDir,
 503
 504     /// A reference to the current directory, i.e. `.`
 505     #[stable(feature = "rust1", since = "1.0.0")]
 506     CurDir,
 507
 508     /// A reference to the parent directory, i.e. `..`
 509     #[stable(feature = "rust1", since = "1.0.0")]
 510     ParentDir,
 511
 512     /// A normal component, i.e. `a` and `b` in `a/b`
 513     #[stable(feature = "rust1", since = "1.0.0")]
 514     Normal(&'a OsStr),
 515 }
 516
 517 impl<'a> Component<'a> {
 518     /// Extract the underlying `OsStr` slice
 519     #[stable(feature = "rust1", since = "1.0.0")]
 520     pub fn as_os_str(self) -> &'a OsStr {
 521         match self {
 522             Component::Prefix(p) => p.as_os_str(),
 523             Component::RootDir => OsStr::from_str(MAIN_SEP_STR),
 524             Component::CurDir => OsStr::from_str("."),
 525             Component::ParentDir => OsStr::from_str(".."),
 526             Component::Normal(path) => path,
 527         }
 528     }
 529 }
 530
 531 /// The core iterator giving the components of a path.
 532 ///
 533 /// See the module documentation for an in-depth explanation of components and
 534 /// their role in the API.
 535 #[derive(Clone)]
 536 #[stable(feature = "rust1", since = "1.0.0")]
 537 pub struct Components<'a> {
 538     // The path left to parse components from
 539     path: &'a [u8],
 540
 541     // The prefix as it was originally parsed, if any
 542     prefix: Option<Prefix<'a>>,
 543
 544     // true if path *physically* has a root separator; for most Windows
 545     // prefixes, it may have a "logical" rootseparator for the purposes of
 546     // normalization, e.g.  \\server\share == \\server\share\.
 547     has_physical_root: bool,
 548
 549     // The iterator is double-ended, and these two states keep track of what has
 550     // been produced from either end
 551     front: State,
 552     back: State,
 553 }
 554
 555 /// An iterator over the components of a path, as `OsStr` slices.
 556 #[derive(Clone)]
 557 #[stable(feature = "rust1", since = "1.0.0")]
 558 pub struct Iter<'a> {
 559     inner: Components<'a>
 560 }
 561
 562 impl<'a> Components<'a> {
 563     // how long is the prefix, if any?
 564     #[inline]
 565     fn prefix_len(&self) -> usize {
 566         self.prefix.as_ref().map(Prefix::len).unwrap_or(0)
 567     }
 568
 569     #[inline]
 570     fn prefix_verbatim(&self) -> bool {
 571         self.prefix.as_ref().map(Prefix::is_verbatim).unwrap_or(false)
 572     }
 573
 574     /// how much of the prefix is left from the point of view of iteration?
 575     #[inline]
 576     fn prefix_remaining(&self) -> usize {
 577         if self.front == State::Prefix { self.prefix_len() }
 578         else { 0 }
 579     }
 580
 581     // Given the iteration so far, how much of the pre-State::Body path is left?
 582     #[inline]
 583     fn len_before_body(&self) -> usize {
 584         let root = if self.front <= State::StartDir && self.has_physical_root { 1 } else { 0 };
 585         let cur_dir = if self.front <= State::StartDir && self.include_cur_dir() { 1 } else { 0 };
 586         self.prefix_remaining() + root + cur_dir
 587     }
 588
 589     // is the iteration complete?
 590     #[inline]
 591     fn finished(&self) -> bool {
 592         self.front == State::Done || self.back == State::Done || self.front > self.back
 593     }
 594
 595     #[inline]
 596     fn is_sep_byte(&self, b: u8) -> bool {
 597         if self.prefix_verbatim() {
 598             is_verbatim_sep(b)
 599         } else {
 600             is_sep_byte(b)
 601         }
 602     }
 603
 604     /// Extract a slice corresponding to the portion of the path remaining for iteration.
 605     pub fn as_path(&self) -> &'a Path {
 606         let mut comps = self.clone();
 607         if comps.front == State::Body { comps.trim_left(); }
 608         if comps.back == State::Body { comps.trim_right(); }
 609         unsafe { Path::from_u8_slice(comps.path) }
 610     }
 611
 612     /// Is the *original* path rooted?
 613     fn has_root(&self) -> bool {
 614         if self.has_physical_root { return true }
 615         if let Some(p) = self.prefix {
 616             if p.has_implicit_root() { return true }
 617         }
 618         false
 619     }
 620
 621     /// Should the normalized path include a leading . ?
 622     fn include_cur_dir(&self) -> bool {
 623         if self.has_root() { return false }
 624         let mut iter = self.path[self.prefix_len()..].iter();
 625         match (iter.next(), iter.next()) {
 626             (Some(&b'.'), None) => true,
 627             (Some(&b'.'), Some(&b)) => self.is_sep_byte(b),
 628             _ => false
 629         }
 630     }
 631
 632     // parse a given byte sequence into the corresponding path component
 633     fn parse_single_component<'b>(&self, comp: &'b [u8]) -> Option<Component<'b>> {
 634         match comp {
 635             b"." if self.prefix_verbatim() => Some(Component::CurDir),
 636             b"." => None, // . components are normalized away, except at
 637                           // the beginning of a path, which is treated
 638                           // separately via `include_cur_dir`
 639             b".." => Some(Component::ParentDir),
 640             b"" => None,
 641             _ => Some(Component::Normal(unsafe { u8_slice_as_os_str(comp) }))
 642         }
 643     }
 644
 645     // parse a component from the left, saying how many bytes to consume to
 646     // remove the component
 647     fn parse_next_component(&self) -> (usize, Option<Component<'a>>) {
 648         debug_assert!(self.front == State::Body);
 649         let (extra, comp) = match self.path.iter().position(|b| self.is_sep_byte(*b)) {
 650             None => (0, self.path),
 651             Some(i) => (1, &self.path[.. i]),
 652         };
 653         (comp.len() + extra, self.parse_single_component(comp))
 654     }
 655
 656     // parse a component from the right, saying how many bytes to consume to
 657     // remove the component
 658     fn parse_next_component_back(&self) -> (usize, Option<Component<'a>>) {
 659         debug_assert!(self.back == State::Body);
 660         let start = self.len_before_body();
 661         let (extra, comp) = match self.path[start..].iter().rposition(|b| self.is_sep_byte(*b)) {
 662             None => (0, &self.path[start ..]),
 663             Some(i) => (1, &self.path[start + i + 1 ..]),
 664         };
 665         (comp.len() + extra, self.parse_single_component(comp))
 666     }
 667
 668     // trim away repeated separators (i.e. emtpy components) on the left
 669     fn trim_left(&mut self) {
 670         while !self.path.is_empty() {
 671             let (size, comp) = self.parse_next_component();
 672             if comp.is_some() {
 673                 return;
 674             } else {
 675                 self.path = &self.path[size ..];
 676             }
 677         }
 678     }
 679
 680     // trim away repeated separators (i.e. emtpy components) on the right
 681     fn trim_right(&mut self) {
 682         while self.path.len() > self.len_before_body() {
 683             let (size, comp) = self.parse_next_component_back();
 684             if comp.is_some() {
 685                 return;
 686             } else {
 687                 self.path = &self.path[.. self.path.len() - size];
 688             }
 689         }
 690     }
 691
 692     /// Examine the next component without consuming it.
 693     #[unstable(feature = "path_components_peek")]
 694     pub fn peek(&self) -> Option<Component<'a>> {
 695         self.clone().next()
 696     }
 697 }
 698
 699 impl<'a> Iter<'a> {
 700     /// Extract a slice corresponding to the portion of the path remaining for iteration.
 701     #[stable(feature = "rust1", since = "1.0.0")]
 702     pub fn as_path(&self) -> &'a Path {
 703         self.inner.as_path()
 704     }
 705 }
 706
 707 #[stable(feature = "rust1", since = "1.0.0")]
 708 impl<'a> Iterator for Iter<'a> {
 709     type Item = &'a OsStr;
 710
 711     fn next(&mut self) -> Option<&'a OsStr> {
 712         self.inner.next().map(Component::as_os_str)
 713     }
 714 }
 715
 716 #[stable(feature = "rust1", since = "1.0.0")]
 717 impl<'a> DoubleEndedIterator for Iter<'a> {
 718     fn next_back(&mut self) -> Option<&'a OsStr> {
 719         self.inner.next_back().map(Component::as_os_str)
 720     }
 721 }
 722
 723 #[stable(feature = "rust1", since = "1.0.0")]
 724 impl<'a> Iterator for Components<'a> {
 725     type Item = Component<'a>;
 726
 727     fn next(&mut self) -> Option<Component<'a>> {
 728         while !self.finished() {
 729             match self.front {
 730                 State::Prefix if self.prefix_len() > 0 => {
 731                     self.front = State::StartDir;
 732                     debug_assert!(self.prefix_len() <= self.path.len());
 733                     let raw = &self.path[.. self.prefix_len()];
 734                     self.path = &self.path[self.prefix_len() .. ];
 735                     return Some(Component::Prefix(PrefixComponent {
 736                         raw: unsafe { u8_slice_as_os_str(raw) },
 737                         parsed: self.prefix.unwrap()
 738                     }))
 739                 }
 740                 State::Prefix => {
 741                     self.front = State::StartDir;
 742                 }
 743                 State::StartDir => {
 744                     self.front = State::Body;
 745                     if self.has_physical_root {
 746                         debug_assert!(self.path.len() > 0);
 747                         self.path = &self.path[1..];
 748                         return Some(Component::RootDir)
 749                     } else if let Some(p) = self.prefix {
 750                         if p.has_implicit_root() && !p.is_verbatim() {
 751                             return Some(Component::RootDir)
 752                         }
 753                     } else if self.include_cur_dir() {
 754                         debug_assert!(self.path.len() > 0);
 755                         self.path = &self.path[1..];
 756                         return Some(Component::CurDir)
 757                     }
 758                 }
 759                 State::Body if !self.path.is_empty() => {
 760                     let (size, comp) = self.parse_next_component();
 761                     self.path = &self.path[size ..];
 762                     if comp.is_some() { return comp }
 763                 }
 764                 State::Body => {
 765                     self.front = State::Done;
 766                 }
 767                 State::Done => unreachable!()
 768             }
 769         }
 770         None
 771     }
 772 }
 773
 774 #[stable(feature = "rust1", since = "1.0.0")]
 775 impl<'a> DoubleEndedIterator for Components<'a> {
 776     fn next_back(&mut self) -> Option<Component<'a>> {
 777         while !self.finished() {
 778             match self.back {
 779                 State::Body if self.path.len() > self.len_before_body() => {
 780                     let (size, comp) = self.parse_next_component_back();
 781                     self.path = &self.path[.. self.path.len() - size];
 782                     if comp.is_some() { return comp }
 783                 }
 784                 State::Body => {
 785                     self.back = State::StartDir;
 786                 }
 787                 State::StartDir => {
 788                     self.back = State::Prefix;
 789                     if self.has_physical_root {
 790                         self.path = &self.path[.. self.path.len() - 1];
 791                         return Some(Component::RootDir)
 792                     } else if let Some(p) = self.prefix {
 793                         if p.has_implicit_root() && !p.is_verbatim() {
 794                             return Some(Component::RootDir)
 795                         }
 796                     } else if self.include_cur_dir() {
 797                         self.path = &self.path[.. self.path.len() - 1];
 798                         return Some(Component::CurDir)
 799                     }
 800                 }
 801                 State::Prefix if self.prefix_len() > 0 => {
 802                     self.back = State::Done;
 803                     return Some(Component::Prefix(PrefixComponent {
 804                         raw: unsafe { u8_slice_as_os_str(self.path) },
 805                         parsed: self.prefix.unwrap()
 806                     }))
 807                 }
 808                 State::Prefix => {
 809                     self.back = State::Done;
 810                     return None
 811                 }
 812                 State::Done => unreachable!()
 813             }
 814         }
 815         None
 816     }
 817 }
 818
 819 #[stable(feature = "rust1", since = "1.0.0")]
 820 impl<'a> cmp::PartialEq for Components<'a> {
 821     fn eq(&self, other: &Components<'a>) -> bool {
 822         iter::order::eq(self.clone(), other.clone())
 823     }
 824 }
 825
 826 #[stable(feature = "rust1", since = "1.0.0")]
 827 impl<'a> cmp::Eq for Components<'a> {}
 828
 829 #[stable(feature = "rust1", since = "1.0.0")]
 830 impl<'a> cmp::PartialOrd for Components<'a> {
 831     fn partial_cmp(&self, other: &Components<'a>) -> Option<cmp::Ordering> {
 832         iter::order::partial_cmp(self.clone(), other.clone())
 833     }
 834 }
 835
 836 #[stable(feature = "rust1", since = "1.0.0")]
 837 impl<'a> cmp::Ord for Components<'a> {
 838     fn cmp(&self, other: &Components<'a>) -> cmp::Ordering {
 839         iter::order::cmp(self.clone(), other.clone())
 840     }
 841 }
 842
 843 ////////////////////////////////////////////////////////////////////////////////
 844 // Basic types and traits
 845 ////////////////////////////////////////////////////////////////////////////////
 846
 847 /// An owned, mutable path (akin to `String`).
 848 ///
 849 /// This type provides methods like `push` and `set_extension` that mutate the
 850 /// path in place. It also implements `Deref` to `Path`, meaning that all
 851 /// methods on `Path` slices are available on `PathBuf` values as well.
 852 ///
 853 /// More details about the overall approach can be found in
 854 /// the module documentation.
 855 ///
 856 /// # Examples
 857 ///
 858 /// ```rust
 859 /// use std::path::PathBuf;
 860 ///
 861 /// let mut path = PathBuf::new("c:\\");
 862 /// path.push("windows");
 863 /// path.push("system32");
 864 /// path.set_extension("dll");
 865 /// ```
 866 #[derive(Clone, Hash)]
 867 #[stable(feature = "rust1", since = "1.0.0")]
 868 pub struct PathBuf {
 869     inner: OsString
 870 }
 871
 872 impl PathBuf {
 873     fn as_mut_vec(&mut self) -> &mut Vec<u8> {
 874         unsafe { mem::transmute(self) }
 875     }
 876
 877     /// Allocate a `PathBuf` with initial contents given by the
 878     /// argument.
 879     #[stable(feature = "rust1", since = "1.0.0")]
 880     pub fn new<S: AsOsStr>(s: S) -> PathBuf {
 881         PathBuf { inner: s.as_os_str().to_os_string() }
 882     }
 883
 884     /// Extend `self` with `path`.
 885     ///
 886     /// If `path` is absolute, it replaces the current path.
 887     ///
 888     /// On Windows:
 889     ///
 890     /// * if `path` has a root but no prefix (e.g. `\windows`), it
 891     ///   replaces everything except for the prefix (if any) of `self`.
 892     /// * if `path` has a prefix but no root, it replaces `self.
 893     #[stable(feature = "rust1", since = "1.0.0")]
 894     pub fn push<P: AsPath>(&mut self, path: P) {
 895         let path = path.as_path();
 896
 897         // in general, a separator is needed if the rightmost byte is not a separator
 898         let mut need_sep = self.as_mut_vec().last().map(|c| !is_sep_byte(*c)).unwrap_or(false);
 899
 900         // in the special case of `C:` on Windows, do *not* add a separator
 901         {
 902             let comps = self.components();
 903             if comps.prefix_len() > 0 &&
 904                 comps.prefix_len() == comps.path.len() &&
 905                 comps.prefix.unwrap().is_drive()
 906             {
 907                 need_sep = false
 908             }
 909         }
 910
 911         // absolute `path` replaces `self`
 912         if path.is_absolute() || path.prefix().is_some() {
 913             self.as_mut_vec().truncate(0);
 914
 915         // `path` has a root but no prefix, e.g. `\windows` (Windows only)
 916         } else if path.has_root() {
 917             let prefix_len = self.components().prefix_remaining();
 918             self.as_mut_vec().truncate(prefix_len);
 919
 920         // `path` is a pure relative path
 921         } else if need_sep {
 922             self.inner.push(MAIN_SEP_STR);
 923         }
 924
 925         self.inner.push(path);
 926     }
 927
 928     /// Truncate `self` to `self.parent()`.
 929     ///
 930     /// Returns false and does nothing if `self.file_name()` is `None`.
 931     /// Otherwise, returns `true`.
 932     #[stable(feature = "rust1", since = "1.0.0")]
 933     pub fn pop(&mut self) -> bool {
 934         match self.parent().map(|p| p.as_u8_slice().len()) {
 935             Some(len) => {
 936                 self.as_mut_vec().truncate(len);
 937                 true
 938             }
 939             None => false
 940         }
 941     }
 942
 943     /// Updates `self.file_name()` to `file_name`.
 944     ///
 945     /// If `self.file_name()` was `None`, this is equivalent to pushing
 946     /// `file_name`.
 947     ///
 948     /// # Examples
 949     ///
 950     /// ```rust
 951     /// use std::path::PathBuf;
 952     ///
 953     /// let mut buf = PathBuf::new("/");
 954     /// assert!(buf.file_name() == None);
 955     /// buf.set_file_name("bar");
 956     /// assert!(buf == PathBuf::new("/bar"));
 957     /// assert!(buf.file_name().is_some());
 958     /// buf.set_file_name("baz.txt");
 959     /// assert!(buf == PathBuf::new("/baz.txt"));
 960     /// ```
 961     #[stable(feature = "rust1", since = "1.0.0")]
 962     pub fn set_file_name<S: AsOsStr>(&mut self, file_name: S) {
 963         if self.file_name().is_some() {
 964             let popped = self.pop();
 965             debug_assert!(popped);
 966         }
 967         self.push(file_name.as_os_str());
 968     }
 969
 970     /// Updates `self.extension()` to `extension`.
 971     ///
 972     /// If `self.file_name()` is `None`, does nothing and returns `false`.
 973     ///
 974     /// Otherwise, returns `true`; if `self.extension()` is `None`, the extension
 975     /// is added; otherwise it is replaced.
 976     #[stable(feature = "rust1", since = "1.0.0")]
 977     pub fn set_extension<S: AsOsStr>(&mut self, extension: S) -> bool {
 978         if self.file_name().is_none() { return false; }
 979
 980         let mut stem = match self.file_stem() {
 981             Some(stem) => stem.to_os_string(),
 982             None => OsString::from_str(""),
 983         };
 984
 985         let extension = extension.as_os_str();
 986         if os_str_as_u8_slice(extension).len() > 0 {
 987             stem.push(".");
 988             stem.push(extension);
 989         }
 990         self.set_file_name(&stem);
 991
 992         true
 993     }
 994
 995     /// Consume the `PathBuf`, yielding its internal `OsString` storage
 996     #[stable(feature = "rust1", since = "1.0.0")]
 997     pub fn into_os_string(self) -> OsString {
 998         self.inner
 999     }
1000 }
1001
1002 #[stable(feature = "rust1", since = "1.0.0")]
1003 impl<P: AsPath> iter::FromIterator<P> for PathBuf {
1004     fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> PathBuf {
1005         let mut buf = PathBuf::new("");
1006         buf.extend(iter);
1007         buf
1008     }
1009 }
1010
1011 #[stable(feature = "rust1", since = "1.0.0")]
1012 impl<P: AsPath> iter::Extend<P> for PathBuf {
1013     fn extend<I: IntoIterator<Item = P>>(&mut self, iter: I) {
1014         for p in iter {
1015             self.push(p)
1016         }
1017     }
1018 }
1019
1020 #[stable(feature = "rust1", since = "1.0.0")]
1021 impl fmt::Debug for PathBuf {
1022     fn fmt(&self, formatter: &mut fmt::Formatter) -> Result<(), fmt::Error> {
1023         fmt::Debug::fmt(&**self, formatter)
1024     }
1025 }
1026
1027 #[stable(feature = "rust1", since = "1.0.0")]
1028 impl ops::Deref for PathBuf {
1029     type Target = Path;
1030
1031     fn deref(&self) -> &Path {
1032         unsafe { mem::transmute(&self.inner[..]) }
1033     }
1034 }
1035
1036 #[stable(feature = "rust1", since = "1.0.0")]
1037 impl Borrow<Path> for PathBuf {
1038     fn borrow(&self) -> &Path {
1039         self.deref()
1040     }
1041 }
1042
1043 #[stable(feature = "rust1", since = "1.0.0")]
1044 impl IntoCow<'static, Path> for PathBuf {
1045     fn into_cow(self) -> Cow<'static, Path> {
1046         Cow::Owned(self)
1047     }
1048 }
1049
1050 #[stable(feature = "rust1", since = "1.0.0")]
1051 impl<'a> IntoCow<'a, Path> for &'a Path {
1052     fn into_cow(self) -> Cow<'a, Path> {
1053         Cow::Borrowed(self)
1054     }
1055 }
1056
1057 #[stable(feature = "rust1", since = "1.0.0")]
1058 impl ToOwned for Path {
1059     type Owned = PathBuf;
1060     fn to_owned(&self) -> PathBuf { self.to_path_buf() }
1061 }
1062
1063 #[stable(feature = "rust1", since = "1.0.0")]
1064 impl cmp::PartialEq for PathBuf {
1065     fn eq(&self, other: &PathBuf) -> bool {
1066         self.components() == other.components()
1067     }
1068 }
1069
1070 #[stable(feature = "rust1", since = "1.0.0")]
1071 impl cmp::Eq for PathBuf {}
1072
1073 #[stable(feature = "rust1", since = "1.0.0")]
1074 impl cmp::PartialOrd for PathBuf {
1075     fn partial_cmp(&self, other: &PathBuf) -> Option<cmp::Ordering> {
1076         self.components().partial_cmp(&other.components())
1077     }
1078 }
1079
1080 #[stable(feature = "rust1", since = "1.0.0")]
1081 impl cmp::Ord for PathBuf {
1082     fn cmp(&self, other: &PathBuf) -> cmp::Ordering {
1083         self.components().cmp(&other.components())
1084     }
1085 }
1086
1087 #[stable(feature = "rust1", since = "1.0.0")]
1088 impl AsOsStr for PathBuf {
1089     fn as_os_str(&self) -> &OsStr {
1090         &self.inner[..]
1091     }
1092 }
1093
1094 /// A slice of a path (akin to `str`).
1095 ///
1096 /// This type supports a number of operations for inspecting a path, including
1097 /// breaking the path into its components (separated by `/` or `\`, depending on
1098 /// the platform), extracting the file name, determining whether the path is
1099 /// absolute, and so on. More details about the overall approach can be found in
1100 /// the module documentation.
1101 ///
1102 /// This is an *unsized* type, meaning that it must always be used with behind a
1103 /// pointer like `&` or `Box`.
1104 ///
1105 /// # Examples
1106 ///
1107 /// ```rust
1108 /// use std::path::Path;
1109 ///
1110 /// let path = Path::new("/tmp/foo/bar.txt");
1111 /// let file = path.file_name();
1112 /// let extension = path.extension();
1113 /// let parent_dir = path.parent();
1114 /// ```
1115 ///
1116 #[derive(Hash)]
1117 #[stable(feature = "rust1", since = "1.0.0")]
1118 pub struct Path {
1119     inner: OsStr
1120 }
1121
1122 impl Path {
1123     // The following (private!) function allows construction of a path from a u8
1124     // slice, which is only safe when it is known to follow the OsStr encoding.
1125     unsafe fn from_u8_slice(s: &[u8]) -> &Path {
1126         mem::transmute(s)
1127     }
1128     // The following (private!) function reveals the byte encoding used for OsStr.
1129     fn as_u8_slice(&self) -> &[u8] {
1130         unsafe { mem::transmute(self) }
1131     }
1132
1133     /// Directly wrap a string slice as a `Path` slice.
1134     ///
1135     /// This is a cost-free conversion.
1136     #[stable(feature = "rust1", since = "1.0.0")]
1137     pub fn new<S: ?Sized + AsOsStr>(s: &S) -> &Path {
1138         unsafe { mem::transmute(s.as_os_str()) }
1139     }
1140
1141     /// Yield a `&str` slice if the `Path` is valid unicode.
1142     ///
1143     /// This conversion may entail doing a check for UTF-8 validity.
1144     #[stable(feature = "rust1", since = "1.0.0")]
1145     pub fn to_str(&self) -> Option<&str> {
1146         self.inner.to_str()
1147     }
1148
1149     /// Convert a `Path` to a `Cow<str>`.
1150     ///
1151     /// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
1152     #[stable(feature = "rust1", since = "1.0.0")]
1153     pub fn to_string_lossy(&self) -> Cow<str> {
1154         self.inner.to_string_lossy()
1155     }
1156
1157     /// Convert a `Path` to an owned `PathBuf`.
1158     #[stable(feature = "rust1", since = "1.0.0")]
1159     pub fn to_path_buf(&self) -> PathBuf {
1160         PathBuf::new(self)
1161     }
1162
1163     /// A path is *absolute* if it is independent of the current directory.
1164     ///
1165     /// * On Unix, a path is absolute if it starts with the root, so
1166     /// `is_absolute` and `has_root` are equivalent.
1167     ///
1168     /// * On Windows, a path is absolute if it has a prefix and starts with the
1169     /// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. In
1170     /// other words, `path.is_absolute() == path.prefix().is_some() && path.has_root()`.
1171     #[stable(feature = "rust1", since = "1.0.0")]
1172     pub fn is_absolute(&self) -> bool {
1173         self.has_root() &&
1174             (cfg!(unix) || self.prefix().is_some())
1175     }
1176
1177     /// A path is *relative* if it is not absolute.
1178     #[stable(feature = "rust1", since = "1.0.0")]
1179     pub fn is_relative(&self) -> bool {
1180         !self.is_absolute()
1181     }
1182
1183     /// Returns the *prefix* of a path, if any.
1184     ///
1185     /// Prefixes are relevant only for Windows paths, and consist of volumes
1186     /// like `C:`, UNC prefixes like `\\server`, and others described in more
1187     /// detail in `std::os::windows::PathExt`.
1188     #[unstable(feature = "path_prefix", reason = "uncertain whether to expose this convenience")]
1189     pub fn prefix(&self) -> Option<Prefix> {
1190         self.components().prefix
1191     }
1192
1193     /// A path has a root if the body of the path begins with the directory separator.
1194     ///
1195     /// * On Unix, a path has a root if it begins with `/`.
1196     ///
1197     /// * On Windows, a path has a root if it:
1198     ///     * has no prefix and begins with a separator, e.g. `\\windows`
1199     ///     * has a prefix followed by a separator, e.g. `c:\windows` but not `c:windows`
1200     ///     * has any non-disk prefix, e.g. `\\server\share`
1201     #[stable(feature = "rust1", since = "1.0.0")]
1202     pub fn has_root(&self) -> bool {
1203          self.components().has_root()
1204     }
1205
1206     /// The path without its final component, if any.
1207     ///
1208     /// Returns `None` if the path terminates in a root or prefix.
1209     ///
1210     /// # Examples
1211     ///
1212     /// ```rust
1213     /// use std::path::Path;
1214     ///
1215     /// let path = Path::new("/foo/bar");
1216     /// let foo = path.parent().unwrap();
1217     /// assert!(foo == Path::new("/foo"));
1218     /// let root = foo.parent().unwrap();
1219     /// assert!(root == Path::new("/"));
1220     /// assert!(root.parent() == None);
1221     /// ```
1222     #[stable(feature = "rust1", since = "1.0.0")]
1223     pub fn parent(&self) -> Option<&Path> {
1224         let mut comps = self.components();
1225         let comp = comps.next_back();
1226         comp.and_then(|p| match p {
1227             Component::Normal(_) |
1228             Component::CurDir |
1229             Component::ParentDir => Some(comps.as_path()),
1230             _ => None
1231         })
1232     }
1233
1234     /// The final component of the path, if it is a normal file.
1235     ///
1236     /// If the path terminates in `.`, `..`, or consists solely or a root of
1237     /// prefix, `file_name` will return `None`.
1238     #[stable(feature = "rust1", since = "1.0.0")]
1239     pub fn file_name(&self) -> Option<&OsStr> {
1240         self.components().next_back().and_then(|p| match p {
1241             Component::Normal(p) => Some(p.as_os_str()),
1242             _ => None
1243         })
1244     }
1245
1246     /// Returns a path that, when joined onto `base`, yields `self`.
1247     #[unstable(feature = "path_relative_from", reason = "see #23284")]
1248     pub fn relative_from<'a, P: ?Sized>(&'a self, base: &'a P) -> Option<&Path> where
1249         P: AsPath
1250     {
1251         iter_after(self.components(), base.as_path().components()).map(|c| c.as_path())
1252     }
1253
1254     /// Determines whether `base` is a prefix of `self`.
1255     #[stable(feature = "rust1", since = "1.0.0")]
1256     pub fn starts_with<P: AsPath>(&self, base: P) -> bool {
1257         iter_after(self.components(), base.as_path().components()).is_some()
1258     }
1259
1260     /// Determines whether `child` is a suffix of `self`.
1261     #[stable(feature = "rust1", since = "1.0.0")]
1262     pub fn ends_with<P: AsPath>(&self, child: P) -> bool {
1263         iter_after(self.components().rev(), child.as_path().components().rev()).is_some()
1264     }
1265
1266     /// Extract the stem (non-extension) portion of `self.file()`.
1267     ///
1268     /// The stem is:
1269     ///
1270     /// * None, if there is no file name;
1271     /// * The entire file name if there is no embedded `.`;
1272     /// * The entire file name if the file name begins with `.` and has no other `.`s within;
1273     /// * Otherwise, the portion of the file name before the final `.`
1274     #[stable(feature = "rust1", since = "1.0.0")]
1275     pub fn file_stem(&self) -> Option<&OsStr> {
1276         self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after))
1277     }
1278
1279     /// Extract the extension of `self.file()`, if possible.
1280     ///
1281     /// The extension is:
1282     ///
1283     /// * None, if there is no file name;
1284     /// * None, if there is no embedded `.`;
1285     /// * None, if the file name begins with `.` and has no other `.`s within;
1286     /// * Otherwise, the portion of the file name after the final `.`
1287     #[stable(feature = "rust1", since = "1.0.0")]
1288     pub fn extension(&self) -> Option<&OsStr> {
1289         self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.and(after))
1290     }
1291
1292     /// Creates an owned `PathBuf` with `path` adjoined to `self`.
1293     ///
1294     /// See `PathBuf::push` for more details on what it means to adjoin a path.
1295     #[stable(feature = "rust1", since = "1.0.0")]
1296     pub fn join<P: AsPath>(&self, path: P) -> PathBuf {
1297         let mut buf = self.to_path_buf();
1298         buf.push(path);
1299         buf
1300     }
1301
1302     /// Creates an owned `PathBuf` like `self` but with the given file name.
1303     ///
1304     /// See `PathBuf::set_file_name` for more details.
1305     #[stable(feature = "rust1", since = "1.0.0")]
1306     pub fn with_file_name<S: AsOsStr>(&self, file_name: S) -> PathBuf {
1307         let mut buf = self.to_path_buf();
1308         buf.set_file_name(file_name);
1309         buf
1310     }
1311
1312     /// Creates an owned `PathBuf` like `self` but with the given extension.
1313     ///
1314     /// See `PathBuf::set_extension` for more details.
1315     #[stable(feature = "rust1", since = "1.0.0")]
1316     pub fn with_extension<S: AsOsStr>(&self, extension: S) -> PathBuf {
1317         let mut buf = self.to_path_buf();
1318         buf.set_extension(extension);
1319         buf
1320     }
1321
1322     /// Produce an iterator over the components of the path.
1323     #[stable(feature = "rust1", since = "1.0.0")]
1324     pub fn components(&self) -> Components {
1325         let prefix = parse_prefix(self.as_os_str());
1326         Components {
1327             path: self.as_u8_slice(),
1328             prefix: prefix,
1329             has_physical_root: has_physical_root(self.as_u8_slice(), prefix),
1330             front: State::Prefix,
1331             back: State::Body,
1332         }
1333     }
1334
1335     /// Produce an iterator over the path's components viewed as `OsStr` slices.
1336     #[stable(feature = "rust1", since = "1.0.0")]
1337     pub fn iter(&self) -> Iter {
1338         Iter { inner: self.components() }
1339     }
1340
1341     /// Returns an object that implements `Display` for safely printing paths
1342     /// that may contain non-Unicode data.
1343     #[stable(feature = "rust1", since = "1.0.0")]
1344     pub fn display(&self) -> Display {
1345         Display { path: self }
1346     }
1347 }
1348
1349 #[stable(feature = "rust1", since = "1.0.0")]
1350 impl AsOsStr for Path {
1351     fn as_os_str(&self) -> &OsStr {
1352         &self.inner
1353     }
1354 }
1355
1356 #[stable(feature = "rust1", since = "1.0.0")]
1357 impl fmt::Debug for Path {
1358     fn fmt(&self, formatter: &mut fmt::Formatter) -> Result<(), fmt::Error> {
1359         self.inner.fmt(formatter)
1360     }
1361 }
1362
1363 /// Helper struct for safely printing paths with `format!()` and `{}`
1364 #[stable(feature = "rust1", since = "1.0.0")]
1365 pub struct Display<'a> {
1366     path: &'a Path
1367 }
1368
1369 #[stable(feature = "rust1", since = "1.0.0")]
1370 impl<'a> fmt::Debug for Display<'a> {
1371     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1372         fmt::Debug::fmt(&self.path.to_string_lossy(), f)
1373     }
1374 }
1375
1376 #[stable(feature = "rust1", since = "1.0.0")]
1377 impl<'a> fmt::Display for Display<'a> {
1378     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1379         fmt::Display::fmt(&self.path.to_string_lossy(), f)
1380     }
1381 }
1382
1383 #[stable(feature = "rust1", since = "1.0.0")]
1384 impl cmp::PartialEq for Path {
1385     fn eq(&self, other: &Path) -> bool {
1386         iter::order::eq(self.components(), other.components())
1387     }
1388 }
1389
1390 #[stable(feature = "rust1", since = "1.0.0")]
1391 impl cmp::Eq for Path {}
1392
1393 #[stable(feature = "rust1", since = "1.0.0")]
1394 impl cmp::PartialOrd for Path {
1395     fn partial_cmp(&self, other: &Path) -> Option<cmp::Ordering> {
1396         self.components().partial_cmp(&other.components())
1397     }
1398 }
1399
1400 #[stable(feature = "rust1", since = "1.0.0")]
1401 impl cmp::Ord for Path {
1402     fn cmp(&self, other: &Path) -> cmp::Ordering {
1403         self.components().cmp(&other.components())
1404     }
1405 }
1406
1407 /// Freely convertible to a `Path`.
1408 #[unstable(feature = "std_misc")]
1409 pub trait AsPath {
1410     /// Convert to a `Path`.
1411     #[unstable(feature = "std_misc")]
1412     fn as_path(&self) -> &Path;
1413 }
1414
1415 #[unstable(feature = "std_misc")]
1416 impl<T: AsOsStr + ?Sized> AsPath for T {
1417     fn as_path(&self) -> &Path { Path::new(self.as_os_str()) }
1418 }
1419
1420 #[cfg(test)]
1421 mod tests {
1422     use super::*;
1423     use core::prelude::*;
1424     use string::{ToString, String};
1425     use vec::Vec;
1426
1427     macro_rules! t(
1428         ($path:expr, iter: $iter:expr) => (
1429             {
1430                 let path = Path::new($path);
1431
1432                 // Forward iteration
1433                 let comps = path.iter()
1434                     .map(|p| p.to_string_lossy().into_owned())
1435                     .collect::<Vec<String>>();
1436                 let exp: &[&str] = &$iter;
1437                 let exps = exp.iter().map(|s| s.to_string()).collect::<Vec<String>>();
1438                 assert!(comps == exps, "iter: Expected {:?}, found {:?}",
1439                         exps, comps);
1440
1441                 // Reverse iteration
1442                 let comps = Path::new($path).iter().rev()
1443                     .map(|p| p.to_string_lossy().into_owned())
1444                     .collect::<Vec<String>>();
1445                 let exps = exps.into_iter().rev().collect::<Vec<String>>();
1446                 assert!(comps == exps, "iter().rev(): Expected {:?}, found {:?}",
1447                         exps, comps);
1448             }
1449         );
1450
1451         ($path:expr, has_root: $has_root:expr, is_absolute: $is_absolute:expr) => (
1452             {
1453                 let path = Path::new($path);
1454
1455                 let act_root = path.has_root();
1456                 assert!(act_root == $has_root, "has_root: Expected {:?}, found {:?}",
1457                         $has_root, act_root);
1458
1459                 let act_abs = path.is_absolute();
1460                 assert!(act_abs == $is_absolute, "is_absolute: Expected {:?}, found {:?}",
1461                         $is_absolute, act_abs);
1462             }
1463         );
1464
1465         ($path:expr, parent: $parent:expr, file_name: $file:expr) => (
1466             {
1467                 let path = Path::new($path);
1468
1469                 let parent = path.parent().map(|p| p.to_str().unwrap());
1470                 let exp_parent: Option<&str> = $parent;
1471                 assert!(parent == exp_parent, "parent: Expected {:?}, found {:?}",
1472                         exp_parent, parent);
1473
1474                 let file = path.file_name().map(|p| p.to_str().unwrap());
1475                 let exp_file: Option<&str> = $file;
1476                 assert!(file == exp_file, "file_name: Expected {:?}, found {:?}",
1477                         exp_file, file);
1478             }
1479         );
1480
1481         ($path:expr, file_stem: $file_stem:expr, extension: $extension:expr) => (
1482             {
1483                 let path = Path::new($path);
1484
1485                 let stem = path.file_stem().map(|p| p.to_str().unwrap());
1486                 let exp_stem: Option<&str> = $file_stem;
1487                 assert!(stem == exp_stem, "file_stem: Expected {:?}, found {:?}",
1488                         exp_stem, stem);
1489
1490                 let ext = path.extension().map(|p| p.to_str().unwrap());
1491                 let exp_ext: Option<&str> = $extension;
1492                 assert!(ext == exp_ext, "extension: Expected {:?}, found {:?}",
1493                         exp_ext, ext);
1494             }
1495         );
1496
1497         ($path:expr, iter: $iter:expr,
1498                      has_root: $has_root:expr, is_absolute: $is_absolute:expr,
1499                      parent: $parent:expr, file_name: $file:expr,
1500                      file_stem: $file_stem:expr, extension: $extension:expr) => (
1501             {
1502                 t!($path, iter: $iter);
1503                 t!($path, has_root: $has_root, is_absolute: $is_absolute);
1504                 t!($path, parent: $parent, file_name: $file);
1505                 t!($path, file_stem: $file_stem, extension: $extension);
1506             }
1507         );
1508     );
1509
1510     #[test]
1511     fn into_cow() {
1512         use borrow::{Cow, IntoCow};
1513
1514         let static_path = Path::new("/home/foo");
1515         let static_cow_path: Cow<'static, Path> = static_path.into_cow();
1516         let pathbuf = PathBuf::new("/home/foo");
1517
1518         {
1519             let path: &Path = &pathbuf;
1520             let borrowed_cow_path: Cow<Path> = path.into_cow();
1521
1522             assert_eq!(static_cow_path, borrowed_cow_path);
1523         }
1524
1525         let owned_cow_path: Cow<'static, Path> = pathbuf.into_cow();
1526
1527         assert_eq!(static_cow_path, owned_cow_path);
1528     }
1529
1530     #[test]
1531     #[cfg(unix)]
1532     pub fn test_decompositions_unix() {
1533         t!("",
1534            iter: [],
1535            has_root: false,
1536            is_absolute: false,
1537            parent: None,
1538            file_name: None,
1539            file_stem: None,
1540            extension: None
1541            );
1542
1543         t!("foo",
1544            iter: ["foo"],
1545            has_root: false,
1546            is_absolute: false,
1547            parent: Some(""),
1548            file_name: Some("foo"),
1549            file_stem: Some("foo"),
1550            extension: None
1551            );
1552
1553         t!("/",
1554            iter: ["/"],
1555            has_root: true,
1556            is_absolute: true,
1557            parent: None,
1558            file_name: None,
1559            file_stem: None,
1560            extension: None
1561            );
1562
1563         t!("/foo",
1564            iter: ["/", "foo"],
1565            has_root: true,
1566            is_absolute: true,
1567            parent: Some("/"),
1568            file_name: Some("foo"),
1569            file_stem: Some("foo"),
1570            extension: None
1571            );
1572
1573         t!("foo/",
1574            iter: ["foo"],
1575            has_root: false,
1576            is_absolute: false,
1577            parent: Some(""),
1578            file_name: Some("foo"),
1579            file_stem: Some("foo"),
1580            extension: None
1581            );
1582
1583         t!("/foo/",
1584            iter: ["/", "foo"],
1585            has_root: true,
1586            is_absolute: true,
1587            parent: Some("/"),
1588            file_name: Some("foo"),
1589            file_stem: Some("foo"),
1590            extension: None
1591            );
1592
1593         t!("foo/bar",
1594            iter: ["foo", "bar"],
1595            has_root: false,
1596            is_absolute: false,
1597            parent: Some("foo"),
1598            file_name: Some("bar"),
1599            file_stem: Some("bar"),
1600            extension: None
1601            );
1602
1603         t!("/foo/bar",
1604            iter: ["/", "foo", "bar"],
1605            has_root: true,
1606            is_absolute: true,
1607            parent: Some("/foo"),
1608            file_name: Some("bar"),
1609            file_stem: Some("bar"),
1610            extension: None
1611            );
1612
1613         t!("///foo///",
1614            iter: ["/", "foo"],
1615            has_root: true,
1616            is_absolute: true,
1617            parent: Some("/"),
1618            file_name: Some("foo"),
1619            file_stem: Some("foo"),
1620            extension: None
1621            );
1622
1623         t!("///foo///bar",
1624            iter: ["/", "foo", "bar"],
1625            has_root: true,
1626            is_absolute: true,
1627            parent: Some("///foo"),
1628            file_name: Some("bar"),
1629            file_stem: Some("bar"),
1630            extension: None
1631            );
1632
1633         t!("./.",
1634            iter: ["."],
1635            has_root: false,
1636            is_absolute: false,
1637            parent: Some(""),
1638            file_name: None,
1639            file_stem: None,
1640            extension: None
1641            );
1642
1643         t!("/..",
1644            iter: ["/", ".."],
1645            has_root: true,
1646            is_absolute: true,
1647            parent: Some("/"),
1648            file_name: None,
1649            file_stem: None,
1650            extension: None
1651            );
1652
1653         t!("../",
1654            iter: [".."],
1655            has_root: false,
1656            is_absolute: false,
1657            parent: Some(""),
1658            file_name: None,
1659            file_stem: None,
1660            extension: None
1661            );
1662
1663         t!("foo/.",
1664            iter: ["foo"],
1665            has_root: false,
1666            is_absolute: false,
1667            parent: Some(""),
1668            file_name: Some("foo"),
1669            file_stem: Some("foo"),
1670            extension: None
1671            );
1672
1673         t!("foo/..",
1674            iter: ["foo", ".."],
1675            has_root: false,
1676            is_absolute: false,
1677            parent: Some("foo"),
1678            file_name: None,
1679            file_stem: None,
1680            extension: None
1681            );
1682
1683         t!("foo/./",
1684            iter: ["foo"],
1685            has_root: false,
1686            is_absolute: false,
1687            parent: Some(""),
1688            file_name: Some("foo"),
1689            file_stem: Some("foo"),
1690            extension: None
1691            );
1692
1693         t!("foo/./bar",
1694            iter: ["foo", "bar"],
1695            has_root: false,
1696            is_absolute: false,
1697            parent: Some("foo"),
1698            file_name: Some("bar"),
1699            file_stem: Some("bar"),
1700            extension: None
1701            );
1702
1703         t!("foo/../",
1704            iter: ["foo", ".."],
1705            has_root: false,
1706            is_absolute: false,
1707            parent: Some("foo"),
1708            file_name: None,
1709            file_stem: None,
1710            extension: None
1711            );
1712
1713         t!("foo/../bar",
1714            iter: ["foo", "..", "bar"],
1715            has_root: false,
1716            is_absolute: false,
1717            parent: Some("foo/.."),
1718            file_name: Some("bar"),
1719            file_stem: Some("bar"),
1720            extension: None
1721            );
1722
1723         t!("./a",
1724            iter: [".", "a"],
1725            has_root: false,
1726            is_absolute: false,
1727            parent: Some("."),
1728            file_name: Some("a"),
1729            file_stem: Some("a"),
1730            extension: None
1731            );
1732
1733         t!(".",
1734            iter: ["."],
1735            has_root: false,
1736            is_absolute: false,
1737            parent: Some(""),
1738            file_name: None,
1739            file_stem: None,
1740            extension: None
1741            );
1742
1743         t!("./",
1744            iter: ["."],
1745            has_root: false,
1746            is_absolute: false,
1747            parent: Some(""),
1748            file_name: None,
1749            file_stem: None,
1750            extension: None
1751            );
1752
1753         t!("a/b",
1754            iter: ["a", "b"],
1755            has_root: false,
1756            is_absolute: false,
1757            parent: Some("a"),
1758            file_name: Some("b"),
1759            file_stem: Some("b"),
1760            extension: None
1761            );
1762
1763         t!("a//b",
1764            iter: ["a", "b"],
1765            has_root: false,
1766            is_absolute: false,
1767            parent: Some("a"),
1768            file_name: Some("b"),
1769            file_stem: Some("b"),
1770            extension: None
1771            );
1772
1773         t!("a/./b",
1774            iter: ["a", "b"],
1775            has_root: false,
1776            is_absolute: false,
1777            parent: Some("a"),
1778            file_name: Some("b"),
1779            file_stem: Some("b"),
1780            extension: None
1781            );
1782
1783         t!("a/b/c",
1784            iter: ["a", "b", "c"],
1785            has_root: false,
1786            is_absolute: false,
1787            parent: Some("a/b"),
1788            file_name: Some("c"),
1789            file_stem: Some("c"),
1790            extension: None
1791            );
1792
1793         t!(".foo",
1794            iter: [".foo"],
1795            has_root: false,
1796            is_absolute: false,
1797            parent: Some(""),
1798            file_name: Some(".foo"),
1799            file_stem: Some(".foo"),
1800            extension: None
1801            );
1802     }
1803
1804     #[test]
1805     #[cfg(windows)]
1806     pub fn test_decompositions_windows() {
1807         t!("",
1808            iter: [],
1809            has_root: false,
1810            is_absolute: false,
1811            parent: None,
1812            file_name: None,
1813            file_stem: None,
1814            extension: None
1815            );
1816
1817         t!("foo",
1818            iter: ["foo"],
1819            has_root: false,
1820            is_absolute: false,
1821            parent: Some(""),
1822            file_name: Some("foo"),
1823            file_stem: Some("foo"),
1824            extension: None
1825            );
1826
1827         t!("/",
1828            iter: ["\\"],
1829            has_root: true,
1830            is_absolute: false,
1831            parent: None,
1832            file_name: None,
1833            file_stem: None,
1834            extension: None
1835            );
1836
1837         t!("\\",
1838            iter: ["\\"],
1839            has_root: true,
1840            is_absolute: false,
1841            parent: None,
1842            file_name: None,
1843            file_stem: None,
1844            extension: None
1845            );
1846
1847         t!("c:",
1848            iter: ["c:"],
1849            has_root: false,
1850            is_absolute: false,
1851            parent: None,
1852            file_name: None,
1853            file_stem: None,
1854            extension: None
1855            );
1856
1857         t!("c:\\",
1858            iter: ["c:", "\\"],
1859            has_root: true,
1860            is_absolute: true,
1861            parent: None,
1862            file_name: None,
1863            file_stem: None,
1864            extension: None
1865            );
1866
1867         t!("c:/",
1868            iter: ["c:", "\\"],
1869            has_root: true,
1870            is_absolute: true,
1871            parent: None,
1872            file_name: None,
1873            file_stem: None,
1874            extension: None
1875            );
1876
1877         t!("/foo",
1878            iter: ["\\", "foo"],
1879            has_root: true,
1880            is_absolute: false,
1881            parent: Some("/"),
1882            file_name: Some("foo"),
1883            file_stem: Some("foo"),
1884            extension: None
1885            );
1886
1887         t!("foo/",
1888            iter: ["foo"],
1889            has_root: false,
1890            is_absolute: false,
1891            parent: Some(""),
1892            file_name: Some("foo"),
1893            file_stem: Some("foo"),
1894            extension: None
1895            );
1896
1897         t!("/foo/",
1898            iter: ["\\", "foo"],
1899            has_root: true,
1900            is_absolute: false,
1901            parent: Some("/"),
1902            file_name: Some("foo"),
1903            file_stem: Some("foo"),
1904            extension: None
1905            );
1906
1907         t!("foo/bar",
1908            iter: ["foo", "bar"],
1909            has_root: false,
1910            is_absolute: false,
1911            parent: Some("foo"),
1912            file_name: Some("bar"),
1913            file_stem: Some("bar"),
1914            extension: None
1915            );
1916
1917         t!("/foo/bar",
1918            iter: ["\\", "foo", "bar"],
1919            has_root: true,
1920            is_absolute: false,
1921            parent: Some("/foo"),
1922            file_name: Some("bar"),
1923            file_stem: Some("bar"),
1924            extension: None
1925            );
1926
1927         t!("///foo///",
1928            iter: ["\\", "foo"],
1929            has_root: true,
1930            is_absolute: false,
1931            parent: Some("/"),
1932            file_name: Some("foo"),
1933            file_stem: Some("foo"),
1934            extension: None
1935            );
1936
1937         t!("///foo///bar",
1938            iter: ["\\", "foo", "bar"],
1939            has_root: true,
1940            is_absolute: false,
1941            parent: Some("///foo"),
1942            file_name: Some("bar"),
1943            file_stem: Some("bar"),
1944            extension: None
1945            );
1946
1947         t!("./.",
1948            iter: ["."],
1949            has_root: false,
1950            is_absolute: false,
1951            parent: Some(""),
1952            file_name: None,
1953            file_stem: None,
1954            extension: None
1955            );
1956
1957         t!("/..",
1958            iter: ["\\", ".."],
1959            has_root: true,
1960            is_absolute: false,
1961            parent: Some("/"),
1962            file_name: None,
1963            file_stem: None,
1964            extension: None
1965            );
1966
1967         t!("../",
1968            iter: [".."],
1969            has_root: false,
1970            is_absolute: false,
1971            parent: Some(""),
1972            file_name: None,
1973            file_stem: None,
1974            extension: None
1975            );
1976
1977         t!("foo/.",
1978            iter: ["foo"],
1979            has_root: false,
1980            is_absolute: false,
1981            parent: Some(""),
1982            file_name: Some("foo"),
1983            file_stem: Some("foo"),
1984            extension: None
1985            );
1986
1987         t!("foo/..",
1988            iter: ["foo", ".."],
1989            has_root: false,
1990            is_absolute: false,
1991            parent: Some("foo"),
1992            file_name: None,
1993            file_stem: None,
1994            extension: None
1995            );
1996
1997         t!("foo/./",
1998            iter: ["foo"],
1999            has_root: false,
2000            is_absolute: false,
2001            parent: Some(""),
2002            file_name: Some("foo"),
2003            file_stem: Some("foo"),
2004            extension: None
2005            );
2006
2007         t!("foo/./bar",
2008            iter: ["foo", "bar"],
2009            has_root: false,
2010            is_absolute: false,
2011            parent: Some("foo"),
2012            file_name: Some("bar"),
2013            file_stem: Some("bar"),
2014            extension: None
2015            );
2016
2017         t!("foo/../",
2018            iter: ["foo", ".."],
2019            has_root: false,
2020            is_absolute: false,
2021            parent: Some("foo"),
2022            file_name: None,
2023            file_stem: None,
2024            extension: None
2025            );
2026
2027         t!("foo/../bar",
2028            iter: ["foo", "..", "bar"],
2029            has_root: false,
2030            is_absolute: false,
2031            parent: Some("foo/.."),
2032            file_name: Some("bar"),
2033            file_stem: Some("bar"),
2034            extension: None
2035            );
2036
2037         t!("./a",
2038            iter: [".", "a"],
2039            has_root: false,
2040            is_absolute: false,
2041            parent: Some("."),
2042            file_name: Some("a"),
2043            file_stem: Some("a"),
2044            extension: None
2045            );
2046
2047         t!(".",
2048            iter: ["."],
2049            has_root: false,
2050            is_absolute: false,
2051            parent: Some(""),
2052            file_name: None,
2053            file_stem: None,
2054            extension: None
2055            );
2056
2057         t!("./",
2058            iter: ["."],
2059            has_root: false,
2060            is_absolute: false,
2061            parent: Some(""),
2062            file_name: None,
2063            file_stem: None,
2064            extension: None
2065            );
2066
2067         t!("a/b",
2068            iter: ["a", "b"],
2069            has_root: false,
2070            is_absolute: false,
2071            parent: Some("a"),
2072            file_name: Some("b"),
2073            file_stem: Some("b"),
2074            extension: None
2075            );
2076
2077         t!("a//b",
2078            iter: ["a", "b"],
2079            has_root: false,
2080            is_absolute: false,
2081            parent: Some("a"),
2082            file_name: Some("b"),
2083            file_stem: Some("b"),
2084            extension: None
2085            );
2086
2087         t!("a/./b",
2088            iter: ["a", "b"],
2089            has_root: false,
2090            is_absolute: false,
2091            parent: Some("a"),
2092            file_name: Some("b"),
2093            file_stem: Some("b"),
2094            extension: None
2095            );
2096
2097         t!("a/b/c",
2098            iter: ["a", "b", "c"],
2099            has_root: false,
2100            is_absolute: false,
2101            parent: Some("a/b"),
2102            file_name: Some("c"),
2103            file_stem: Some("c"),
2104            extension: None);
2105
2106         t!("a\\b\\c",
2107            iter: ["a", "b", "c"],
2108            has_root: false,
2109            is_absolute: false,
2110            parent: Some("a\\b"),
2111            file_name: Some("c"),
2112            file_stem: Some("c"),
2113            extension: None
2114            );
2115
2116         t!("\\a",
2117            iter: ["\\", "a"],
2118            has_root: true,
2119            is_absolute: false,
2120            parent: Some("\\"),
2121            file_name: Some("a"),
2122            file_stem: Some("a"),
2123            extension: None
2124            );
2125
2126         t!("c:\\foo.txt",
2127            iter: ["c:", "\\", "foo.txt"],
2128            has_root: true,
2129            is_absolute: true,
2130            parent: Some("c:\\"),
2131            file_name: Some("foo.txt"),
2132            file_stem: Some("foo"),
2133            extension: Some("txt")
2134            );
2135
2136         t!("\\\\server\\share\\foo.txt",
2137            iter: ["\\\\server\\share", "\\", "foo.txt"],
2138            has_root: true,
2139            is_absolute: true,
2140            parent: Some("\\\\server\\share\\"),
2141            file_name: Some("foo.txt"),
2142            file_stem: Some("foo"),
2143            extension: Some("txt")
2144            );
2145
2146         t!("\\\\server\\share",
2147            iter: ["\\\\server\\share", "\\"],
2148            has_root: true,
2149            is_absolute: true,
2150            parent: None,
2151            file_name: None,
2152            file_stem: None,
2153            extension: None
2154            );
2155
2156         t!("\\\\server",
2157            iter: ["\\", "server"],
2158            has_root: true,
2159            is_absolute: false,
2160            parent: Some("\\"),
2161            file_name: Some("server"),
2162            file_stem: Some("server"),
2163            extension: None
2164            );
2165
2166         t!("\\\\?\\bar\\foo.txt",
2167            iter: ["\\\\?\\bar", "\\", "foo.txt"],
2168            has_root: true,
2169            is_absolute: true,
2170            parent: Some("\\\\?\\bar\\"),
2171            file_name: Some("foo.txt"),
2172            file_stem: Some("foo"),
2173            extension: Some("txt")
2174            );
2175
2176         t!("\\\\?\\bar",
2177            iter: ["\\\\?\\bar"],
2178            has_root: true,
2179            is_absolute: true,
2180            parent: None,
2181            file_name: None,
2182            file_stem: None,
2183            extension: None
2184            );
2185
2186         t!("\\\\?\\",
2187            iter: ["\\\\?\\"],
2188            has_root: true,
2189            is_absolute: true,
2190            parent: None,
2191            file_name: None,
2192            file_stem: None,
2193            extension: None
2194            );
2195
2196         t!("\\\\?\\UNC\\server\\share\\foo.txt",
2197            iter: ["\\\\?\\UNC\\server\\share", "\\", "foo.txt"],
2198            has_root: true,
2199            is_absolute: true,
2200            parent: Some("\\\\?\\UNC\\server\\share\\"),
2201            file_name: Some("foo.txt"),
2202            file_stem: Some("foo"),
2203            extension: Some("txt")
2204            );
2205
2206         t!("\\\\?\\UNC\\server",
2207            iter: ["\\\\?\\UNC\\server"],
2208            has_root: true,
2209            is_absolute: true,
2210            parent: None,
2211            file_name: None,
2212            file_stem: None,
2213            extension: None
2214            );
2215
2216         t!("\\\\?\\UNC\\",
2217            iter: ["\\\\?\\UNC\\"],
2218            has_root: true,
2219            is_absolute: true,
2220            parent: None,
2221            file_name: None,
2222            file_stem: None,
2223            extension: None
2224            );
2225
2226         t!("\\\\?\\C:\\foo.txt",
2227            iter: ["\\\\?\\C:", "\\", "foo.txt"],
2228            has_root: true,
2229            is_absolute: true,
2230            parent: Some("\\\\?\\C:\\"),
2231            file_name: Some("foo.txt"),
2232            file_stem: Some("foo"),
2233            extension: Some("txt")
2234            );
2235
2236
2237         t!("\\\\?\\C:\\",
2238            iter: ["\\\\?\\C:", "\\"],
2239            has_root: true,
2240            is_absolute: true,
2241            parent: None,
2242            file_name: None,
2243            file_stem: None,
2244            extension: None
2245            );
2246
2247
2248         t!("\\\\?\\C:",
2249            iter: ["\\\\?\\C:"],
2250            has_root: true,
2251            is_absolute: true,
2252            parent: None,
2253            file_name: None,
2254            file_stem: None,
2255            extension: None
2256            );
2257
2258
2259         t!("\\\\?\\foo/bar",
2260            iter: ["\\\\?\\foo/bar"],
2261            has_root: true,
2262            is_absolute: true,
2263            parent: None,
2264            file_name: None,
2265            file_stem: None,
2266            extension: None
2267            );
2268
2269
2270         t!("\\\\?\\C:/foo",
2271            iter: ["\\\\?\\C:/foo"],
2272            has_root: true,
2273            is_absolute: true,
2274            parent: None,
2275            file_name: None,
2276            file_stem: None,
2277            extension: None
2278            );
2279
2280
2281         t!("\\\\.\\foo\\bar",
2282            iter: ["\\\\.\\foo", "\\", "bar"],
2283            has_root: true,
2284            is_absolute: true,
2285            parent: Some("\\\\.\\foo\\"),
2286            file_name: Some("bar"),
2287            file_stem: Some("bar"),
2288            extension: None
2289            );
2290
2291
2292         t!("\\\\.\\foo",
2293            iter: ["\\\\.\\foo", "\\"],
2294            has_root: true,
2295            is_absolute: true,
2296            parent: None,
2297            file_name: None,
2298            file_stem: None,
2299            extension: None
2300            );
2301
2302
2303         t!("\\\\.\\foo/bar",
2304            iter: ["\\\\.\\foo/bar", "\\"],
2305            has_root: true,
2306            is_absolute: true,
2307            parent: None,
2308            file_name: None,
2309            file_stem: None,
2310            extension: None
2311            );
2312
2313
2314         t!("\\\\.\\foo\\bar/baz",
2315            iter: ["\\\\.\\foo", "\\", "bar", "baz"],
2316            has_root: true,
2317            is_absolute: true,
2318            parent: Some("\\\\.\\foo\\bar"),
2319            file_name: Some("baz"),
2320            file_stem: Some("baz"),
2321            extension: None
2322            );
2323
2324
2325         t!("\\\\.\\",
2326            iter: ["\\\\.\\", "\\"],
2327            has_root: true,
2328            is_absolute: true,
2329            parent: None,
2330            file_name: None,
2331            file_stem: None,
2332            extension: None
2333            );
2334
2335         t!("\\\\?\\a\\b\\",
2336            iter: ["\\\\?\\a", "\\", "b"],
2337            has_root: true,
2338            is_absolute: true,
2339            parent: Some("\\\\?\\a\\"),
2340            file_name: Some("b"),
2341            file_stem: Some("b"),
2342            extension: None
2343            );
2344     }
2345
2346     #[test]
2347     pub fn test_stem_ext() {
2348         t!("foo",
2349            file_stem: Some("foo"),
2350            extension: None
2351            );
2352
2353         t!("foo.",
2354            file_stem: Some("foo"),
2355            extension: Some("")
2356            );
2357
2358         t!(".foo",
2359            file_stem: Some(".foo"),
2360            extension: None
2361            );
2362
2363         t!("foo.txt",
2364            file_stem: Some("foo"),
2365            extension: Some("txt")
2366            );
2367
2368         t!("foo.bar.txt",
2369            file_stem: Some("foo.bar"),
2370            extension: Some("txt")
2371            );
2372
2373         t!("foo.bar.",
2374            file_stem: Some("foo.bar"),
2375            extension: Some("")
2376            );
2377
2378         t!(".",
2379            file_stem: None,
2380            extension: None
2381            );
2382
2383         t!("..",
2384            file_stem: None,
2385            extension: None
2386            );
2387
2388         t!("",
2389            file_stem: None,
2390            extension: None
2391            );
2392     }
2393
2394     #[test]
2395     pub fn test_push() {
2396         macro_rules! tp(
2397             ($path:expr, $push:expr, $expected:expr) => ( {
2398                 let mut actual = PathBuf::new($path);
2399                 actual.push($push);
2400                 assert!(actual.to_str() == Some($expected),
2401                         "pushing {:?} onto {:?}: Expected {:?}, got {:?}",
2402                         $push, $path, $expected, actual.to_str().unwrap());
2403             });
2404         );
2405
2406         if cfg!(unix) {
2407             tp!("", "foo", "foo");
2408             tp!("foo", "bar", "foo/bar");
2409             tp!("foo/", "bar", "foo/bar");
2410             tp!("foo//", "bar", "foo//bar");
2411             tp!("foo/.", "bar", "foo/./bar");
2412             tp!("foo./.", "bar", "foo././bar");
2413             tp!("foo", "", "foo/");
2414             tp!("foo", ".", "foo/.");
2415             tp!("foo", "..", "foo/..");
2416             tp!("foo", "/", "/");
2417             tp!("/foo/bar", "/", "/");
2418             tp!("/foo/bar", "/baz", "/baz");
2419             tp!("/foo/bar", "./baz", "/foo/bar/./baz");
2420         } else {
2421             tp!("", "foo", "foo");
2422             tp!("foo", "bar", r"foo\bar");
2423             tp!("foo/", "bar", r"foo/bar");
2424             tp!(r"foo\", "bar", r"foo\bar");
2425             tp!("foo//", "bar", r"foo//bar");
2426             tp!(r"foo\\", "bar", r"foo\\bar");
2427             tp!("foo/.", "bar", r"foo/.\bar");
2428             tp!("foo./.", "bar", r"foo./.\bar");
2429             tp!(r"foo\.", "bar", r"foo\.\bar");
2430             tp!(r"foo.\.", "bar", r"foo.\.\bar");
2431             tp!("foo", "", "foo\\");
2432             tp!("foo", ".", r"foo\.");
2433             tp!("foo", "..", r"foo\..");
2434             tp!("foo", "/", "/");
2435             tp!("foo", r"\", r"\");
2436             tp!("/foo/bar", "/", "/");
2437             tp!(r"\foo\bar", r"\", r"\");
2438             tp!("/foo/bar", "/baz", "/baz");
2439             tp!("/foo/bar", r"\baz", r"\baz");
2440             tp!("/foo/bar", "./baz", r"/foo/bar\./baz");
2441             tp!("/foo/bar", r".\baz", r"/foo/bar\.\baz");
2442
2443             tp!("c:\\", "windows", "c:\\windows");
2444             tp!("c:", "windows", "c:windows");
2445
2446             tp!("a\\b\\c", "d", "a\\b\\c\\d");
2447             tp!("\\a\\b\\c", "d", "\\a\\b\\c\\d");
2448             tp!("a\\b", "c\\d", "a\\b\\c\\d");
2449             tp!("a\\b", "\\c\\d", "\\c\\d");
2450             tp!("a\\b", ".", "a\\b\\.");
2451             tp!("a\\b", "..\\c", "a\\b\\..\\c");
2452             tp!("a\\b", "C:a.txt", "C:a.txt");
2453             tp!("a\\b", "C:\\a.txt", "C:\\a.txt");
2454             tp!("C:\\a", "C:\\b.txt", "C:\\b.txt");
2455             tp!("C:\\a\\b\\c", "C:d", "C:d");
2456             tp!("C:a\\b\\c", "C:d", "C:d");
2457             tp!("C:", r"a\b\c", r"C:a\b\c");
2458             tp!("C:", r"..\a", r"C:..\a");
2459             tp!("\\\\server\\share\\foo", "bar", "\\\\server\\share\\foo\\bar");
2460             tp!("\\\\server\\share\\foo", "C:baz", "C:baz");
2461             tp!("\\\\?\\C:\\a\\b", "C:c\\d", "C:c\\d");
2462             tp!("\\\\?\\C:a\\b", "C:c\\d", "C:c\\d");
2463             tp!("\\\\?\\C:\\a\\b", "C:\\c\\d", "C:\\c\\d");
2464             tp!("\\\\?\\foo\\bar", "baz", "\\\\?\\foo\\bar\\baz");
2465             tp!("\\\\?\\UNC\\server\\share\\foo", "bar", "\\\\?\\UNC\\server\\share\\foo\\bar");
2466             tp!("\\\\?\\UNC\\server\\share", "C:\\a", "C:\\a");
2467             tp!("\\\\?\\UNC\\server\\share", "C:a", "C:a");
2468
2469             // Note: modified from old path API
2470             tp!("\\\\?\\UNC\\server", "foo", "\\\\?\\UNC\\server\\foo");
2471
2472             tp!("C:\\a", "\\\\?\\UNC\\server\\share", "\\\\?\\UNC\\server\\share");
2473             tp!("\\\\.\\foo\\bar", "baz", "\\\\.\\foo\\bar\\baz");
2474             tp!("\\\\.\\foo\\bar", "C:a", "C:a");
2475             // again, not sure about the following, but I'm assuming \\.\ should be verbatim
2476             tp!("\\\\.\\foo", "..\\bar", "\\\\.\\foo\\..\\bar");
2477
2478             tp!("\\\\?\\C:", "foo", "\\\\?\\C:\\foo"); // this is a weird one
2479         }
2480     }
2481
2482     #[test]
2483     pub fn test_pop() {
2484         macro_rules! tp(
2485             ($path:expr, $expected:expr, $output:expr) => ( {
2486                 let mut actual = PathBuf::new($path);
2487                 let output = actual.pop();
2488                 assert!(actual.to_str() == Some($expected) && output == $output,
2489                         "popping from {:?}: Expected {:?}/{:?}, got {:?}/{:?}",
2490                         $path, $expected, $output,
2491                         actual.to_str().unwrap(), output);
2492             });
2493         );
2494
2495         tp!("", "", false);
2496         tp!("/", "/", false);
2497         tp!("foo", "", true);
2498         tp!(".", "", true);
2499         tp!("/foo", "/", true);
2500         tp!("/foo/bar", "/foo", true);
2501         tp!("foo/bar", "foo", true);
2502         tp!("foo/.", "", true);
2503         tp!("foo//bar", "foo", true);
2504
2505         if cfg!(windows) {
2506             tp!("a\\b\\c", "a\\b", true);
2507             tp!("\\a", "\\", true);
2508             tp!("\\", "\\", false);
2509
2510             tp!("C:\\a\\b", "C:\\a", true);
2511             tp!("C:\\a", "C:\\", true);
2512             tp!("C:\\", "C:\\", false);
2513             tp!("C:a\\b", "C:a", true);
2514             tp!("C:a", "C:", true);
2515             tp!("C:", "C:", false);
2516             tp!("\\\\server\\share\\a\\b", "\\\\server\\share\\a", true);
2517             tp!("\\\\server\\share\\a", "\\\\server\\share\\", true);
2518             tp!("\\\\server\\share", "\\\\server\\share", false);
2519             tp!("\\\\?\\a\\b\\c", "\\\\?\\a\\b", true);
2520             tp!("\\\\?\\a\\b", "\\\\?\\a\\", true);
2521             tp!("\\\\?\\a", "\\\\?\\a", false);
2522             tp!("\\\\?\\C:\\a\\b", "\\\\?\\C:\\a", true);
2523             tp!("\\\\?\\C:\\a", "\\\\?\\C:\\", true);
2524             tp!("\\\\?\\C:\\", "\\\\?\\C:\\", false);
2525             tp!("\\\\?\\UNC\\server\\share\\a\\b", "\\\\?\\UNC\\server\\share\\a", true);
2526             tp!("\\\\?\\UNC\\server\\share\\a", "\\\\?\\UNC\\server\\share\\", true);
2527             tp!("\\\\?\\UNC\\server\\share", "\\\\?\\UNC\\server\\share", false);
2528             tp!("\\\\.\\a\\b\\c", "\\\\.\\a\\b", true);
2529             tp!("\\\\.\\a\\b", "\\\\.\\a\\", true);
2530             tp!("\\\\.\\a", "\\\\.\\a", false);
2531
2532             tp!("\\\\?\\a\\b\\", "\\\\?\\a\\", true);
2533         }
2534     }
2535
2536     #[test]
2537     pub fn test_set_file_name() {
2538         macro_rules! tfn(
2539                 ($path:expr, $file:expr, $expected:expr) => ( {
2540                 let mut p = PathBuf::new($path);
2541                 p.set_file_name($file);
2542                 assert!(p.to_str() == Some($expected),
2543                         "setting file name of {:?} to {:?}: Expected {:?}, got {:?}",
2544                         $path, $file, $expected,
2545                         p.to_str().unwrap());
2546             });
2547         );
2548
2549         tfn!("foo", "foo", "foo");
2550         tfn!("foo", "bar", "bar");
2551         tfn!("foo", "", "");
2552         tfn!("", "foo", "foo");
2553         if cfg!(unix) {
2554             tfn!(".", "foo", "./foo");
2555             tfn!("foo/", "bar", "bar");
2556             tfn!("foo/.", "bar", "bar");
2557             tfn!("..", "foo", "../foo");
2558             tfn!("foo/..", "bar", "foo/../bar");
2559             tfn!("/", "foo", "/foo");
2560         } else {
2561             tfn!(".", "foo", r".\foo");
2562             tfn!(r"foo\", "bar", r"bar");
2563             tfn!(r"foo\.", "bar", r"bar");
2564             tfn!("..", "foo", r"..\foo");
2565             tfn!(r"foo\..", "bar", r"foo\..\bar");
2566             tfn!(r"\", "foo", r"\foo");
2567         }
2568     }
2569
2570     #[test]
2571     pub fn test_set_extension() {
2572         macro_rules! tfe(
2573                 ($path:expr, $ext:expr, $expected:expr, $output:expr) => ( {
2574                 let mut p = PathBuf::new($path);
2575                 let output = p.set_extension($ext);
2576                 assert!(p.to_str() == Some($expected) && output == $output,
2577                         "setting extension of {:?} to {:?}: Expected {:?}/{:?}, got {:?}/{:?}",
2578                         $path, $ext, $expected, $output,
2579                         p.to_str().unwrap(), output);
2580             });
2581         );
2582
2583         tfe!("foo", "txt", "foo.txt", true);
2584         tfe!("foo.bar", "txt", "foo.txt", true);
2585         tfe!("foo.bar.baz", "txt", "foo.bar.txt", true);
2586         tfe!(".test", "txt", ".test.txt", true);
2587         tfe!("foo.txt", "", "foo", true);
2588         tfe!("foo", "", "foo", true);
2589         tfe!("", "foo", "", false);
2590         tfe!(".", "foo", ".", false);
2591         tfe!("foo/", "bar", "foo.bar", true);
2592         tfe!("foo/.", "bar", "foo.bar", true);
2593         tfe!("..", "foo", "..",  false);
2594         tfe!("foo/..", "bar", "foo/..", false);
2595         tfe!("/", "foo", "/", false);
2596     }
2597
2598     #[test]
2599     pub fn test_compare() {
2600         macro_rules! tc(
2601             ($path1:expr, $path2:expr, eq: $eq:expr,
2602              starts_with: $starts_with:expr, ends_with: $ends_with:expr,
2603              relative_from: $relative_from:expr) => ({
2604                  let path1 = Path::new($path1);
2605                  let path2 = Path::new($path2);
2606
2607                  let eq = path1 == path2;
2608                  assert!(eq == $eq, "{:?} == {:?}, expected {:?}, got {:?}",
2609                          $path1, $path2, $eq, eq);
2610
2611                  let starts_with = path1.starts_with(path2);
2612                  assert!(starts_with == $starts_with,
2613                          "{:?}.starts_with({:?}), expected {:?}, got {:?}", $path1, $path2,
2614                          $starts_with, starts_with);
2615
2616                  let ends_with = path1.ends_with(path2);
2617                  assert!(ends_with == $ends_with,
2618                          "{:?}.ends_with({:?}), expected {:?}, got {:?}", $path1, $path2,
2619                          $ends_with, ends_with);
2620
2621                  let relative_from = path1.relative_from(path2).map(|p| p.to_str().unwrap());
2622                  let exp: Option<&str> = $relative_from;
2623                  assert!(relative_from == exp,
2624                          "{:?}.relative_from({:?}), expected {:?}, got {:?}", $path1, $path2,
2625                          exp, relative_from);
2626             });
2627         );
2628
2629         tc!("", "",
2630             eq: true,
2631             starts_with: true,
2632             ends_with: true,
2633             relative_from: Some("")
2634             );
2635
2636         tc!("foo", "",
2637             eq: false,
2638             starts_with: true,
2639             ends_with: true,
2640             relative_from: Some("foo")
2641             );
2642
2643         tc!("", "foo",
2644             eq: false,
2645             starts_with: false,
2646             ends_with: false,
2647             relative_from: None
2648             );
2649
2650         tc!("foo", "foo",
2651             eq: true,
2652             starts_with: true,
2653             ends_with: true,
2654             relative_from: Some("")
2655             );
2656
2657         tc!("foo/", "foo",
2658             eq: true,
2659             starts_with: true,
2660             ends_with: true,
2661             relative_from: Some("")
2662             );
2663
2664         tc!("foo/bar", "foo",
2665             eq: false,
2666             starts_with: true,
2667             ends_with: false,
2668             relative_from: Some("bar")
2669             );
2670
2671         tc!("foo/bar/baz", "foo/bar",
2672             eq: false,
2673             starts_with: true,
2674             ends_with: false,
2675             relative_from: Some("baz")
2676             );
2677
2678         tc!("foo/bar", "foo/bar/baz",
2679             eq: false,
2680             starts_with: false,
2681             ends_with: false,
2682             relative_from: None
2683             );
2684
2685         tc!("./foo/bar/", ".",
2686             eq: false,
2687             starts_with: true,
2688             ends_with: false,
2689             relative_from: Some("foo/bar")
2690             );
2691
2692         if cfg!(windows) {
2693             tc!(r"C:\src\rust\cargo-test\test\Cargo.toml",
2694                 r"c:\src\rust\cargo-test\test",
2695                 eq: false,
2696                 starts_with: true,
2697                 ends_with: false,
2698                 relative_from: Some("Cargo.toml")
2699                 );
2700
2701             tc!(r"c:\foo", r"C:\foo",
2702                 eq: true,
2703                 starts_with: true,
2704                 ends_with: true,
2705                 relative_from: Some("")
2706                 );
2707         }
2708     }
2709 }