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())

581:     path: &'a [u8],

1747: impl ToOwned for Path {

1834: pub struct Path {

1847: impl Path {

2739: impl AsRef<OsStr> for Path {

2746: impl fmt::Debug for Path {

2773:     path: &'a Path,

2788: impl cmp::PartialEq for Path {

2795: impl Hash for Path {

2845: impl cmp::Eq for Path {}

2847: impl cmp::PartialOrd for Path {

2854: impl cmp::Ord for Path {

2861: impl AsRef<Path> for Path {

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

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

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

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

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

1123: pub struct PathBuf {

1127: impl PathBuf {

1506: impl Clone for PathBuf {

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

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

1580: impl From<OsString> for PathBuf {

1600: impl From<String> for PathBuf {

1610: impl FromStr for PathBuf {

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

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

1638: impl fmt::Debug for PathBuf {

1644: impl ops::Deref for PathBuf {

1652: impl Borrow<Path> for PathBuf {

1659: impl Default for PathBuf {

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

1759: impl cmp::PartialEq for PathBuf {

1766: impl Hash for PathBuf {

1772: impl cmp::Eq for PathBuf {}

1774: impl cmp::PartialOrd for PathBuf {

1781: impl cmp::Ord for PathBuf {

1788: impl AsRef<OsStr> for PathBuf {

2903: impl AsRef<Path> for PathBuf {

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

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

2732:     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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

254: /// use std::path;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

527:     /// use std::path::Path;

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

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

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

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

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

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

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

567: /// use std::path::Path;

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

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

576: /// [`components`]: Path::components

580:     // The path left to parse components from

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

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

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

602: /// [`iter`]: Path::iter

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

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

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

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

665:     /// use std::path::Path;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

775:         self.as_path()

782:         self.as_path().as_os_str()

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

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

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

806:     /// use std::path::Path;

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

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

817:         self.inner.as_path()

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

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

824:         self.as_path()

831:         self.as_path().as_os_str()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

996:     // Fast path for long shared prefixes

1001:     //   otherwise do it on the full path

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

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

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

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

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

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

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

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

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

1035: /// use std::path::Path;

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

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

1044: /// [`ancestors`]: Path::ancestors

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

1052:     type Item = &'a Path;

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

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

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

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

1086: /// use std::path::PathBuf;

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

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

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

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

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

1101: /// use std::path::PathBuf;

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

1110: /// use std::path::PathBuf;

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

1138:     /// use std::path::PathBuf;

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

1154:     /// use std::path::PathBuf;

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

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

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

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

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

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

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

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

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

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

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

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

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

1207:     /// use std::path::PathBuf;

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

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

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

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

1217:     /// use std::path::PathBuf;

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

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

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

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

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

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

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

1241:         // absolute `path` replaces `self`

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

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

1248:             for c in path.components() {

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

1286:         } else if path.has_root() {

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

1295:         self.inner.push(path);

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

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

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

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

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

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

1342:     /// use std::path::PathBuf;

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

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

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

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

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

1420:     /// use std::path::PathBuf;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1548:         boxed.into_path_buf()

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

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

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

1559:         p.into_boxed_path()

1563: impl Clone for Box<Path> {

1566:         self.to_path_buf().into_boxed_path()

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

1596:         path_buf.inner

1645:     type Target = Path;

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

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

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

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

1668:     /// [`Path`].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1751:         self.to_path_buf()

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

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

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

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

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

1812: /// use std::path::Path;

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

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

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

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

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

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

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

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

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

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

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

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

1843: /// [`strip_prefix`]: Path::strip_prefix

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

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

1851:         Path::new(u8_slice_as_os_str(s))

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

1865:     /// use std::path::Path;

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

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

1873:     /// use std::path::Path;

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

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

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

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

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

1889:     /// use std::path::Path;

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

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

1911:     /// use std::path::Path;

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

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

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

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

1935:     /// use std::path::Path;

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

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

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

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

1955:     /// use std::path::Path;

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

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

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

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

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

1979:     /// use std::path::Path;

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

1984:     /// [`has_root`]: Path::has_root

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

1998:     /// use std::path::Path;

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

2003:     /// [`is_absolute`]: Path::is_absolute

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

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

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

2026:     /// use std::path::Path;

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

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

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

2043:     /// use std::path::Path;

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

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

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

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

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

2059:                 Some(comps.as_path())

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

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

2076:     /// use std::path::Path;

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

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

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

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

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

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

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

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

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

2092:     /// [`parent`]: Path::parent

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

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

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

2108:     /// use std::path::Path;

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

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

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

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

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

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

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

2133:     /// [`starts_with`]: Path::starts_with

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

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

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

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

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

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

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

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

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

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

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

2156:         P: AsRef<Path>,

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

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

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

2174:     /// use std::path::Path;

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

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

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

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

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

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

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

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

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

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

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

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

2205:     /// use std::path::Path;

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

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

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

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

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

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

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

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

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

2239:     /// use std::path::Path;

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

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

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

2249:     /// [`Path::file_prefix`]: Path::file_prefix

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

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

2272:     /// use std::path::Path;

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

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

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

2282:     /// [`Path::file_stem`]: Path::file_stem

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

2303:     /// use std::path::Path;

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

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

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

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

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

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

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

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

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

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

2331:         buf.push(path);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2424:             path: self.as_u8_slice(),

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

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

2438:     /// [`components`]: Path::components

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

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

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

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

2467:     /// use std::path::Path;

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

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

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

2477:         Display { path: self }

2490:     /// use std::path::Path;

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

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

2509:     /// use std::path::Path;

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

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

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

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

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

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

2547:     /// use std::path::Path;

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

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

2568:     /// use std::path::Path;

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

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

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

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

2594:     /// use std::path::Path;

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

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

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

2621:     /// #![feature(path_try_exists)]

2623:     /// use std::path::Path;

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

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

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

2648:     /// use std::path::Path;

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

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

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

2681:     /// use std::path::Path;

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

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

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

2709:     /// use std::path::Path;

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

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

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

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

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

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

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

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

2763: /// use std::path::Path;

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

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

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

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

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

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

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

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

2868: impl AsRef<Path> for OsStr {

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

2871:         Path::new(self)

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

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

2878:         Path::new(self)

2882: impl AsRef<Path> for OsString {

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

2885:         Path::new(self)

2889: impl AsRef<Path> for str {

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

2892:         Path::new(self)

2896: impl AsRef<Path> for String {

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

2899:         Path::new(self)

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

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

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

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

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

2960: impl_cmp!(PathBuf, Path);

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

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

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

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

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

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

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

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

3002: impl_cmp_os_str!(Path, OsStr);

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

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

3005: impl_cmp_os_str!(Path, OsString);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3095:     _absolute(path)

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

3099:     let path = path.as_ref();

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

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

3103:         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

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

1074: /// [`push`]: PathBuf::push

1075: /// [`set_extension`]: PathBuf::set_extension

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

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

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

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

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

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

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

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

1144:     pub fn new() -> PathBuf {

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

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

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

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

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

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

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

1337:     /// [`pop`]: PathBuf::pop

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

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

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

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

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

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

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

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

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

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

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

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

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

1586:         PathBuf { inner: s }

1590: impl From<PathBuf> for OsString {

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

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

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

1606:         PathBuf::from(OsString::from(s))

1615:         Ok(PathBuf::from(s))

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

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

1662:         PathBuf::new()

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

1690:     /// [`PathBuf`].

1748:     type Owned = PathBuf;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2998: impl_cmp_os_str!(PathBuf, OsStr);

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

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

3001: impl_cmp_os_str!(PathBuf, OsString);

3040: /// ## Posix paths

3065: /// ## 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)