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

    pub struct PathBuf {
        // some fields omitted
    }

An owned, mutable path (akin to `String`).

This type provides methods like `push` and `set_extension` that mutate the path in place. It also implements `Deref` to `Path`, meaning that all methods on `Path` slices are available on `PathBuf` values as well.

More details about the overall approach can be found in the module documentation.

# Examples

fn main() { use std::path::PathBuf; let mut path = PathBuf::from("c:\\"); path.push("windows"); path.push("system32"); path.set_extension("dll"); }

    use std::path::PathBuf;

    let mut path = PathBuf::from("c:\\");
    path.push("windows");
    path.push("system32");
    path.set_extension("dll");

## Methods

### `impl PathBuf`

#### `fn new() -> PathBuf`

Allocates an empty `PathBuf`.

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

Coerces to a `Path` slice.

#### `fn push<P: AsRef<Path>>(&mut self, path: P)`

Extends `self` with `path`.

If `path` is absolute, it replaces the current path.

On Windows:

- if `path` has a root but no prefix (e.g. `\windows`), it replaces everything except for the prefix (if any) of `self`.
- if `path` has a prefix but no root, it replaces `self`.

# Examples

fn main() { use std::path::PathBuf; let mut path = PathBuf::new(); path.push("/tmp"); path.push("file.bk"); assert_eq!(path, PathBuf::from("/tmp/file.bk")); // Pushing an absolute path replaces the current path path.push("/etc/passwd"); assert_eq!(path, PathBuf::from("/etc/passwd")); }

    use std::path::PathBuf;

    let mut path = PathBuf::new();
    path.push("/tmp");
    path.push("file.bk");
    assert_eq!(path, PathBuf::from("/tmp/file.bk"));

    // Pushing an absolute path replaces the current path
    path.push("/etc/passwd");
    assert_eq!(path, PathBuf::from("/etc/passwd"));

#### `fn pop(&mut self) -> bool`

Truncate `self` to `self.parent()`.

Returns false and does nothing if `self.file_name()` is `None`. Otherwise, returns `true`.

#### `fn set_file_name<S: AsRef<OsStr>>(&mut self, file_name: S)`

Updates `self.file_name()` to `file_name`.

If `self.file_name()` was `None`, this is equivalent to pushing `file_name`.

# Examples

fn main() { use std::path::PathBuf; let mut buf = PathBuf::from("/"); assert!(buf.file_name() == None); buf.set_file_name("bar"); assert!(buf == PathBuf::from("/bar")); assert!(buf.file_name().is_some()); buf.set_file_name("baz.txt"); assert!(buf == PathBuf::from("/baz.txt")); }

    use std::path::PathBuf;

    let mut buf = PathBuf::from("/");
    assert!(buf.file_name() == None);
    buf.set_file_name("bar");
    assert!(buf == PathBuf::from("/bar"));
    assert!(buf.file_name().is_some());
    buf.set_file_name("baz.txt");
    assert!(buf == PathBuf::from("/baz.txt"));

#### `fn set_extension<S: AsRef<OsStr>>(&mut self, extension: S) -> bool`

Updates `self.extension()` to `extension`.

If `self.file_name()` is `None`, does nothing and returns `false`.

Otherwise, returns `true`; if `self.extension()` is `None`, the extension is added; otherwise it is replaced.

#### `fn into_os_string(self) -> OsString`

Consumes the `PathBuf`, yielding its internal `OsString` storage.

## Methods from Deref<Target=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, T: ?Sized + AsRef<OsStr>> From<&'a T> for PathBuf`

#### `fn from(s: &'a T) -> PathBuf`

### `impl From<OsString> for PathBuf`

#### `fn from(s: OsString) -> PathBuf`

### `impl From<String> for PathBuf`

#### `fn from(s: String) -> PathBuf`

### `impl<P: AsRef<Path>> FromIterator<P> for PathBuf`

#### `fn from_iter<I: IntoIterator<Item=P>>(iter: I) -> PathBuf`

### `impl<P: AsRef<Path>> Extend<P> for PathBuf`

#### `fn extend<I: IntoIterator<Item=P>>(&mut self, iter: I)`

### `impl Debug for PathBuf`

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

### `impl Deref for PathBuf`

#### `type Target = Path`

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

### `impl Borrow<Path> for PathBuf`

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

### `impl IntoCow<'static, Path> for PathBuf`

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

### `impl PartialEq for PathBuf`

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

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

### `impl Hash for PathBuf`

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

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

### `impl Eq for PathBuf`

### `impl PartialOrd for PathBuf`

#### `fn partial_cmp(&self, other: &PathBuf) -> 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 PathBuf`

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

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

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

### `impl Into<OsString> for PathBuf`

#### `fn into(self) -> OsString`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Derived Implementations

### `impl Clone for PathBuf`

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

#### `fn clone_from(&mut self, source: &Self)`

# 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`)