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

Unstable (path_prefix #27722)
: uncertain whether to expose this convenience

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

Unstable (path_relative_from #23284)
: see #23284

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.

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

Methods

impl PathBuf

fn new() -> PathBuf

fn as_path(&self) -> &Path

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

fn pop(&mut self) -> bool

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

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

fn into_os_string(self) -> OsString

Methods from Deref<Target=Path>

fn as_os_str(&self) -> &OsStr

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

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

fn to_path_buf(&self) -> PathBuf

fn is_absolute(&self) -> bool

fn is_relative(&self) -> bool

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

fn has_root(&self) -> bool

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

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

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

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

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

fn file_stem(&self) -> Option<&OsStr>

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

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

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

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

fn components(&self) -> Components

fn iter(&self) -> Iter

fn display(&self) -> Display

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

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

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

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

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

fn exists(&self) -> bool

fn is_file(&self) -> bool

fn is_dir(&self) -> bool

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

`impl PathBuf`

`fn new() -> PathBuf`

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

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

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

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

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

`fn into_os_string(self) -> OsString`

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

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

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

`fn to_path_buf(&self) -> PathBuf`

`fn is_absolute(&self) -> bool`

`fn is_relative(&self) -> bool`

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

`fn has_root(&self) -> bool`

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

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

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

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

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

`fn file_stem(&self) -> Option<&OsStr>`

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

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

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

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

`fn components(&self) -> Components`

`fn iter(&self) -> Iter`

`fn display(&self) -> Display`

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

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

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

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

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

`fn exists(&self) -> bool`

`fn is_file(&self) -> bool`

`fn is_dir(&self) -> bool`

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