928: class Path(PurePath):

210:     def _split_extended_path(self, s, ext_prefix=ext_namespace_prefix):

134:     pathmod = ntpath

253:     pathmod = posixpath

565: class PurePath(object):

844:     def joinpath(self, *args):

915: class PurePosixPath(PurePath):

920: class PureWindowsPath(PurePath):

952:     def _make_child_relpath(self, part):

1275: class PosixPath(Path, PurePosixPath):

1278: class WindowsPath(Path, PureWindowsPath):

537: class _PathParents(Sequence):

40:         _getfinalpathname = None

45:     "Path", "PosixPath", "WindowsPath",

67:     """A flavour implements a particular (platform-specific) set of path

119:                 # Same drive => second path is relative to the first

122:             # Second path is non-anchored (common case)

162:             prefix, part = self._split_extended_path(part)

169:             # is a UNC path:

176:                 # a UNC path can't have two slashes in a row

201:     def resolve(self, path):

202:         s = str(path)

221:         # Turn back an extended path into a normal DOS-like path

222:         return self._split_extended_path(s)[1]

236:     def make_uri(self, path):

238:         drive = path.drive

240:             # It's a path on a local drive => 'file:///c:/a/b'

241:             rest = path.as_posix()[2:].lstrip('/')

245:             # It's a path on a network drive => 'file://host/share/a/b'

246:             return 'file:' + urlquote_from_bytes(path.as_posix().encode('utf-8'))

260:             # According to POSIX path resolution:

278:     def resolve(self, path):

280:         accessor = path._accessor

282:         def _resolve(path, rest):

284:                 path = ''

292:                     path, _, _ = path.rpartition(sep)

294:                 newpath = path + sep + name

296:                     # Already seen this path

297:                     path = seen[newpath]

298:                     if path is not None:

310:                     path = newpath

313:                     path = _resolve(path, target)

314:                     seen[newpath] = path # resolved symlink

316:             return path

317:         # NOTE: according to POSIX, getcwd() cannot contain path components

319:         base = '' if path.is_absolute() else os.getcwd()

320:         return _resolve(base, str(path)) or sep

325:     def make_uri(self, path):

326:         # We represent the path using the local filesystem encoding,

328:         bpath = bytes(path)

397:     def readlink(self, path):

398:         return os.readlink(path)

433:         raise ValueError("Invalid pattern: '**' can only be an entire path component")

446:     of a given path."""

455:     def select_from(self, parent_path):

456:         """Iterate over all child paths of `parent_path` matched by this

457:         selector.  This can contain parent_path itself."""

458:         path_cls = type(parent_path)

459:         is_dir = path_cls.is_dir

460:         exists = path_cls.exists

461:         listdir = parent_path._accessor.listdir

462:         return self._select_from(parent_path, is_dir, exists, listdir)

467:     def _select_from(self, parent_path, is_dir, exists, listdir):

468:         yield parent_path

477:     def _select_from(self, parent_path, is_dir, exists, listdir):

478:         if not is_dir(parent_path):

480:         path = parent_path._make_child_relpath(self.name)

481:         if exists(path):

482:             for p in self.successor._select_from(path, is_dir, exists, listdir):

492:     def _select_from(self, parent_path, is_dir, exists, listdir):

493:         if not is_dir(parent_path):

495:         cf = parent_path._flavour.casefold

496:         for name in listdir(parent_path):

499:                 path = parent_path._make_child_relpath(name)

500:                 for p in self.successor._select_from(path, is_dir, exists, listdir):

509:     def _iterate_directories(self, parent_path, is_dir, listdir):

510:         yield parent_path

511:         for name in listdir(parent_path):

512:             path = parent_path._make_child_relpath(name)

513:             if is_dir(path):

514:                 for p in self._iterate_directories(path, is_dir, listdir):

517:     def _select_from(self, parent_path, is_dir, exists, listdir):

518:         if not is_dir(parent_path):

524:                 for starting_point in self._iterate_directories(parent_path, is_dir, listdir):

539:     of a path.  Don't try to construct it yourself."""

542:     def __init__(self, path):

544:         self._pathcls = type(path)

545:         self._drv = path._drv

546:         self._root = path._root

547:         self._parts = path._parts

566:     """PurePath represents a filesystem path and offers operations which

579:         PurePath objects.  The strings and path objects are combined so as

580:         to yield a canonicalized path, which is incorporated into the

588:         # Using the parts tuple helps share interned path parts

604:                     "argument should be a path or str object, not %r"

639:         # Overriden in concrete Path

649:         """Return the string representation of the path, suitable for

659:         """Return the string representation of the path with forward (/)

665:         """Return the bytes representation of the path.  This is only

675:         """Return the path as a 'file' URI."""

677:             raise ValueError("relative path can't be expressed as a file URI")

725:                      doc="""The drive prefix (letter or UNC path), if any.""")

728:                     doc="""The root of the path, if any.""")

738:         """The final path component, if any."""

765:         """The final path component, minus its last suffix."""

774:         """Return a new path with the file name changed."""

781:         """Return a new path with the file suffix changed (or added, if none)."""

801:         """Return the relative path to another path identified by the passed

803:         a subpath of the other path), raise ValueError.

807:         #   Path('c:/').relative_to('c:')  gives Path('/')

808:         #   Path('c:/').relative_to('/')   raise ValueError

835:         components in the filesystem path."""

845:         """Combine this path with one or several arguments, and return a

846:         new path representing either a subpath (if all arguments are relative

847:         paths) or a totally different path (if one of the arguments is

864:         """The logical parent of the path."""

874:         """A sequence of this path's logical parents."""

878:         """True if the path is absolute (has both a root and, if applicable,

885:         """Return True if the path contains one of the special names reserved

889:     def match(self, path_pattern):

891:         Return True if this path matches the given pattern.

894:         path_pattern = cf(path_pattern)

895:         drv, root, pat_parts = self._flavour.parse_parts((path_pattern,))

934:         if cls is Path:

954:         # a single part relative to this path.

964:         Open the file pointed by this path and return a file descriptor,

973:         """Return a new path pointing to the current working directory

984:                 # Yielding a path object for these makes little sense

1013:         """Return an absolute version of this path.  This function works

1014:         even if the path doesn't point to anything.

1017:         Use resolve() to get the canonical path to a file.

1030:         Make the path absolute, resolving all symlinks on the way and also

1037:             # the path doesn't exist or is forbidden

1040:         # Now we have no symlinks in the path, it's safe to normalize it.

1048:         Return the result of the stat() system call on this path, like

1070:         Open the file pointed by this path and return a file object, as

1115:         Change the permissions of the path, like os.chmod().

1121:         Like chmod(), except if the path points to a symlink, the symlink's

1129:         If the path is a directory, use rmdir() instead.

1141:         Like stat(), except if the path points to a symlink, the symlink's

1148:         Rename this path to the given path.

1154:         Rename this path to the given path, clobbering the existing

1164:         Make this path a symlink pointing to the given path.

1173:         Whether this path exists.

1185:         Whether this path is a directory.

1192:             # Path doesn't exist or is a broken symlink

1198:         Whether this path is a regular file (also True for symlinks pointing

1206:             # Path doesn't exist or is a broken symlink

1212:         Whether this path is a symbolic link.

1219:             # Path doesn't exist

1224:         Whether this path is a block device.

1231:             # Path doesn't exist or is a broken symlink

1237:         Whether this path is a character device.

1244:             # Path doesn't exist or is a broken symlink

1250:         Whether this path is a FIFO.

1257:             # Path doesn't exist or is a broken symlink

1263:         Whether this path is a socket.

1270:             # Path doesn't exist or is a broken symlink

4: import ntpath

6: import posixpath

44:     "PurePath", "PurePosixPath", "PureWindowsPath",

111:         Join the two paths represented by the respective

128:     # Reference for Windows paths can be found at

150:     # Interesting findings about extended paths:

153:     # - extended paths are always absolute; "relative" extended paths will

160:             # XXX extended paths should also disable the collapsing of "."

227:         # We err on the side of caution and return True for paths which are

232:             # UNC paths are never reserved

262:             # "A pathname that begins with two successive slashes may be

295:                 if newpath in seen:

302:                     raise RuntimeError("Symlink loop from %r" % newpath)

305:                     target = accessor.readlink(newpath)

312:                     seen[newpath] = None # not resolved symlink

329:         return 'file://' + urlquote_from_bytes(bpath)

338:     accessing paths on the filesystem."""

345:         def wrapped(pathobj, *args):

346:             return strfunc(str(pathobj), *args)

351:         def wrapped(pathobjA, pathobjB, *args):

352:             return strfunc(str(pathobjA), str(pathobjB), *args)

368:         def lchmod(self, pathobj, mode):

540:     __slots__ = ('_pathcls', '_drv', '_root', '_parts')

558:         return self._pathcls._from_parsed_parts(self._drv, self._root,

562:         return "<{0}.parents>".format(self._pathcls.__name__)

568:     instantiating a PurePath will return either a PurePosixPath or a

569:     PureWindowsPath object.  You can also instantiate either of these classes

578:         """Construct a PurePath from one or several strings and or existing

581:         new PurePath object.

583:         if cls is PurePath:

584:             cls = PureWindowsPath if os.name == 'nt' else PurePosixPath

589:         # when pickling related paths.

598:             if isinstance(a, PurePath):

690:         if not isinstance(other, PurePath):

705:         if not isinstance(other, PurePath) or self._flavour is not other._flavour:

710:         if not isinstance(other, PurePath) or self._flavour is not other._flavour:

715:         if not isinstance(other, PurePath) or self._flavour is not other._flavour:

720:         if not isinstance(other, PurePath) or self._flavour is not other._flavour:

875:         return _PathParents(self)

935:             cls = WindowsPath if os.name == 'nt' else PosixPath

980:         result for the special paths '.' and '..'.

986:             yield self._make_child_relpath(name)

1041:         normed = self._flavour.pathmod.normpath(s)

1193:             # (see https://bitbucket.org/pitrou/pathlib/issue/12/)

1207:             # (see https://bitbucket.org/pitrou/pathlib/issue/12/)

1232:             # (see https://bitbucket.org/pitrou/pathlib/issue/12/)

1245:             # (see https://bitbucket.org/pitrou/pathlib/issue/12/)

1258:             # (see https://bitbucket.org/pitrou/pathlib/issue/12/)

1271:             # (see https://bitbucket.org/pitrou/pathlib/issue/12/)

37:         from nt import _getfinalpathname

205:         if _getfinalpathname is not None:

206:             return self._ext_to_normal(_getfinalpathname(s))

1023:         # use nt._getfullpathname())

582:     path: &'a [u8],

1748: impl ToOwned for Path {

1835: pub struct Path {

1848: impl Path {

2746: impl AsRef<OsStr> for Path {

2753: impl fmt::Debug for Path {

2780:     path: &'a Path,

2795: impl cmp::PartialEq for Path {

2802: impl Hash for Path {

2853: impl cmp::Eq for Path {}

2855: impl cmp::PartialOrd for Path {

2862: impl cmp::Ord for Path {

2869: impl AsRef<Path> for Path {

2927: impl<'a> IntoIterator for &'a Path {

675:     pub fn as_path(&self) -> &'a Path {

817:     pub fn as_path(&self) -> &'a Path {

1186:     pub fn as_path(&self) -> &Path {

1435:     pub fn into_boxed_path(self) -> Box<Path> {

1124: pub struct PathBuf {

1128: impl PathBuf {

1507: impl Clone for PathBuf {

1543: impl From<Box<Path>> for PathBuf {

1571: impl<T: ?Sized + AsRef<OsStr>> From<&T> for PathBuf {

1581: impl From<OsString> for PathBuf {

1601: impl From<String> for PathBuf {

1611: impl FromStr for PathBuf {

1620: impl<P: AsRef<Path>> iter::FromIterator<P> for PathBuf {

1628: impl<P: AsRef<Path>> iter::Extend<P> for PathBuf {

1639: impl fmt::Debug for PathBuf {

1645: impl ops::Deref for PathBuf {

1653: impl Borrow<Path> for PathBuf {

1660: impl Default for PathBuf {

1700: impl<'a> From<Cow<'a, Path>> for PathBuf {

1760: impl cmp::PartialEq for PathBuf {

1767: impl Hash for PathBuf {

1773: impl cmp::Eq for PathBuf {}

1775: impl cmp::PartialOrd for PathBuf {

1782: impl cmp::Ord for PathBuf {

1789: impl AsRef<OsStr> for PathBuf {

2911: impl AsRef<Path> for PathBuf {

2918: impl<'a> IntoIterator for &'a PathBuf {

1964:     pub fn to_path_buf(&self) -> PathBuf {

2739:     pub fn into_path_buf(self: Box<Path>) -> PathBuf {

18: //! Cross-platform path manipulation.

20: //! This module provides two types, [`PathBuf`] and [`Path`] (akin to [`String`]

23: //! on strings according to the local platform's path syntax.

26: //! returned by the [`components`] method on [`Path`]. [`Component`]s roughly

27: //! correspond to the substrings between path separators (`/` or `\`). You can

28: //! reconstruct an equivalent path from components with the [`push`] method on

34: //! Unless otherwise indicated path methods that do not access the filesystem,

35: //! such as [`Path::starts_with`] and [`Path::ends_with`], are case sensitive no

41: //! Path manipulation includes both parsing components from slices and building

44: //! To parse a path, you can create a [`Path`] slice from a [`str`]

48: //! use std::path::Path;

51: //! let path = Path::new("/tmp/foo/bar.txt");

53: //! let parent = path.parent();

54: //! assert_eq!(parent, Some(Path::new("/tmp/foo")));

56: //! let file_stem = path.file_stem();

59: //! let extension = path.extension();

66: //! use std::path::PathBuf;

69: //! let mut path = PathBuf::from("c:\\");

71: //! path.push("windows");

72: //! path.push("system32");

74: //! path.set_extension("dll");

78: //! let path: PathBuf = ["c:\\", "windows", "system32.dll"].iter().collect();

81: //! [`components`]: Path::components

104: use crate::sys::path::{is_sep_byte, is_verbatim_sep, parse_prefix, MAIN_SEP_STR};

120: /// Windows path prefixes, e.g., `C:` or `\\server\share`.

122: /// Windows uses a variety of path prefix styles, including references to drive

124: /// others. In addition, some path prefixes are "verbatim" (i.e., prefixed with

131: /// use std::path::{Component, Path, Prefix};

132: /// use std::path::Prefix::*;

135: /// fn get_path_prefix(s: &str) -> Prefix {

136: ///     let path = Path::new(s);

137: ///     match path.components().next().unwrap() {

145: ///            get_path_prefix(r"\\?\pictures\kittens"));

147: ///            get_path_prefix(r"\\?\UNC\server\share"));

148: /// assert_eq!(VerbatimDisk(b'C'), get_path_prefix(r"\\?\c:\"));

150: ///            get_path_prefix(r"\\.\BrainInterface"));

152: ///            get_path_prefix(r"\\server\share"));

153: /// assert_eq!(Disk(b'C'), get_path_prefix(r"C:\Users\Rust\Pictures\Ferris"));

218:     /// use std::path::Prefix::*;

250: /// Determines whether the character is one of the permitted path

256: /// use std::path;

258: /// assert!(path::is_separator('/')); // '/' works for both Unix and Windows

259: /// assert!(!path::is_separator('❤'));

266: /// The primary separator of path components for the current platform.

269: pub const MAIN_SEPARATOR: char = crate::sys::path::MAIN_SEP;

271: /// The primary separator of path components for the current platform.

274: pub const MAIN_SEPARATOR_STR: &str = crate::sys::path::MAIN_SEP_STR;

322:     let path = if let Some(p) = prefix { &s[p.len()..] } else { s };

323:     !path.is_empty() && is_sep_byte(path[0])

370: /// front and back of the path each keep track of what parts of the path have

373: /// Going front to back, a path is made up of a prefix, a starting

383: /// A structure wrapping a Windows path prefix as well as its unparsed string

399: /// use std::path::{Component, Path, Prefix};

402: /// let path = Path::new(r"c:\you\later\");

403: /// match path.components().next().unwrap() {

471: /// A single component of a path.

473: /// A `Component` roughly corresponds to a substring between path separators

477: /// created by the [`components`](Path::components) method on [`Path`].

482: /// use std::path::{Component, Path};

484: /// let path = Path::new("/tmp/foo/bar.txt");

485: /// let components = path.components().collect::<Vec<_>>();

496:     /// A Windows path prefix, e.g., `C:` or `\\server\share`.

506:     /// It represents a separator that designates that a path starts from root.

528:     /// use std::path::Path;

530:     /// let path = Path::new("./tmp/foo/bar.txt");

531:     /// let components: Vec<_> = path.components().map(|comp| comp.as_os_str()).collect();

541:             Component::Normal(path) => path,

553: impl AsRef<Path> for Component<'_> {

555:     fn as_ref(&self) -> &Path {

560: /// An iterator over the [`Component`]s of a [`Path`].

562: /// This `struct` is created by the [`components`] method on [`Path`].

568: /// use std::path::Path;

570: /// let path = Path::new("/tmp/foo/bar.txt");

572: /// for component in path.components() {

577: /// [`components`]: Path::components

581:     // The path left to parse components from

587:     // true if path *physically* has a root separator; for most Windows

598: /// An iterator over the [`Component`]s of a [`Path`], as [`OsStr`] slices.

600: /// This `struct` is created by the [`iter`] method on [`Path`].

603: /// [`iter`]: Path::iter

612:         struct DebugHelper<'a>(&'a Path);

620:         f.debug_tuple("Components").field(&DebugHelper(self.as_path())).finish()

642:     // Given the iteration so far, how much of the pre-State::Body path is left?

661:     /// Extracts a slice corresponding to the portion of the path remaining for iteration.

666:     /// use std::path::Path;

668:     /// let mut components = Path::new("/tmp/foo/bar.txt").components();

672:     /// assert_eq!(Path::new("foo/bar.txt"), components.as_path());

683:         unsafe { Path::from_u8_slice(comps.path) }

686:     /// Is the *original* path rooted?

699:     /// Should the normalized path include a leading . ?

704:         let mut iter = self.path[self.prefix_remaining()..].iter();

712:     // parse a given byte sequence into the corresponding path component

717:             // the beginning of a path, which is treated

729:         let (extra, comp) = match self.path.iter().position(|b| self.is_sep_byte(*b)) {

730:             None => (0, self.path),

731:             Some(i) => (1, &self.path[..i]),

741:         let (extra, comp) = match self.path[start..].iter().rposition(|b| self.is_sep_byte(*b)) {

742:             None => (0, &self.path[start..]),

743:             Some(i) => (1, &self.path[start + i + 1..]),

750:         while !self.path.is_empty() {

755:                 self.path = &self.path[size..];

762:         while self.path.len() > self.len_before_body() {

767:                 self.path = &self.path[..self.path.len() - size];

773: impl AsRef<Path> for Components<'_> {

775:     fn as_ref(&self) -> &Path {

776:         self.as_path()

783:         self.as_path().as_os_str()

789:         struct DebugHelper<'a>(&'a Path);

797:         f.debug_tuple("Iter").field(&DebugHelper(self.as_path())).finish()

802:     /// Extracts a slice corresponding to the portion of the path remaining for iteration.

807:     /// use std::path::Path;

809:     /// let mut iter = Path::new("/tmp/foo/bar.txt").iter();

813:     /// assert_eq!(Path::new("foo/bar.txt"), iter.as_path());

818:         self.inner.as_path()

822: impl AsRef<Path> for Iter<'_> {

824:     fn as_ref(&self) -> &Path {

825:         self.as_path()

832:         self.as_path().as_os_str()

862:                     debug_assert!(self.prefix_len() <= self.path.len());

863:                     let raw = &self.path[..self.prefix_len()];

864:                     self.path = &self.path[self.prefix_len()..];

876:                         debug_assert!(!self.path.is_empty());

877:                         self.path = &self.path[1..];

884:                         debug_assert!(!self.path.is_empty());

885:                         self.path = &self.path[1..];

889:                 State::Body if !self.path.is_empty() => {

891:                     self.path = &self.path[size..];

910:                 State::Body if self.path.len() > self.len_before_body() => {

912:                     self.path = &self.path[..self.path.len() - size];

923:                         self.path = &self.path[..self.path.len() - 1];

930:                         self.path = &self.path[..self.path.len() - 1];

937:                         raw: unsafe { u8_slice_as_os_str(self.path) },

957:         let Components { path: _, front: _, back: _, has_physical_root: _, prefix: _ } = self;

959:         // Fast path for exact matches, e.g. for hashmap lookups.

961:         // either be covered by the `path` buffer or are only relevant for `prefix_verbatim()`.

962:         if self.path.len() == other.path.len()

970:             if self.path == other.path {

997:     // Fast path for long shared prefixes

1002:     //   otherwise do it on the full path

1004:     // The fast path isn't taken for paths with a PrefixComponent to avoid backtracking into

1008:         let first_difference = match left.path.iter().zip(right.path).position(|(&a, &b)| a != b) {

1009:             None if left.path.len() == right.path.len() => return cmp::Ordering::Equal,

1010:             None => left.path.len().min(right.path.len()),

1015:             left.path[..first_difference].iter().rposition(|&b| left.is_sep_byte(b))

1018:             left.path = &left.path[mismatched_component_start..];

1020:             right.path = &right.path[mismatched_component_start..];

1028: /// An iterator over [`Path`] and its ancestors.

1030: /// This `struct` is created by the [`ancestors`] method on [`Path`].

1036: /// use std::path::Path;

1038: /// let path = Path::new("/foo/bar");

1040: /// for ancestor in path.ancestors() {

1045: /// [`ancestors`]: Path::ancestors

1049:     next: Option<&'a Path>,

1053:     type Item = &'a Path;

1058:         self.next = next.and_then(Path::parent);

1069: /// An owned, mutable path (akin to [`String`]).

1072: /// the path in place. It also implements [`Deref`] to [`Path`], meaning that

1073: /// all methods on [`Path`] slices are available on `PathBuf` values as well.

1087: /// use std::path::PathBuf;

1089: /// let mut path = PathBuf::new();

1091: /// path.push(r"C:\");

1092: /// path.push("windows");

1093: /// path.push("system32");

1095: /// path.set_extension("dll");

1102: /// use std::path::PathBuf;

1104: /// let path: PathBuf = [r"C:\", "windows", "system32.dll"].iter().collect();

1111: /// use std::path::PathBuf;

1113: /// let path = PathBuf::from(r"C:\windows\system32.dll");

1139:     /// use std::path::PathBuf;

1141:     /// let path = PathBuf::new();

1155:     /// use std::path::PathBuf;

1157:     /// let mut path = PathBuf::with_capacity(10);

1158:     /// let capacity = path.capacity();

1161:     /// path.push(r"C:\");

1163:     /// assert_eq!(capacity, path.capacity());

1173:     /// Coerces to a [`Path`] slice.

1178:     /// use std::path::{Path, PathBuf};

1181:     /// assert_eq!(Path::new("/test"), p.as_path());

1190:     /// Extends `self` with `path`.

1192:     /// If `path` is absolute, it replaces the current path.

1196:     /// * if `path` has a root but no prefix (e.g., `\windows`), it

1198:     /// * if `path` has a prefix but no root, it replaces `self`.

1200:     ///   and `path` is not empty, the new path is normalized: all references

1205:     /// Pushing a relative path extends the existing path:

1208:     /// use std::path::PathBuf;

1210:     /// let mut path = PathBuf::from("/tmp");

1211:     /// path.push("file.bk");

1212:     /// assert_eq!(path, PathBuf::from("/tmp/file.bk"));

1215:     /// Pushing an absolute path replaces the existing path:

1218:     /// use std::path::PathBuf;

1220:     /// let mut path = PathBuf::from("/tmp");

1221:     /// path.push("/etc");

1222:     /// assert_eq!(path, PathBuf::from("/etc"));

1224:     pub fn push<P: AsRef<Path>>(&mut self, path: P) {

1225:         self._push(path.as_ref())

1228:     fn _push(&mut self, path: &Path) {

1236:             && comps.prefix_len() == comps.path.len()

1242:         // absolute `path` replaces `self`

1243:         if path.is_absolute() || path.prefix().is_some() {

1247:         } else if comps.prefix_verbatim() && !path.inner.is_empty() {

1249:             for c in path.components() {

1286:         // `path` has a root but no prefix, e.g., `\windows` (Windows only)

1287:         } else if path.has_root() {

1291:         // `path` is a pure relative path

1296:         self.inner.push(path);

1304:     /// [`self.parent`]: Path::parent

1309:     /// use std::path::{Path, PathBuf};

1314:     /// assert_eq!(Path::new("/spirited"), p);

1316:     /// assert_eq!(Path::new("/"), p);

1334:     /// `file_name`. The new path will be a sibling of the original path.

1337:     /// [`self.file_name`]: Path::file_name

1343:     /// use std::path::PathBuf;

1373:     /// [`self.file_name`]: Path::file_name

1374:     /// [`self.extension`]: Path::extension

1379:     /// use std::path::{Path, PathBuf};

1384:     /// assert_eq!(Path::new("/feel/the.force"), p.as_path());

1387:     /// assert_eq!(Path::new("/feel/the.dark_side"), p.as_path());

1421:     /// use std::path::PathBuf;

1432:     /// Converts this `PathBuf` into a [boxed](Box) [`Path`].

1436:         let rw = Box::into_raw(self.inner.into_boxed_os_str()) as *mut Path;

1519: impl From<&Path> for Box<Path> {

1520:     /// Creates a boxed [`Path`] from a reference.

1522:     /// This will allocate and clone `path` to it.

1523:     fn from(path: &Path) -> Box<Path> {

1524:         let boxed: Box<OsStr> = path.inner.into();

1525:         let rw = Box::into_raw(boxed) as *mut Path;

1530: impl From<Cow<'_, Path>> for Box<Path> {

1531:     /// Creates a boxed [`Path`] from a clone-on-write pointer.

1535:     fn from(cow: Cow<'_, Path>) -> Box<Path> {

1537:             Cow::Borrowed(path) => Box::from(path),

1538:             Cow::Owned(path) => Box::from(path),

1544:     /// Converts a <code>[Box]&lt;[Path]&gt;</code> into a [`PathBuf`].

1548:     fn from(boxed: Box<Path>) -> PathBuf {

1549:         boxed.into_path_buf()

1553: impl From<PathBuf> for Box<Path> {

1554:     /// Converts a [`PathBuf`] into a <code>[Box]&lt;[Path]&gt;</code>.

1559:     fn from(p: PathBuf) -> Box<Path> {

1560:         p.into_boxed_path()

1564: impl Clone for Box<Path> {

1567:         self.to_path_buf().into_boxed_path()

1596:     fn from(path_buf: PathBuf) -> OsString {

1597:         path_buf.inner

1646:     type Target = Path;

1648:     fn deref(&self) -> &Path {

1649:         Path::new(&self.inner)

1655:     fn borrow(&self) -> &Path {

1667: impl<'a> From<&'a Path> for Cow<'a, Path> {

1669:     /// [`Path`].

1673:     fn from(s: &'a Path) -> Cow<'a, Path> {

1678: impl<'a> From<PathBuf> for Cow<'a, Path> {

1684:     fn from(s: PathBuf) -> Cow<'a, Path> {

1689: impl<'a> From<&'a PathBuf> for Cow<'a, Path> {

1695:     fn from(p: &'a PathBuf) -> Cow<'a, Path> {

1696:         Cow::Borrowed(p.as_path())

1701:     /// Converts a clone-on-write pointer to an owned path.

1705:     fn from(p: Cow<'a, Path>) -> Self {

1710: impl From<PathBuf> for Arc<Path> {

1711:     /// Converts a [`PathBuf`] into an <code>[Arc]<[Path]></code> by moving the [`PathBuf`] data

1714:     fn from(s: PathBuf) -> Arc<Path> {

1716:         unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Path) }

1720: impl From<&Path> for Arc<Path> {

1721:     /// Converts a [`Path`] into an [`Arc`] by copying the [`Path`] data into a new [`Arc`] buffer.

1723:     fn from(s: &Path) -> Arc<Path> {

1725:         unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Path) }

1729: impl From<PathBuf> for Rc<Path> {

1730:     /// Converts a [`PathBuf`] into an <code>[Rc]<[Path]></code> by moving the [`PathBuf`] data into

1733:     fn from(s: PathBuf) -> Rc<Path> {

1735:         unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Path) }

1739: impl From<&Path> for Rc<Path> {

1740:     /// Converts a [`Path`] into an [`Rc`] by copying the [`Path`] data into a new [`Rc`] buffer.

1742:     fn from(s: &Path) -> Rc<Path> {

1744:         unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Path) }

1752:         self.to_path_buf()

1769:         self.as_path().hash(h)

1796: /// A slice of a path (akin to [`str`]).

1798: /// This type supports a number of operations for inspecting a path, including

1799: /// breaking the path into its components (separated by `/` on Unix and by either

1800: /// `/` or `\` on Windows), extracting the file name, determining whether the path

1813: /// use std::path::Path;

1817: /// let path = Path::new("./foo/bar.txt");

1819: /// let parent = path.parent();

1820: /// assert_eq!(parent, Some(Path::new("./foo")));

1822: /// let file_stem = path.file_stem();

1825: /// let extension = path.extension();

1828: #[cfg_attr(not(test), rustc_diagnostic_item = "Path")]

1830: // `Path::new` current implementation relies

1831: // on `Path` being layout-compatible with `OsStr`.

1832: // When attribute privacy is implemented, `Path` should be annotated as `#[repr(transparent)]`.

1833: // Anyway, `Path` representation and layout are considered implementation detail, are

1839: /// An error returned from [`Path::strip_prefix`] if the prefix was not found.

1841: /// This `struct` is created by the [`strip_prefix`] method on [`Path`].

1844: /// [`strip_prefix`]: Path::strip_prefix

1849:     // The following (private!) function allows construction of a path from a u8

1851:     unsafe fn from_u8_slice(s: &[u8]) -> &Path {

1852:         Path::new(u8_slice_as_os_str(s))

1859:     /// Directly wraps a string slice as a `Path` slice.

1866:     /// use std::path::Path;

1868:     /// Path::new("foo.txt");

1871:     /// You can create `Path`s from `String`s, or even other `Path`s:

1874:     /// use std::path::Path;

1877:     /// let from_string = Path::new(&string);

1878:     /// let from_path = Path::new(&from_string);

1879:     /// assert_eq!(from_string, from_path);

1881:     pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &Path {

1882:         unsafe { &*(s.as_ref() as *const OsStr as *const Path) }

1890:     /// use std::path::Path;

1892:     /// let os_str = Path::new("foo.txt").as_os_str();

1901:     /// Yields a [`&str`] slice if the `Path` is valid unicode.

1912:     /// use std::path::Path;

1914:     /// let path = Path::new("foo.txt");

1915:     /// assert_eq!(path.to_str(), Some("foo.txt"));

1924:     /// Converts a `Path` to a [`Cow<str>`].

1933:     /// Calling `to_string_lossy` on a `Path` with valid unicode:

1936:     /// use std::path::Path;

1938:     /// let path = Path::new("foo.txt");

1939:     /// assert_eq!(path.to_string_lossy(), "foo.txt");

1942:     /// Had `path` contained invalid unicode, the `to_string_lossy` call might

1951:     /// Converts a `Path` to an owned [`PathBuf`].

1956:     /// use std::path::Path;

1958:     /// let path_buf = Path::new("foo.txt").to_path_buf();

1959:     /// assert_eq!(path_buf, std::path::PathBuf::from("foo.txt"));

1968:     /// Returns `true` if the `Path` is absolute, i.e., if it is independent of

1971:     /// * On Unix, a path is absolute if it starts with the root, so

1974:     /// * On Windows, a path is absolute if it has a prefix and starts with the

1980:     /// use std::path::Path;

1982:     /// assert!(!Path::new("foo.txt").is_absolute());

1985:     /// [`has_root`]: Path::has_root

1992:     /// Returns `true` if the `Path` is relative, i.e., not absolute.

1999:     /// use std::path::Path;

2001:     /// assert!(Path::new("foo.txt").is_relative());

2004:     /// [`is_absolute`]: Path::is_absolute

2015:     /// Returns `true` if the `Path` has a root.

2017:     /// * On Unix, a path has a root if it begins with `/`.

2019:     /// * On Windows, a path has a root if it:

2027:     /// use std::path::Path;

2029:     /// assert!(Path::new("/etc/passwd").has_root());

2037:     /// Returns the `Path` without its final component, if there is one.

2039:     /// Returns [`None`] if the path terminates in a root or prefix.

2044:     /// use std::path::Path;

2046:     /// let path = Path::new("/foo/bar");

2047:     /// let parent = path.parent().unwrap();

2048:     /// assert_eq!(parent, Path::new("/foo"));

2051:     /// assert_eq!(grand_parent, Path::new("/"));

2055:     pub fn parent(&self) -> Option<&Path> {

2060:                 Some(comps.as_path())

2066:     /// Produces an iterator over `Path` and its ancestors.

2068:     /// The iterator will yield the `Path` that is returned if the [`parent`] method is used zero

2077:     /// use std::path::Path;

2079:     /// let mut ancestors = Path::new("/foo/bar").ancestors();

2080:     /// assert_eq!(ancestors.next(), Some(Path::new("/foo/bar")));

2081:     /// assert_eq!(ancestors.next(), Some(Path::new("/foo")));

2082:     /// assert_eq!(ancestors.next(), Some(Path::new("/")));

2085:     /// let mut ancestors = Path::new("../foo/bar").ancestors();

2086:     /// assert_eq!(ancestors.next(), Some(Path::new("../foo/bar")));

2087:     /// assert_eq!(ancestors.next(), Some(Path::new("../foo")));

2088:     /// assert_eq!(ancestors.next(), Some(Path::new("..")));

2089:     /// assert_eq!(ancestors.next(), Some(Path::new("")));

2093:     /// [`parent`]: Path::parent

2099:     /// Returns the final component of the `Path`, if there is one.

2101:     /// If the path is a normal file, this is the file name. If it's the path of a directory, this

2104:     /// Returns [`None`] if the path terminates in `..`.

2109:     /// use std::path::Path;

2112:     /// assert_eq!(Some(OsStr::new("bin")), Path::new("/usr/bin/").file_name());

2113:     /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("tmp/foo.txt").file_name());

2114:     /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.").file_name());

2115:     /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.//").file_name());

2116:     /// assert_eq!(None, Path::new("foo.txt/..").file_name());

2117:     /// assert_eq!(None, Path::new("/").file_name());

2127:     /// Returns a path that, when joined onto `base`, yields `self`.

2134:     /// [`starts_with`]: Path::starts_with

2139:     /// use std::path::{Path, PathBuf};

2141:     /// let path = Path::new("/test/haha/foo.txt");

2143:     /// assert_eq!(path.strip_prefix("/"), Ok(Path::new("test/haha/foo.txt")));

2144:     /// assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt")));

2145:     /// assert_eq!(path.strip_prefix("/test/"), Ok(Path::new("haha/foo.txt")));

2146:     /// assert_eq!(path.strip_prefix("/test/haha/foo.txt"), Ok(Path::new("")));

2147:     /// assert_eq!(path.strip_prefix("/test/haha/foo.txt/"), Ok(Path::new("")));

2149:     /// assert!(path.strip_prefix("test").is_err());

2150:     /// assert!(path.strip_prefix("/haha").is_err());

2153:     /// assert_eq!(path.strip_prefix(prefix), Ok(Path::new("haha/foo.txt")));

2155:     pub fn strip_prefix<P>(&self, base: P) -> Result<&Path, StripPrefixError>

2157:         P: AsRef<Path>,

2162:     fn _strip_prefix(&self, base: &Path) -> Result<&Path, StripPrefixError> {

2164:             .map(|c| c.as_path())

2170:     /// Only considers whole path components to match.

2175:     /// use std::path::Path;

2177:     /// let path = Path::new("/etc/passwd");

2179:     /// assert!(path.starts_with("/etc"));

2180:     /// assert!(path.starts_with("/etc/"));

2181:     /// assert!(path.starts_with("/etc/passwd"));

2182:     /// assert!(path.starts_with("/etc/passwd/")); // extra slash is okay

2183:     /// assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay

2185:     /// assert!(!path.starts_with("/e"));

2186:     /// assert!(!path.starts_with("/etc/passwd.txt"));

2188:     /// assert!(!Path::new("/etc/foo.rs").starts_with("/etc/foo"));

2191:     pub fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool {

2195:     fn _starts_with(&self, base: &Path) -> bool {

2201:     /// Only considers whole path components to match.

2206:     /// use std::path::Path;

2208:     /// let path = Path::new("/etc/resolv.conf");

2210:     /// assert!(path.ends_with("resolv.conf"));

2211:     /// assert!(path.ends_with("etc/resolv.conf"));

2212:     /// assert!(path.ends_with("/etc/resolv.conf"));

2214:     /// assert!(!path.ends_with("/resolv.conf"));

2215:     /// assert!(!path.ends_with("conf")); // use .extension() instead

2218:     pub fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool {

2222:     fn _ends_with(&self, child: &Path) -> bool {

2228:     /// [`self.file_name`]: Path::file_name

2240:     /// use std::path::Path;

2242:     /// assert_eq!("foo", Path::new("foo.rs").file_stem().unwrap());

2243:     /// assert_eq!("foo.tar", Path::new("foo.tar.gz").file_stem().unwrap());

2247:     /// This method is similar to [`Path::file_prefix`], which extracts the portion of the file name

2250:     /// [`Path::file_prefix`]: Path::file_prefix

2267:     /// [`self.file_name`]: Path::file_name

2272:     /// # #![feature(path_file_prefix)]

2273:     /// use std::path::Path;

2275:     /// assert_eq!("foo", Path::new("foo.rs").file_prefix().unwrap());

2276:     /// assert_eq!("foo", Path::new("foo.tar.gz").file_prefix().unwrap());

2280:     /// This method is similar to [`Path::file_stem`], which extracts the portion of the file name

2283:     /// [`Path::file_stem`]: Path::file_stem

2300:     /// [`self.file_name`]: Path::file_name

2305:     /// use std::path::Path;

2307:     /// assert_eq!("rs", Path::new("foo.rs").extension().unwrap());

2308:     /// assert_eq!("gz", Path::new("foo.tar.gz").extension().unwrap());

2315:     /// Creates an owned [`PathBuf`] with `path` adjoined to `self`.

2317:     /// See [`PathBuf::push`] for more details on what it means to adjoin a path.

2322:     /// use std::path::{Path, PathBuf};

2324:     /// assert_eq!(Path::new("/etc").join("passwd"), PathBuf::from("/etc/passwd"));

2327:     pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf {

2328:         self._join(path.as_ref())

2331:     fn _join(&self, path: &Path) -> PathBuf {

2332:         let mut buf = self.to_path_buf();

2333:         buf.push(path);

2344:     /// use std::path::{Path, PathBuf};

2346:     /// let path = Path::new("/tmp/foo.txt");

2347:     /// assert_eq!(path.with_file_name("bar.txt"), PathBuf::from("/tmp/bar.txt"));

2349:     /// let path = Path::new("/tmp");

2350:     /// assert_eq!(path.with_file_name("var"), PathBuf::from("/var"));

2358:         let mut buf = self.to_path_buf();

2370:     /// use std::path::{Path, PathBuf};

2372:     /// let path = Path::new("foo.rs");

2373:     /// assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt"));

2375:     /// let path = Path::new("foo.tar.gz");

2376:     /// assert_eq!(path.with_extension(""), PathBuf::from("foo.tar"));

2377:     /// assert_eq!(path.with_extension("xz"), PathBuf::from("foo.tar.xz"));

2378:     /// assert_eq!(path.with_extension("").with_extension("txt"), PathBuf::from("foo.txt"));

2385:         let mut buf = self.to_path_buf();

2390:     /// Produces an iterator over the [`Component`]s of the path.

2392:     /// When parsing the path, there is a small amount of normalization:

2398:     ///   beginning of the path. For example, `a/./b`, `a/b/`, `a/b/.` and

2411:     /// use std::path::{Path, Component};

2414:     /// let mut components = Path::new("/tmp/foo.txt").components();

2426:             path: self.as_u8_slice(),

2434:     /// Produces an iterator over the path's components viewed as [`OsStr`]

2437:     /// For more information about the particulars of how the path is separated

2440:     /// [`components`]: Path::components

2445:     /// use std::path::{self, Path};

2448:     /// let mut it = Path::new("/tmp/foo.txt").iter();

2449:     /// assert_eq!(it.next(), Some(OsStr::new(&path::MAIN_SEPARATOR.to_string())));

2462:     /// escapes the path please use [`Debug`] instead.

2469:     /// use std::path::Path;

2471:     /// let path = Path::new("/tmp/foo.rs");

2473:     /// println!("{}", path.display());

2475:     #[must_use = "this does not display the path, \

2479:         Display { path: self }

2492:     /// use std::path::Path;

2494:     /// let path = Path::new("/Minas/tirith");

2495:     /// let metadata = path.metadata().expect("metadata call failed");

2511:     /// use std::path::Path;

2513:     /// let path = Path::new("/Minas/tirith");

2514:     /// let metadata = path.symlink_metadata().expect("symlink_metadata call failed");

2523:     /// Returns the canonical, absolute form of the path with all intermediate

2531:     /// use std::path::{Path, PathBuf};

2533:     /// let path = Path::new("/foo/test/../test/bar.rs");

2534:     /// assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs"));

2549:     /// use std::path::Path;

2551:     /// let path = Path::new("/laputa/sky_castle.rs");

2552:     /// let path_link = path.read_link().expect("read_link call failed");

2570:     /// use std::path::Path;

2572:     /// let path = Path::new("/laputa");

2573:     /// for entry in path.read_dir().expect("read_dir call failed") {

2575:     ///         println!("{:?}", entry.path());

2585:     /// Returns `true` if the path points at an existing entity.

2599:     /// use std::path::Path;

2600:     /// assert!(!Path::new("does_not_exist.txt").exists());

2606:     /// check errors, call [`Path::try_exists`].

2616:     /// Returns `Ok(true)` if the path points at an existing entity.

2622:     /// unrelated to the path not existing. (E.g. it will return `Err(_)` in case of permission

2632:     /// use std::path::Path;

2633:     /// assert!(!Path::new("does_not_exist.txt").try_exists().expect("Can't check existence of file does_not_exist.txt"))...(1 bytes skipped)...

2634:     /// assert!(Path::new("/root/secret_file.txt").try_exists().is_err());

2644:     /// Returns `true` if the path exists on disk and is pointing at a regular file.

2655:     /// use std::path::Path;

2656:     /// assert_eq!(Path::new("./is_a_directory/").is_file(), false);

2657:     /// assert_eq!(Path::new("a_file.txt").is_file(), true);

2677:     /// Returns `true` if the path exists on disk and is pointing at a directory.

2688:     /// use std::path::Path;

2689:     /// assert_eq!(Path::new("./is_a_directory/").is_dir(), true);

2690:     /// assert_eq!(Path::new("a_file.txt").is_dir(), false);

2704:     /// Returns `true` if the path exists on disk and is pointing at a symbolic link.

2716:     /// use std::path::Path;

2719:     /// let link_path = Path::new("link");

2720:     /// symlink("/origin_does_not_exist/", link_path).unwrap();

2721:     /// assert_eq!(link_path.is_symlink(), true);

2722:     /// assert_eq!(link_path.exists(), false);

2736:     /// Converts a [`Box<Path>`](Box) into a [`PathBuf`] without copying or

2761: /// A [`Path`] might contain non-Unicode data. This `struct` implements the

2763: /// [`display`](Path::display) method on [`Path`]. This may perform lossy

2765: /// which escapes the path please use [`Debug`] instead.

2770: /// use std::path::Path;

2772: /// let path = Path::new("/tmp/foo.rs");

2774: /// println!("{}", path.display());

2785:         fmt::Debug::fmt(&self.path, f)

2791:         self.path.inner.display(f)

2797:     fn eq(&self, other: &Path) -> bool {

2857:     fn partial_cmp(&self, other: &Path) -> Option<cmp::Ordering> {

2864:     fn cmp(&self, other: &Path) -> cmp::Ordering {

2871:     fn as_ref(&self) -> &Path {

2876: impl AsRef<Path> for OsStr {

2878:     fn as_ref(&self) -> &Path {

2879:         Path::new(self)

2883: impl AsRef<Path> for Cow<'_, OsStr> {

2885:     fn as_ref(&self) -> &Path {

2886:         Path::new(self)

2890: impl AsRef<Path> for OsString {

2892:     fn as_ref(&self) -> &Path {

2893:         Path::new(self)

2897: impl AsRef<Path> for str {

2899:     fn as_ref(&self) -> &Path {

2900:         Path::new(self)

2904: impl AsRef<Path> for String {

2906:     fn as_ref(&self) -> &Path {

2907:         Path::new(self)

2913:     fn as_ref(&self) -> &Path {

2941:                 <Path as PartialEq>::eq(self, other)

2948:                 <Path as PartialEq>::eq(self, other)

2955:                 <Path as PartialOrd>::partial_cmp(self, other)

2962:                 <Path as PartialOrd>::partial_cmp(self, other)

2968: impl_cmp!(PathBuf, Path);

2969: impl_cmp!(PathBuf, &'a Path);

2970: impl_cmp!(Cow<'a, Path>, Path);

2971: impl_cmp!(Cow<'a, Path>, &'b Path);

2972: impl_cmp!(Cow<'a, Path>, PathBuf);

2979:                 <Path as PartialEq>::eq(self, other.as_ref())

2986:                 <Path as PartialEq>::eq(self.as_ref(), other)

2993:                 <Path as PartialOrd>::partial_cmp(self, other.as_ref())

3000:                 <Path as PartialOrd>::partial_cmp(self.as_ref(), other)

3010: impl_cmp_os_str!(Path, OsStr);

3011: impl_cmp_os_str!(Path, &'a OsStr);

3012: impl_cmp_os_str!(Path, Cow<'a, OsStr>);

3013: impl_cmp_os_str!(Path, OsString);

3014: impl_cmp_os_str!(&'a Path, OsStr);

3015: impl_cmp_os_str!(&'a Path, Cow<'b, OsStr>);

3016: impl_cmp_os_str!(&'a Path, OsString);

3017: impl_cmp_os_str!(Cow<'a, Path>, OsStr);

3018: impl_cmp_os_str!(Cow<'a, Path>, &'b OsStr);

3019: impl_cmp_os_str!(Cow<'a, Path>, OsString);

3035: /// Makes the path absolute without accessing the filesystem.

3037: /// If the path is relative, the current directory is used as the base directory.

3040: /// resolve symlinks and may succeed even if the path does not exist.

3042: /// If the `path` is empty or getting the

3051: /// #![feature(absolute_path)]

3054: ///   use std::path::{self, Path};

3057: ///   let absolute = path::absolute("foo/./bar")?;

3061: ///   let absolute = path::absolute("/foo//test/.././bar.rs")?;

3062: ///   assert_eq!(absolute, Path::new("/foo/test/../bar.rs"));

3069: /// The path is resolved using [POSIX semantics][posix-semantics] except that

3076: /// #![feature(absolute_path)]

3079: ///   use std::path::{self, Path};

3082: ///   let absolute = path::absolute("foo/./bar")?;

3086: ///   let absolute = path::absolute(r"C:\foo//test\..\./bar.rs")?;

3088: ///   assert_eq!(absolute, Path::new(r"C:\foo\bar.rs"));

3095: /// For verbatim paths this will simply return the path as given. For other

3096: /// paths this is currently equivalent to calling [`GetFullPathNameW`][windows-path]

3100: /// [windows-path]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfullpathnamew

3102: pub fn absolute<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {

3103:     _absolute(path)

3106: pub(crate) fn _absolute<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {

3107:     let path = path.as_ref();

3108:     if path.as_os_str().is_empty() {

3109:         Err(io::const_io_error!(io::ErrorKind::InvalidInput, "cannot make an empty path absolute",))

3111:         sys::path::absolute(path)

21: //! and [`str`]), for working with paths abstractly. These types are thin wrappers

25: //! Paths can be parsed into [`Component`]s by iterating over the structure

29: //! [`PathBuf`]; note that the paths may differ syntactically by the

42: //! new owned paths.

63: //! To build or modify paths, use [`PathBuf`]:

82: //! [`push`]: PathBuf::push

975:         // compare back to front since absolute paths often share long prefixes

1075: /// [`push`]: PathBuf::push

1076: /// [`set_extension`]: PathBuf::set_extension

1083: /// You can use [`push`] to build up a `PathBuf` from

1117: #[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")]

1119: // `PathBuf::as_mut_vec` current implementation relies

1120: // on `PathBuf` being layout-compatible with `Vec<u8>`.

1121: // When attribute privacy is implemented, `PathBuf` should be annotated as `#[repr(transparent)]`.

1122: // Anyway, `PathBuf` representation and layout are considered implementation detail, are

1131:         unsafe { &mut *(self as *mut PathBuf as *mut Vec<u8>) }

1134:     /// Allocates an empty `PathBuf`.

1145:     pub fn new() -> PathBuf {

1146:         PathBuf { inner: OsString::new() }

1149:     /// Creates a new `PathBuf` with a given capacity used to create the

1169:     pub fn with_capacity(capacity: usize) -> PathBuf {

1170:         PathBuf { inner: OsString::with_capacity(capacity) }

1180:     /// let p = PathBuf::from("/test");

1246:         // verbatim paths need . and .. removed

1311:     /// let mut p = PathBuf::from("/spirited/away.rs");

1338:     /// [`pop`]: PathBuf::pop

1345:     /// let mut buf = PathBuf::from("/");

1348:     /// assert!(buf == PathBuf::from("/bar"));

1351:     /// assert!(buf == PathBuf::from("/baz.txt"));

1381:     /// let mut p = PathBuf::from("/feel/the");

1416:     /// Consumes the `PathBuf`, yielding its internal [`OsString`] storage.

1423:     /// let p = PathBuf::from("/the/head");

1510:         PathBuf { inner: self.inner.clone() }

1572:     /// Converts a borrowed [`OsStr`] to a [`PathBuf`].

1574:     /// Allocates a [`PathBuf`] and copies the data into it.

1576:     fn from(s: &T) -> PathBuf {

1577:         PathBuf::from(s.as_ref().to_os_string())

1582:     /// Converts an [`OsString`] into a [`PathBuf`]

1586:     fn from(s: OsString) -> PathBuf {

1587:         PathBuf { inner: s }

1591: impl From<PathBuf> for OsString {

1592:     /// Converts a [`PathBuf`] into an [`OsString`]

1602:     /// Converts a [`String`] into a [`PathBuf`]

1606:     fn from(s: String) -> PathBuf {

1607:         PathBuf::from(OsString::from(s))

1616:         Ok(PathBuf::from(s))

1621:     fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> PathBuf {

1622:         let mut buf = PathBuf::new();

1663:         PathBuf::new()

1680:     /// instance of [`PathBuf`].

1691:     /// [`PathBuf`].

1749:     type Owned = PathBuf;

1751:     fn to_owned(&self) -> PathBuf {

1755:     fn clone_into(&self, target: &mut PathBuf) {

1762:     fn eq(&self, other: &PathBuf) -> bool {

1777:     fn partial_cmp(&self, other: &PathBuf) -> Option<cmp::Ordering> {

1784:     fn cmp(&self, other: &PathBuf) -> cmp::Ordering {

1805: /// see [`PathBuf`].

1965:         PathBuf::from(self.inner.to_os_string())

2152:     /// let prefix = PathBuf::from("/test/");

2337:     /// Creates an owned [`PathBuf`] like `self` but with the given file name.

2339:     /// See [`PathBuf::set_file_name`] for more details.

2353:     pub fn with_file_name<S: AsRef<OsStr>>(&self, file_name: S) -> PathBuf {

2357:     fn _with_file_name(&self, file_name: &OsStr) -> PathBuf {

2363:     /// Creates an owned [`PathBuf`] like `self` but with the given extension.

2365:     /// See [`PathBuf::set_extension`] for more details.

2380:     pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {

2384:     fn _with_extension(&self, extension: &OsStr) -> PathBuf {

2459:     /// Returns an object that implements [`Display`] for safely printing paths

2538:     pub fn canonicalize(&self) -> io::Result<PathBuf> {

2556:     pub fn read_link(&self) -> io::Result<PathBuf> {

2742:         PathBuf { inner: OsString::from(inner) }

2759: /// Helper struct for safely printing paths with [`format!`] and `{}`.

3006: impl_cmp_os_str!(PathBuf, OsStr);

3007: impl_cmp_os_str!(PathBuf, &'a OsStr);

3008: impl_cmp_os_str!(PathBuf, Cow<'a, OsStr>);

3009: impl_cmp_os_str!(PathBuf, OsString);

3048: /// ## Posix paths

3073: /// ## Windows paths

18: package path

392:     path: &'a [u8],

1202: impl ToOwned for Path {

1262: pub struct Path {

1277: impl Path {

1730: impl AsRef<OsStr> for Path {

1736: impl fmt::Debug for Path {

1749:     path: &'a Path,

1764: impl cmp::PartialEq for Path {

1770: impl Hash for Path {

1778: impl cmp::Eq for Path {}

1780: impl cmp::PartialOrd for Path {

1786: impl cmp::Ord for Path {

1792: impl AsRef<Path> for Path {

1844: impl<'a> IntoIterator for &'a Path {

475:     pub fn as_path(&self) -> &'a Path {

602:     pub fn as_path(&self) -> &'a Path {

823:     pub fn as_path(&self) -> &Path {

968:     pub fn into_boxed_path(self) -> Box<Path> {

797: pub struct PathBuf {

801: impl PathBuf {

1030: impl From<Box<Path>> for PathBuf {

1056: impl<T: ?Sized + AsRef<OsStr>> From<&T> for PathBuf {

1062: impl From<OsString> for PathBuf {

1081: impl From<String> for PathBuf {

1090: impl FromStr for PathBuf {

1098: impl<P: AsRef<Path>> iter::FromIterator<P> for PathBuf {

1106: impl<P: AsRef<Path>> iter::Extend<P> for PathBuf {

1112: impl fmt::Debug for PathBuf {

1118: impl ops::Deref for PathBuf {

1126: impl Borrow<Path> for PathBuf {

1132: impl Default for PathBuf {

1159: impl<'a> From<Cow<'a, Path>> for PathBuf {

1212: impl cmp::PartialEq for PathBuf {

1218: impl Hash for PathBuf {

1224: impl cmp::Eq for PathBuf {}

1226: impl cmp::PartialOrd for PathBuf {

1232: impl cmp::Ord for PathBuf {

1238: impl AsRef<OsStr> for PathBuf {

1829: impl AsRef<Path> for PathBuf {

1836: impl<'a> IntoIterator for &'a PathBuf {

1333:     pub fn to_path_buf(&self) -> PathBuf {

1723:     pub fn into_path_buf(self: Box<Path>) -> PathBuf {

18: //! Cross-platform path manipulation.

20: //! This module provides two types, [`PathBuf`] and [`Path`] (akin to [`String`]

23: //! on strings according to the local platform's path syntax.

26: //! returned by the [`components`] method on [`Path`]. [`Component`]s roughly

27: //! correspond to the substrings between path separators (`/` or `\`). You can

28: //! reconstruct an equivalent path from components with the [`push`] method on

39: use crate::sys::path::{is_sep_byte, is_verbatim_sep, parse_prefix, MAIN_SEP_STR};

65: /// Windows path prefixes, e.g., `C:` or `\\server\share`.

67: /// Windows uses a variety of path prefix styles, including references to drive

69: /// others. In addition, some path prefixes are "verbatim" (i.e., prefixed with

152: /// Determines whether the character is one of the permitted path

159: /// The primary separator of path components for the current platform.

162: pub const MAIN_SEPARATOR: char = crate::sys::path::MAIN_SEP;

210:     let path = if let Some(p) = prefix { &s[p.len()..] } else { s };

211:     !path.is_empty() && is_sep_byte(path[0])

242: /// front and back of the path each keep track of what parts of the path have

245: /// Going front to back, a path is made up of a prefix, a starting

255: /// A structure wrapping a Windows path prefix as well as its unparsed string

319: /// A single component of a path.

321: /// A `Component` roughly corresponds to a substring between path separators

325: /// created by the [`components`][`Path::components`] method on [`Path`].

330:     /// A Windows path prefix, e.g., `C:` or `\\server\share`.

342:     /// It represents a separator that designates that a path starts from root.

367:             Component::Normal(path) => path,

378: impl AsRef<Path> for Component<'_> {

379:     fn as_ref(&self) -> &Path {

384: /// An iterator over the [`Component`]s of a [`Path`].

386: /// This `struct` is created by the [`components`] method on [`Path`].

391:     // The path left to parse components from

397:     // true if path *physically* has a root separator; for most Windows

408: /// An iterator over the [`Component`]s of a [`Path`], as [`OsStr`] slices.

410: /// This `struct` is created by the [`iter`] method on [`Path`].

414: /// [`iter`]: struct.Path.html#method.iter

416: /// [`Path`]: struct.Path.html

424:         struct DebugHelper<'a>(&'a Path);

432:         f.debug_tuple("Components").field(&DebugHelper(self.as_path())).finish()

454:     // Given the iteration so far, how much of the pre-State::Body path is left?

473:     /// Extracts a slice corresponding to the portion of the path remaining for iteration.

483:         unsafe { Path::from_u8_slice(comps.path) }

486:     /// Is the *original* path rooted?

499:     /// Should the normalized path include a leading . ?

504:         let mut iter = self.path[self.prefix_len()..].iter();

512:     // parse a given byte sequence into the corresponding path component

517:             // the beginning of a path, which is treated

529:         let (extra, comp) = match self.path.iter().position(|b| self.is_sep_byte(*b)) {

530:             None => (0, self.path),

531:             Some(i) => (1, &self.path[..i]),

541:         let (extra, comp) = match self.path[start..].iter().rposition(|b| self.is_sep_byte(*b)) {

542:             None => (0, &self.path[start..]),

543:             Some(i) => (1, &self.path[start + i + 1..]),

550:         while !self.path.is_empty() {

555:                 self.path = &self.path[size..];

562:         while self.path.len() > self.len_before_body() {

567:                 self.path = &self.path[..self.path.len() - size];

573: impl AsRef<Path> for Components<'_> {

574:     fn as_ref(&self) -> &Path {

575:         self.as_path()

581:         self.as_path().as_os_str()

587:         struct DebugHelper<'a>(&'a Path);

595:         f.debug_tuple("Iter").field(&DebugHelper(self.as_path())).finish()

600:     /// Extracts a slice corresponding to the portion of the path remaining for iteration.

603:         self.inner.as_path()

607: impl AsRef<Path> for Iter<'_> {

608:     fn as_ref(&self) -> &Path {

609:         self.as_path()

615:         self.as_path().as_os_str()

643:                     debug_assert!(self.prefix_len() <= self.path.len());

644:                     let raw = &self.path[..self.prefix_len()];

645:                     self.path = &self.path[self.prefix_len()..];

657:                         debug_assert!(!self.path.is_empty());

658:                         self.path = &self.path[1..];

665:                         debug_assert!(!self.path.is_empty());

666:                         self.path = &self.path[1..];

670:                 State::Body if !self.path.is_empty() => {

672:                     self.path = &self.path[size..];

691:                 State::Body if self.path.len() > self.len_before_body() => {

693:                     self.path = &self.path[..self.path.len() - size];

704:                         self.path = &self.path[..self.path.len() - 1];

711:                         self.path = &self.path[..self.path.len() - 1];

718:                         raw: unsafe { u8_slice_as_os_str(self.path) },

755: /// An iterator over [`Path`] and its ancestors.

757: /// This `struct` is created by the [`ancestors`] method on [`Path`].

762:     next: Option<&'a Path>,

766:     type Item = &'a Path;

770:         self.next = next.and_then(Path::parent);

781: /// An owned, mutable path (akin to [`String`]).

784: /// the path in place. It also implements [`Deref`] to [`Path`], meaning that

785: /// all methods on [`Path`] slices are available on `PathBuf` values as well.

788: /// [`Path`]: struct.Path.html

819:     /// Coerces to a [`Path`] slice.

821:     /// [`Path`]: struct.Path.html

827:     /// Extends `self` with `path`.

829:     /// If `path` is absolute, it replaces the current path.

833:     /// * if `path` has a root but no prefix (e.g., `\windows`), it

835:     /// * if `path` has a prefix but no root, it replaces `self`.

837:     pub fn push<P: AsRef<Path>>(&mut self, path: P) {

838:         self._push(path.as_ref())

841:     fn _push(&mut self, path: &Path) {

849:                 && comps.prefix_len() == comps.path.len()

856:         // absolute `path` replaces `self`

857:         if path.is_absolute() || path.prefix().is_some() {

860:         // `path` has a root but no prefix, e.g., `\windows` (Windows only)

861:         } else if path.has_root() {

865:         // `path` is a pure relative path

870:         self.inner.push(path);

898:     /// `file_name`. The new path will be a sibling of the original path.

964:     /// Converts this `PathBuf` into a [boxed][`Box`] [`Path`].

967:     /// [`Path`]: struct.Path.html

969:         let rw = Box::into_raw(self.inner.into_boxed_os_str()) as *mut Path;

1022: impl From<&Path> for Box<Path> {

1023:     fn from(path: &Path) -> Box<Path> {

1024:         let boxed: Box<OsStr> = path.inner.into();

1025:         let rw = Box::into_raw(boxed) as *mut Path;

1031:     /// Converts a `Box<Path>` into a `PathBuf`

1034:     fn from(boxed: Box<Path>) -> PathBuf {

1035:         boxed.into_path_buf()

1039: impl From<PathBuf> for Box<Path> {

1040:     /// Converts a `PathBuf` into a `Box<Path>`

1044:     fn from(p: PathBuf) -> Box<Path> {

1045:         p.into_boxed_path()

1049: impl Clone for Box<Path> {

1052:         self.to_path_buf().into_boxed_path()

1076:     fn from(path_buf: PathBuf) -> OsString {

1077:         path_buf.inner

1119:     type Target = Path;

1121:     fn deref(&self) -> &Path {

1122:         Path::new(&self.inner)