Struct path::PathBuf

source ·

pub struct PathBuf { /* private fields */ }

Expand description

An owned, mutable path.

This type is just a wrapper around a String.

Implementations§

source §

impl PathBuf

source

pub fn new() -> Self

Allocates an empty PathBuf.

source

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

Extends self with path.

If path is absolute, it replaces the current path.

Examples

Pushing a relative path extends the existing path:

use std::path::PathBuf;

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

Pushing an absolute path replaces the existing path:

use std::path::PathBuf;

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

source

pub fn pop(&mut self) -> bool

Truncates self to self.parent.

Returns false and does nothing if self.parent is None. Otherwise, returns true.

Examples

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

let mut p = PathBuf::from("/spirited/away.rs");

p.pop();
assert_eq!(Path::new("/spirited"), p);
p.pop();
assert_eq!(Path::new("/"), p);

Methods from Deref<Target = Path>§

source

pub fn components(&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/b and a//b both have a and b as components.
Occurrences of . are normalized away, except if they are at the beginning of the path. For example, a/./b, a/b/, a/b/. and a/b all have a and b as components, but ./a/b starts with an additional CurDir component.
A trailing slash is normalized away, /a/b and /a/b/ are equivalent.

Examples

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

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

source

pub fn is_absolute(&self) -> bool

Returns true if the path starts with the root.

Examples

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

source

pub fn join(&self, path: P) -> PathBufwhere P: AsRef<Self>,

Creates an owned PathBuf with path adjoined to self.

If path is absolute, it replaces the current path.

Examples

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

source

pub fn parent(&self) -> Option<&Self>

Returns the path without its final component, if there is one.

Examples

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

let relative_path = Path::new("foo/bar");
let parent = relative_path.parent();
assert_eq!(parent, Some(Path::new("foo")));
let grand_parent = parent.and_then(Path::parent);
assert_eq!(grand_parent, Some(Path::new("")));
assert_eq!(grand_parent, Some(Path::new("")));
let great_grand_parent = grand_parent.and_then(Path::parent);
assert_eq!(great_grand_parent, None);

source

pub fn file_name(&self) -> Option<&str>

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 None if the path terminates in ...

Examples

assert_eq!(Some("bin"), Path::new("/usr/bin/").file_name());
assert_eq!(Some("foo.txt"), Path::new("tmp/foo.txt").file_name());
assert_eq!(Some("foo.txt"), Path::new("foo.txt/.").file_name());
assert_eq!(Some("foo.txt"), Path::new("foo.txt/.//").file_name());
assert_eq!(None, Path::new("foo.txt/..").file_name());
assert_eq!(None, Path::new("/").file_name());

source

pub fn file_stem(&self) -> Option<&str>

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

assert_eq!("foo", Path::new("foo.rs").file_stem().unwrap());
assert_eq!(".foo", Path::new(".foo").file_stem().unwrap());
assert_eq!("foo.tar", Path::new("foo.tar.gz").file_stem().unwrap());

source

pub fn get(&self, cwd: &DirRef) -> Option<FileOrDir>

Returns the file or directory at the given path.

The path can be relative or absolute.

If the path does not point to a file system object, None is returned.

source

pub fn get_file(&self, cwd: &DirRef) -> Option<FileRef>

Returns the file at the given path.

The path can be relative or absolute.

If the path does not point to a file, None is returned.

source

pub fn get_dir(&self, cwd: &DirRef) -> Option<DirRef>

Returns the directory at the given path.

The path can be relative or absolute.

If the path does not point to a directory, None is returned.

source

pub fn relative(&self, base: P) -> Option<PathBuf>where P: AsRef<Path>,

Construct a relative path from a provided base directory path to the provided path.

source

pub fn extension(&self) -> Option<&str>

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

assert_eq!(None, Path::new("foo").extension());
assert_eq!(None, Path::new(".foo").extension());
assert_eq!("rs", Path::new("foo.rs").extension().unwrap());
assert_eq!("gz", Path::new("foo.tar.gz").extension().unwrap());