# Struct std::path::Path [−] [src]

    pub struct Path {
        // some fields omitted
    }

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 `/` or `\`, depending on the platform), extracting the file name, determining whether the path is absolute, and so on. More details about the overall approach can be found in the module documentation.

This is an unsized type, meaning that it must always be used behind a pointer like `&` or `Box`.

# Examples

fn main() { use std::path::Path; let path = Path::new("/tmp/foo/bar.txt"); let file = path.file_name(); let extension = path.extension(); let parent_dir = path.parent(); }

    use std::path::Path;

    let path = Path::new("/tmp/foo/bar.txt");
    let file = path.file_name();
    let extension = path.extension();
    let parent_dir = path.parent();

## Methods

### `impl Path`

#### `fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &Path`

Directly wrap a string slice as a `Path` slice.

This is a cost-free conversion.

# Examples

fn main() { use std::path::Path; Path::new("foo.txt"); }

    use std::path::Path;

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

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

fn main() { use std::path::Path; let string = String::from("foo.txt"); let from_string = Path::new(&string); let from_path = Path::new(&from_string); assert_eq!(from_string, from_path); }

    use std::path::Path;

    let string = String::from("foo.txt");
    let from_string = Path::new(&string);
    let from_path = Path::new(&from_string);
    assert_eq!(from_string, from_path);

#### `fn as_os_str(&self) -> &OsStr`

Yields the underlying `OsStr` slice.

# Examples

fn main() { use std::path::Path; let os_str = Path::new("foo.txt").as_os_str(); assert_eq!(os_str, std::ffi::OsStr::new("foo.txt")); }

    use std::path::Path;

    let os_str = Path::new("foo.txt").as_os_str();
    assert_eq!(os_str, std::ffi::OsStr::new("foo.txt"));

#### `fn to_str(&self) -> Option<&str>`

Yields a `&str` slice if the `Path` is valid unicode.

This conversion may entail doing a check for UTF-8 validity.

# Examples

fn main() { use std::path::Path; let path_str = Path::new("foo.txt").to_str(); assert_eq!(path_str, Some("foo.txt")); }

    use std::path::Path;

    let path_str = Path::new("foo.txt").to_str();
    assert_eq!(path_str, Some("foo.txt"));

#### `fn to_string_lossy(&self) -> Cow<str>`

Converts a `Path` to a `Cow<str>`.

Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.

# Examples

fn main() { use std::path::Path; let path_str = Path::new("foo.txt").to_string_lossy(); assert_eq!(path_str, "foo.txt"); }

    use std::path::Path;

    let path_str = Path::new("foo.txt").to_string_lossy();
    assert_eq!(path_str, "foo.txt");

#### `fn to_path_buf(&self) -> PathBuf`

Converts a `Path` to an owned `PathBuf`.

# Examples

fn main() { use std::path::Path; let path_buf = Path::new("foo.txt").to_path_buf(); assert_eq!(path_buf, std::path::PathBuf::from("foo.txt")); }

    use std::path::Path;

    let path_buf = Path::new("foo.txt").to_path_buf();
    assert_eq!(path_buf, std::path::PathBuf::from("foo.txt"));

#### `fn is_absolute(&self) -> bool`

A path is absolute if it is independent of the current directory.

- On Unix, a path is absolute if it starts with the root, so `is_absolute` and `has_root` are equivalent.

- On Windows, a path is absolute if it has a prefix and starts with the root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. In other words, `path.is_absolute() == path.prefix().is_some() && path.has_root()`.

# Examples

fn main() { use std::path::Path; assert!(!Path::new("foo.txt").is_absolute()); }

    use std::path::Path;

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

#### `fn is_relative(&self) -> bool`

A path is relative if it is not absolute.

# Examples

fn main() { use std::path::Path; assert!(Path::new("foo.txt").is_relative()); }

    use std::path::Path;

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

#### `fn prefix(&self) -> Option<Prefix>`

Deprecated since 1.7.0

: inspect components().next() instead

Returns the prefix of a path, if any.

Prefixes are relevant only for Windows paths, and consist of volumes like `C:`, UNC prefixes like `\\server`, and others described in more detail in `std::os::windows::PathExt`.

#### `fn has_root(&self) -> bool`

A path has a root if the body of the path begins with the directory separator.

- 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:\windows` but not `c:windows`
  - has any non-disk prefix, e.g. `\\server\share`

# Examples

fn main() { use std::path::Path; assert!(Path::new("/etc/passwd").has_root()); }

    use std::path::Path;

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

#### `fn parent(&self) -> Option<&Path>`

The path without its final component, if any.

Returns `None` if the path terminates in a root or prefix.

# Examples

fn main() { use std::path::Path; let path = Path::new("/foo/bar"); let parent = path.parent().unwrap(); assert_eq!(parent, Path::new("/foo")); let grand_parent = parent.parent().unwrap(); assert_eq!(grand_parent, Path::new("/")); assert_eq!(grand_parent.parent(), None); }

    use std::path::Path;

    let path = Path::new("/foo/bar");
    let parent = path.parent().unwrap();
    assert_eq!(parent, Path::new("/foo"));

    let grand_parent = parent.parent().unwrap();
    assert_eq!(grand_parent, Path::new("/"));
    assert_eq!(grand_parent.parent(), None);

#### `fn file_name(&self) -> Option<&OsStr>`

The final component of the path, if it is a normal file.

If the path terminates in `.`, `..`, or consists solely of a root of prefix, `file_name` will return `None`.

# Examples

fn main() { use std::path::Path; use std::ffi::OsStr; let path = Path::new("foo.txt"); let os_str = OsStr::new("foo.txt"); assert_eq!(Some(os_str), path.file_name()); }

    use std::path::Path;
    use std::ffi::OsStr;

    let path = Path::new("foo.txt");
    let os_str = OsStr::new("foo.txt");

    assert_eq!(Some(os_str), path.file_name());

#### `fn relative_from<'a, P: ?Sized + AsRef<Path>>(&'a self, base: &'a P) -> Option<&Path>`

Deprecated since 1.7.0

: renamed to strip_prefix

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

If `base` is not a prefix of `self` (i.e. `starts_with` returns false), then `relative_from` returns `None`.

#### `fn strip_prefix<'a, P: ?Sized>(&'a self, base: &'a P) -> Result<&'a Path, StripPrefixError> where P: AsRef<Path>`

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

If `base` is not a prefix of `self` (i.e. `starts_with` returns false), then `relative_from` returns `None`.

#### `fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool`

Determines whether `base` is a prefix of `self`.

Only considers whole path components to match.

# Examples

fn main() { use std::path::Path; let path = Path::new("/etc/passwd"); assert!(path.starts_with("/etc")); assert!(!path.starts_with("/e")); }

    use std::path::Path;

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

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

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

#### `fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool`

Determines whether `child` is a suffix of `self`.

Only considers whole path components to match.

# Examples

fn main() { use std::path::Path; let path = Path::new("/etc/passwd"); assert!(path.ends_with("passwd")); }

    use std::path::Path;

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

    assert!(path.ends_with("passwd"));

#### `fn file_stem(&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

fn main() { use std::path::Path; let path = Path::new("foo.rs"); assert_eq!("foo", path.file_stem().unwrap()); }

    use std::path::Path;

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

    assert_eq!("foo", path.file_stem().unwrap());

#### `fn extension(&self) -> Option<&OsStr>`

Extracts the extension 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

fn main() { use std::path::Path; let path = Path::new("foo.rs"); assert_eq!("rs", path.extension().unwrap()); }

    use std::path::Path;

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

    assert_eq!("rs", path.extension().unwrap());

#### `fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf`

Creates an owned `PathBuf` with `path` adjoined to `self`.

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

# Examples

fn main() { use std::path::{Path, PathBuf}; assert_eq!(Path::new("/etc").join("passwd"), PathBuf::from("/etc/passwd")); }

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

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

#### `fn with_file_name<S: AsRef<OsStr>>(&self, file_name: S) -> PathBuf`

Creates an owned `PathBuf` like `self` but with the given file name.

See `PathBuf::set_file_name` for more details.

# Examples

fn main() { use std::path::{Path, PathBuf}; let path = Path::new("/tmp/foo.txt"); assert_eq!(path.with_file_name("bar.txt"), PathBuf::from("/tmp/bar.txt")); }

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

    let path = Path::new("/tmp/foo.txt");
    assert_eq!(path.with_file_name("bar.txt"), PathBuf::from("/tmp/bar.txt"));

#### `fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf`

Creates an owned `PathBuf` like `self` but with the given extension.

See `PathBuf::set_extension` for more details.

# Examples

fn main() { use std::path::{Path, PathBuf}; let path = Path::new("foo.rs"); assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt")); }

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

    let path = Path::new("foo.rs");
    assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt"));

#### `fn components(&self) -> Components`

Produce an iterator over the components of the path.

# Examples

fn main() { use std::path::{Path, Component}; use std::ffi::OsStr; let mut components = Path::new("/tmp/foo.txt").components(); assert_eq!(components.next(), Some(Component::RootDir)); assert_eq!(components.next(), Some(Component::Normal(OsStr::new("tmp")))); assert_eq!(components.next(), Some(Component::Normal(OsStr::new("foo.txt")))); assert_eq!(components.next(), None) }

    use std::path::{Path, Component};
    use std::ffi::OsStr;

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

    assert_eq!(components.next(), Some(Component::RootDir));
    assert_eq!(components.next(), Some(Component::Normal(OsStr::new("tmp"))));
    assert_eq!(components.next(), Some(Component::Normal(OsStr::new("foo.txt"))));
    assert_eq!(components.next(), None)

#### `fn iter(&self) -> Iter`

Produce an iterator over the path's components viewed as `OsStr` slices.

# Examples

fn main() { use std::path::{self, Path}; use std::ffi::OsStr; let mut it = Path::new("/tmp/foo.txt").iter(); assert_eq!(it.next(), Some(OsStr::new(&path::MAIN_SEPARATOR.to_string()))); assert_eq!(it.next(), Some(OsStr::new("tmp"))); assert_eq!(it.next(), Some(OsStr::new("foo.txt"))); assert_eq!(it.next(), None) }

    use std::path::{self, Path};
    use std::ffi::OsStr;

    let mut it = Path::new("/tmp/foo.txt").iter();
    assert_eq!(it.next(), Some(OsStr::new(&path::MAIN_SEPARATOR.to_string())));
    assert_eq!(it.next(), Some(OsStr::new("tmp")));
    assert_eq!(it.next(), Some(OsStr::new("foo.txt")));
    assert_eq!(it.next(), None)

#### `fn display(&self) -> Display`

Returns an object that implements `Display` for safely printing paths that may contain non-Unicode data.

# Examples

fn main() { use std::path::Path; let path = Path::new("/tmp/foo.rs"); println!("{}", path.display()); }

    use std::path::Path;

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

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

#### `fn metadata(&self) -> Result<Metadata>`

Gets information on the file, directory, etc at this path.

Consult the `fs::metadata` documentation for more info.

This call preserves identical runtime/error semantics with `fs::metadata`.

#### `fn symlink_metadata(&self) -> Result<Metadata>`

Gets information on the file, directory, etc at this path.

Consult the `fs::symlink_metadata` documentation for more info.

This call preserves identical runtime/error semantics with `fs::symlink_metadata`.

#### `fn canonicalize(&self) -> Result<PathBuf>`

Returns the canonical form of a path, normalizing all components and eliminate all symlinks.

This call preserves identical runtime/error semantics with `fs::canonicalize`.

#### `fn read_link(&self) -> Result<PathBuf>`

Reads the symlink at this path.

For more information see `fs::read_link`.

#### `fn read_dir(&self) -> Result<ReadDir>`

Reads the directory at this path.

For more information see `fs::read_dir`.

#### `fn exists(&self) -> bool`

Boolean value indicator whether the underlying file exists on the local filesystem. Returns false in exactly the cases where `fs::metadata` fails.

#### `fn is_file(&self) -> bool`

Whether the underlying implementation (be it a file path, or something else) points at a "regular file" on the FS. Will return false for paths to non-existent locations or directories or other non-regular files (named pipes, etc). Follows links when making this determination.

#### `fn is_dir(&self) -> bool`

Whether the underlying implementation (be it a file path, or something else) is pointing at a directory in the underlying FS. Will return false for paths to non-existent locations or if the item is not a directory (eg files, named pipes, etc). Follows links when making this determination.

## Trait Implementations

### `impl<'a> IntoCow<'a, Path> for &'a Path`

#### `fn into_cow(self) -> Cow<'a, Path>`

### `impl ToOwned for Path`

#### `type Owned = PathBuf`

#### `fn to_owned(&self) -> PathBuf`

### `impl AsRef<OsStr> for Path`

#### `fn as_ref(&self) -> &OsStr`

### `impl Debug for Path`

#### `fn fmt(&self, formatter: &mut Formatter) -> Result<(), Error>`

### `impl PartialEq for Path`

#### `fn eq(&self, other: &Path) -> bool`

#### `fn ne(&self, other: &Rhs) -> bool`

### `impl Hash for Path`

#### `fn hash<H: Hasher>(&self, h: &mut H)`

#### `fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher`

### `impl Eq for Path`

### `impl PartialOrd for Path`

#### `fn partial_cmp(&self, other: &Path) -> Option<Ordering>`

#### `fn lt(&self, other: &Rhs) -> bool`

#### `fn le(&self, other: &Rhs) -> bool`

#### `fn gt(&self, other: &Rhs) -> bool`

#### `fn ge(&self, other: &Rhs) -> bool`

### `impl Ord for Path`

#### `fn cmp(&self, other: &Path) -> Ordering`

### `impl AsRef<Path> for Path`

#### `fn as_ref(&self) -> &Path`

### `impl<'a> IntoIterator for &'a Path`

#### `type Item = &'a OsStr`

#### `type IntoIter = Iter<'a>`

#### `fn into_iter(self) -> Iter<'a>`

### `impl<'a, 'b> PartialEq<PathBuf> for Path`

#### `fn eq(&self, other: &PathBuf) -> bool`

#### `fn ne(&self, other: &Rhs) -> bool`

### `impl<'a, 'b> PartialEq<PathBuf> for &'a Path`

#### `fn eq(&self, other: &PathBuf) -> bool`

#### `fn ne(&self, other: &Rhs) -> bool`

### `impl<'a, 'b> PartialEq<Cow<'a, Path>> for Path`

#### `fn eq(&self, other: &Cow<'a, Path>) -> bool`

#### `fn ne(&self, other: &Rhs) -> bool`

### `impl<'a, 'b> PartialEq<Cow<'a, Path>> for &'b Path`

#### `fn eq(&self, other: &Cow<'a, Path>) -> bool`

#### `fn ne(&self, other: &Rhs) -> bool`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize`)