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) ofself
`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:
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
` andhas_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, whilec: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>
: 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 notc:windows
`c:windows` - has any non-disk prefix, e.g.
\\server\share
`\server\share`
- has no prefix and begins with a separator, e.g.
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>
: 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());