Struct Path
struct Path { ... }
A slice of a path (akin to str).
This type supports a number of operations for inspecting a path, including
breaking the path into its components (separated by / on Unix and by either
/ or \ on Windows), extracting the file name, determining whether the path
is absolute, and so on.
This is an unsized type, meaning that it must always be used behind a
pointer like & or Box. For an owned version of this type,
see PathBuf.
More details about the overall approach can be found in the module documentation.
Examples
use Path;
use OsStr;
// Note: this example does work on Windows
let path = new;
let parent = path.parent;
assert_eq!;
let file_stem = path.file_stem;
assert_eq!;
let extension = path.extension;
assert_eq!;
Implementations
impl Path
const fn new<S: ~const AsRef<OsStr> + ?Sized>(s: &S) -> &PathDirectly wraps a string slice as a
Pathslice.This is a cost-free conversion.
Examples
use Path; new;You can create
Paths fromStrings, or even otherPaths:use Path; let string = Stringfrom; let from_string = new; let from_path = new; assert_eq!;fn as_os_str(self: &Self) -> &OsStrYields the underlying
OsStrslice.Examples
use Path; let os_str = new.as_os_str; assert_eq!;fn as_mut_os_str(self: &mut Self) -> &mut OsStrYields a mutable reference to the underlying
OsStrslice.Examples
use ; let mut path = from; assert_ne!; path.as_mut_os_str.make_ascii_lowercase; assert_eq!;fn to_str(self: &Self) -> Option<&str>Yields a
&strslice if thePathis valid unicode.This conversion may entail doing a check for UTF-8 validity. Note that validation is performed because non-UTF-8 strings are perfectly valid for some OS.
Examples
use Path; let path = new; assert_eq!;fn to_string_lossy(self: &Self) -> Cow<'_, str>Converts a
Pathto a [Cow<str>].Any non-UTF-8 sequences are replaced with
U+FFFD REPLACEMENT CHARACTER.Examples
Calling
to_string_lossyon aPathwith valid unicode:use Path; let path = new; assert_eq!;Had
pathcontained invalid unicode, theto_string_lossycall might have returned"fo�.txt".fn to_path_buf(self: &Self) -> PathBufConverts a
Pathto an ownedPathBuf.Examples
use ; let path_buf = new.to_path_buf; assert_eq!;fn is_absolute(self: &Self) -> boolReturns
trueif thePathis absolute, i.e., if it is independent of the current directory.-
On Unix, a path is absolute if it starts with the root, so
is_absoluteandhas_rootare equivalent. -
On Windows, a path is absolute if it has a prefix and starts with the root:
c:\windowsis absolute, whilec:tempand\tempare not.
Examples
use Path; assert!;-
fn is_relative(self: &Self) -> boolReturns
trueif thePathis relative, i.e., not absolute.See
is_absolute's documentation for more details.Examples
use Path; assert!;fn has_root(self: &Self) -> boolReturns
trueif thePathhas a root.-
On Unix, a path has a root if it begins with
/. -
On Windows, a path has a root if it:
- has no prefix and begins with a separator, e.g.,
\windows - has a prefix followed by a separator, e.g.,
c:\windowsbut notc:windows - has any non-disk prefix, e.g.,
\\server\share
- has no prefix and begins with a separator, e.g.,
Examples
use Path; assert!;-
fn parent(self: &Self) -> Option<&Path>Returns the
Pathwithout its final component, if there is one.This means it returns
Some("")for relative paths with one component.Returns
Noneif the path terminates in a root or prefix, or if it's the empty string.Examples
use Path; let path = new; let parent = path.parent.unwrap; assert_eq!; let grand_parent = parent.parent.unwrap; assert_eq!; assert_eq!; let relative_path = new; let parent = relative_path.parent; assert_eq!; let grand_parent = parent.and_then; assert_eq!; let great_grand_parent = grand_parent.and_then; assert_eq!;fn ancestors(self: &Self) -> Ancestors<'_>Produces an iterator over
Pathand its ancestors.The iterator will yield the
Paththat is returned if theparentmethod is used zero or more times. If theparentmethod returnsNone, the iterator will do likewise. The iterator will always yield at least one value, namelySome(&self). Next it will yield&self.parent(),&self.parent().and_then(Path::parent)and so on.Examples
use Path; let mut ancestors = new.ancestors; assert_eq!; assert_eq!; assert_eq!; assert_eq!; let mut ancestors = new.ancestors; assert_eq!; assert_eq!; assert_eq!; assert_eq!; assert_eq!;fn file_name(self: &Self) -> Option<&OsStr>Returns the final component of the
Path, if there is one.If the path is a normal file, this is the file name. If it's the path of a directory, this is the directory name.
Returns
Noneif the path terminates in...Examples
use Path; use OsStr; assert_eq!; assert_eq!; assert_eq!; assert_eq!; assert_eq!; assert_eq!;fn strip_prefix<P>(self: &Self, base: P) -> Result<&Path, StripPrefixError> where P: AsRef<Path>Returns a path that, when joined onto
base, yieldsself.Errors
If
baseis not a prefix ofself(i.e.,starts_withreturnsfalse), returnsErr.Examples
use ; let path = new; assert_eq!; assert_eq!; assert_eq!; assert_eq!; assert_eq!; assert!; assert!; assert!; let prefix = from; assert_eq!;fn starts_with<P: AsRef<Path>>(self: &Self, base: P) -> boolDetermines whether
baseis a prefix ofself.Only considers whole path components to match.
Examples
use Path; let path = new; assert!; assert!; assert!; assert!; // extra slash is okay assert!; // multiple extra slashes are okay assert!; assert!; assert!;fn ends_with<P: AsRef<Path>>(self: &Self, child: P) -> boolDetermines whether
childis a suffix ofself.Only considers whole path components to match.
Examples
use Path; let path = new; assert!; assert!; assert!; assert!; assert!; // use .extension() insteadfn is_empty(self: &Self) -> boolChecks whether the
Pathis empty.Examples
use Path; let path = new; assert!; let path = new; assert!; let path = new; assert!;fn file_stem(self: &Self) -> Option<&OsStr>Extracts the stem (non-extension) portion of
self.file_name.The stem is:
None, if there is no file name;- The entire file name if there is no embedded
.; - The entire file name if the file name begins with
.and has no other.s within; - Otherwise, the portion of the file name before the final
.
Examples
use Path; assert_eq!; assert_eq!;See Also
This method is similar to
Path::file_prefix, which extracts the portion of the file name before the first.fn file_prefix(self: &Self) -> Option<&OsStr>Extracts the prefix of
self.file_name.The prefix is:
None, if there is no file name;- The entire file name if there is no embedded
.; - The portion of the file name before the first non-beginning
.; - The entire file name if the file name begins with
.and has no other.s within; - The portion of the file name before the second
.if the file name begins with.
Examples
use Path; assert_eq!; assert_eq!; assert_eq!; assert_eq!;See Also
This method is similar to
Path::file_stem, which extracts the portion of the file name before the last.fn extension(self: &Self) -> Option<&OsStr>Extracts the extension (without the leading dot) of
self.file_name, if possible.The extension is:
None, if there is no file name;None, if there is no embedded.;None, if the file name begins with.and has no other.s within;- Otherwise, the portion of the file name after the final
.
Examples
use Path; assert_eq!; assert_eq!;fn has_trailing_sep(self: &Self) -> boolChecks whether the path ends in a trailing separator.
This is generally done to ensure that a path is treated as a directory, not a file, although it does not actually guarantee that such a path is a directory on the underlying file system.
Despite this behavior, two paths are still considered the same in Rust whether they have a trailing separator or not.
Examples
use Path; assert!; assert!;fn with_trailing_sep(self: &Self) -> Cow<'_, Path>Ensures that a path has a trailing separator, allocating a
PathBufif necessary.The resulting path will return true for
has_trailing_sep.Examples
use OsStr; use Path; assert_eq!; assert_eq!; assert!; assert!;fn trim_trailing_sep(self: &Self) -> &PathTrims a trailing separator from a path, if possible.
The resulting path will return false for
has_trailing_sepfor most paths.Some paths, like
/, cannot be trimmed in this way.Examples
use OsStr; use Path; assert_eq!; assert_eq!; assert_eq!; assert_eq!; assert_eq!;fn join<P: AsRef<Path>>(self: &Self, path: P) -> PathBufCreates an owned
PathBufwithpathadjoined toself.If
pathis absolute, it replaces the current path.On Windows:
- if
pathhas a root but no prefix (e.g.,\windows), it replaces and returns everything except for the prefix (if any) ofself. - if
pathhas a prefix but no root,selfis ignored andpathis returned. - if
selfhas a verbatim prefix (e.g.\\?\C:\windows) andpathis not empty, the new path is normalized: all references to.and..are removed.
See
PathBuf::pushfor more details on what it means to adjoin a path.Examples
use ; assert_eq!; assert_eq!;- if
fn with_file_name<S: AsRef<OsStr>>(self: &Self, file_name: S) -> PathBufCreates an owned
PathBuflikeselfbut with the given file name.See
PathBuf::set_file_namefor more details.Examples
use ; let path = new; assert_eq!; assert_eq!; let path = new; assert_eq!;fn with_extension<S: AsRef<OsStr>>(self: &Self, extension: S) -> PathBufCreates an owned
PathBuflikeselfbut with the given extension.See
PathBuf::set_extensionfor more details.Examples
use Path; let path = new; assert_eq!; assert_eq!;Handling multiple extensions:
use Path; let path = new; assert_eq!; assert_eq!;Adding an extension where one did not exist:
use Path; let path = new; assert_eq!;fn with_added_extension<S: AsRef<OsStr>>(self: &Self, extension: S) -> PathBufCreates an owned
PathBuflikeselfbut with the extension added.See
PathBuf::add_extensionfor more details.Examples
use ; let path = new; assert_eq!; let path = new; assert_eq!; assert_eq!; assert_eq!;fn components(self: &Self) -> Components<'_>Produces an iterator over the
Components of the path.When parsing the path, there is a small amount of normalization:
-
Repeated separators are ignored, so
a/banda//bboth haveaandbas components. -
Occurrences of
.are normalized away, except if they are at the beginning of the path. For example,a/./b,a/b/,a/b/.anda/ball haveaandbas components, but./a/bstarts with an additionalCurDircomponent. -
Trailing separators are normalized away, so
/a/band/a/b/are equivalent.
Note that no other normalization takes place; in particular,
a/canda/b/../care distinct, to account for the possibility thatbis a symbolic link (so its parent isn'ta).Examples
use ; use OsStr; let mut components = new.components; assert_eq!; assert_eq!; assert_eq!; assert_eq!-
fn iter(self: &Self) -> Iter<'_>Produces an iterator over the path's components viewed as
OsStrslices.For more information about the particulars of how the path is separated into components, see
components.Examples
use ; use OsStr; let mut it = new.iter; assert_eq!; assert_eq!; assert_eq!; assert_eq!fn display(self: &Self) -> Display<'_>Returns an object that implements
Displayfor safely printing paths that may contain non-Unicode data. This may perform lossy conversion, depending on the platform. If you would like an implementation which escapes the path please useDebuginstead.Examples
use Path; let path = new; println!;const fn as_path(self: &Self) -> &PathReturns the same path as
&Path.This method is redundant when used directly on
&Path, but it helps dereferencing otherPathBuf-like types toPaths, for example references toBox<Path>orArc<Path>.fn metadata(self: &Self) -> io::Result<fs::Metadata>Queries the file system to get information about a file, directory, etc.
This function will traverse symbolic links to query information about the destination file.
This is an alias to
fs::metadata.Examples
use std::path::Path; let path = Path::new("/Minas/tirith"); let metadata = path.metadata().expect("metadata call failed"); println!("{:?}", metadata.file_type());fn symlink_metadata(self: &Self) -> io::Result<fs::Metadata>Queries the metadata about a file without following symlinks.
This is an alias to
fs::symlink_metadata.Examples
use std::path::Path; let path = Path::new("/Minas/tirith"); let metadata = path.symlink_metadata().expect("symlink_metadata call failed"); println!("{:?}", metadata.file_type());fn canonicalize(self: &Self) -> io::Result<PathBuf>Returns the canonical, absolute form of the path with all intermediate components normalized and symbolic links resolved.
This is an alias to
fs::canonicalize.Errors
This method will return an error in the following situations, but is not limited to just these cases:
pathdoes not exist.- A non-final component in path is not a directory.
Examples
use std::path::{Path, PathBuf}; let path = Path::new("/foo/test/../test/bar.rs"); assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs"));fn normalize_lexically(self: &Self) -> Result<PathBuf, NormalizeError>Normalize a path, including
..without traversing the filesystem.Returns an error if normalization would leave leading
..components.This function always resolves
..to the "lexical" parent. That is "a/b/../c" will always resolve toa/cwhich can change the meaning of the path. In particular,a/canda/b/../care distinct on many systems becausebmay be a symbolic link, so its parent isn'ta.path::absoluteis an alternative that preserves... OrPath::canonicalizecan be used to resolve any..by querying the filesystem.fn read_link(self: &Self) -> io::Result<PathBuf>Reads a symbolic link, returning the file that the link points to.
This is an alias to
fs::read_link.Examples
use std::path::Path; let path = Path::new("/laputa/sky_castle.rs"); let path_link = path.read_link().expect("read_link call failed");fn read_dir(self: &Self) -> io::Result<fs::ReadDir>Returns an iterator over the entries within a directory.
The iterator will yield instances of
[io::Result]<[fs::DirEntry]>. New errors may be encountered after an iterator is initially constructed.This is an alias to
fs::read_dir.Examples
use std::path::Path; let path = Path::new("/laputa"); for entry in path.read_dir().expect("read_dir call failed") { if let Ok(entry) = entry { println!("{:?}", entry.path()); } }fn exists(self: &Self) -> boolReturns
trueif the path points at an existing entity.Warning: this method may be error-prone, consider using
try_exists()instead! It also has a risk of introducing time-of-check to time-of-use (TOCTOU) bugs.This function will traverse symbolic links to query information about the destination file.
If you cannot access the metadata of the file, e.g. because of a permission error or broken symbolic links, this will return
false.Examples
use std::path::Path; assert!(!Path::new("does_not_exist.txt").exists());See Also
This is a convenience function that coerces errors to false. If you want to check errors, call
Path::try_exists.fn try_exists(self: &Self) -> io::Result<bool>Returns
Ok(true)if the path points at an existing entity.This function will traverse symbolic links to query information about the destination file. In case of broken symbolic links this will return
Ok(false).[
Path::exists()] only checks whether or not a path was both found and readable. By contrast,try_existswill returnOk(true)orOk(false), respectively, if the path was verified to exist or not exist. If its existence can neither be confirmed nor denied, it will propagate anErr(_)instead. This can be the case if e.g. listing permission is denied on one of the parent directories.Note that while this avoids some pitfalls of the
exists()method, it still can not prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios where those bugs are not an issue.This is an alias for
std::fs::exists.Examples
use std::path::Path; assert!(!Path::new("does_not_exist.txt").try_exists().expect("Can't check existence of file does_not_exist.txt")); assert!(Path::new("/root/secret_file.txt").try_exists().is_err());fn is_file(self: &Self) -> boolReturns
trueif the path exists on disk and is pointing at a regular file.This function will traverse symbolic links to query information about the destination file.
If you cannot access the metadata of the file, e.g. because of a permission error or broken symbolic links, this will return
false.Examples
use std::path::Path; assert_eq!(Path::new("./is_a_directory/").is_file(), false); assert_eq!(Path::new("a_file.txt").is_file(), true);See Also
This is a convenience function that coerces errors to false. If you want to check errors, call
fs::metadataand handle itsResult. Then callfs::Metadata::is_fileif it wasOk.When the goal is simply to read from (or write to) the source, the most reliable way to test the source can be read (or written to) is to open it. Only using
is_filecan break workflows likediff <( prog_a )on a Unix-like system for example. Seefs::File::openorfs::OpenOptions::openfor more information.fn is_dir(self: &Self) -> boolReturns
trueif the path exists on disk and is pointing at a directory.This function will traverse symbolic links to query information about the destination file.
If you cannot access the metadata of the file, e.g. because of a permission error or broken symbolic links, this will return
false.Examples
use std::path::Path; assert_eq!(Path::new("./is_a_directory/").is_dir(), true); assert_eq!(Path::new("a_file.txt").is_dir(), false);See Also
This is a convenience function that coerces errors to false. If you want to check errors, call
fs::metadataand handle itsResult. Then callfs::Metadata::is_dirif it wasOk.fn is_symlink(self: &Self) -> boolReturns
trueif the path exists on disk and is pointing at a symbolic link.This function will not traverse symbolic links. In case of a broken symbolic link this will also return true.
If you cannot access the directory containing the file, e.g., because of a permission error, this will return false.
Examples
#See Also
This is a convenience function that coerces errors to false. If you want to check errors, call
fs::symlink_metadataand handle itsResult. Then callfs::Metadata::is_symlinkif it wasOk.fn into_path_buf(self: Box<Self>) -> PathBufConverts a
Box<Path>into aPathBufwithout copying or allocating.
impl AsRef for Path
fn as_ref(self: &Self) -> &Path
impl AsRef for Path
fn as_ref(self: &Self) -> &OsStr
impl CloneToUninit for Path
unsafe fn clone_to_uninit(self: &Self, dst: *mut u8)
impl Debug for Path
fn fmt(self: &Self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result
impl Eq for Path
impl Freeze for Path
impl Hash for Path
fn hash<H: Hasher>(self: &Self, h: &mut H)
impl Ord for Path
fn cmp(self: &Self, other: &Path) -> cmp::Ordering
impl PartialEq for Path
fn eq(self: &Self, other: &OsString) -> bool
impl PartialEq for Path
fn eq(self: &Self, other: &str) -> bool
impl PartialEq for Path
fn eq(self: &Self, other: &OsStr) -> bool
impl PartialEq for Path
fn eq(self: &Self, other: &String) -> bool
impl PartialEq for Path
fn eq(self: &Self, other: &PathBuf) -> bool
impl PartialEq for Path
fn eq(self: &Self, other: &Path) -> bool
impl PartialOrd for Path
fn partial_cmp(self: &Self, other: &OsString) -> Option<cmp::Ordering>
impl PartialOrd for Path
fn partial_cmp(self: &Self, other: &OsStr) -> Option<cmp::Ordering>
impl PartialOrd for Path
fn partial_cmp(self: &Self, other: &Path) -> Option<cmp::Ordering>
impl PartialOrd for Path
fn partial_cmp(self: &Self, other: &PathBuf) -> Option<cmp::Ordering>
impl RefUnwindSafe for Path
impl Send for Path
impl Sized for Path
impl Sync for Path
impl ToOwned for Path
fn to_owned(self: &Self) -> PathBuffn clone_into(self: &Self, target: &mut PathBuf)
impl Unpin for Path
impl UnwindSafe for Path
impl<'a> PartialEq for Path
fn eq(self: &Self, other: &Cow<'a, Path>) -> bool
impl<'a> PartialEq for Path
fn eq(self: &Self, other: &Cow<'a, OsStr>) -> bool
impl<'a> PartialEq for Path
fn eq(self: &Self, other: &&'a OsStr) -> bool
impl<'a> PartialOrd for Path
fn partial_cmp(self: &Self, other: &&'a OsStr) -> Option<cmp::Ordering>
impl<'a> PartialOrd for Path
fn partial_cmp(self: &Self, other: &Cow<'a, Path>) -> Option<cmp::Ordering>
impl<'a> PartialOrd for Path
fn partial_cmp(self: &Self, other: &Cow<'a, OsStr>) -> Option<cmp::Ordering>
impl<T> Any for Path
fn type_id(self: &Self) -> TypeId
impl<T> Borrow for Path
fn borrow(self: &Self) -> &T
impl<T> BorrowMut for Path
fn borrow_mut(self: &mut Self) -> &mut T