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

pub struct PathBuf {
    // some fields omitted
}

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

This type provides methods like push`pushand` and set_extension`set_extensionthat mutate the path in place. It also implements` that mutate the path in place. It also implements Deref`Derefto` to Path`Path, meaning that all methods on`, meaning that all methods on Path`Pathslices are available on` slices are available on PathBuf`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`PathBuf`.

fn as_path(&self) -> &Path

Coerces to a Path`Path` slice.

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

Extends self`selfwith` with path`path`.

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

On Windows:

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

fn pop(&mut self) -> bool

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

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

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

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

If self.file_name()`self.file_name()was` was None`None, this is equivalent to pushing`, this is equivalent to pushing file_name`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()`self.extension()to` to extension`extension`.

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

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

fn into_os_string(self) -> OsString

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

Methods from Deref<Target=Path>

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

Directly wrap a string slice as a Path`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`Paths from`s from String`Strings, or even other`s, or even other Path`Path`s:

fn main() { use std::path::Path; let s = String::from("bar.txt"); let p = Path::new(&s); Path::new(&p); }
use std::path::Path;

let s = String::from("bar.txt");
let p = Path::new(&s);
Path::new(&p);

fn as_os_str(&self) -> &OsStr

Yields the underlying OsStr`OsStr` slice.

Examples

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

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

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

Yields a &str`&strslice if the` slice if the Path`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(); }
use std::path::Path;

let path_str = Path::new("foo.txt").to_str();

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

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

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(); }
use std::path::Path;

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

fn to_path_buf(&self) -> PathBuf

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

Examples

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

let path_str = Path::new("foo.txt").to_path_buf();

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`is_absoluteand` and has_root`has_root` are equivalent.

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

Examples

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

assert_eq!(false, 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

: 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:`C:, UNC prefixes like`, UNC prefixes like \\server`\server, and others described in more detail in`, and others described in more detail in std::os::windows::PathExt`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`\windows`
    • has a prefix followed by a separator, e.g. c:\windows`c:\windowsbut not` but not c:windows`c:windows`
    • has any non-disk prefix, e.g. \\server\share`\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`None` if the path terminates in a root or prefix.

Examples

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

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

assert!(foo == Path::new("/foo"));

let root = foo.parent().unwrap();

assert!(root == Path::new("/"));
assert!(root.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 or a root of prefix,`, or consists solely or a root of prefix, file_name`file_namewill return` will return None`None`.

Examples

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

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

assert_eq!(filename, path.file_name().unwrap());

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

Unstable

: see #23284

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

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

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

Determines whether base`baseis a prefix of` is a prefix of self`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`childis a suffix of` is a suffix of self`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()`self.file()`.

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` 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()`self.file()`, 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` 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`PathBufwith` with path`pathadjoined to` adjoined to self`self`.

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

Examples

fn main() { use std::path::Path; let path = Path::new("/tmp"); let new_path = path.join("foo"); }
use std::path::Path;

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

let new_path = path.join("foo");

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

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

See PathBuf::set_file_name`PathBuf::set_file_name` for more details.

Examples

fn main() { use std::path::Path; let path = Path::new("/tmp/foo.rs"); let new_path = path.with_file_name("bar.rs"); }
use std::path::Path;

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

let new_path = path.with_file_name("bar.rs");

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

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

See PathBuf::set_extension`PathBuf::set_extension` for more details.

Examples

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

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

let new_path = path.with_extension("txt");
assert_eq!(new_path, PathBuf::from("/tmp/foo.txt"));

fn components(&self) -> Components

Produce an iterator over the components of the path.

Examples

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

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

for component in path.components() {
    println!("{:?}", component);
}

fn iter(&self) -> Iter

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

Examples

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

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

for component in path.iter() {
    println!("{:?}", component);
}

fn display(&self) -> Display

Returns an object that implements Display`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());

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

Derived Implementations

impl Hash for PathBuf

fn hash<__H: Hasher>(&self, __arg_0: &mut __H)

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

impl Clone for PathBuf

fn clone(&self) -> PathBuf

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