Module std::path
Cross-platform path support
This module implements support for two flavors of paths. PosixPath
represents
a path on any unix-like system, whereas WindowsPath
represents a path on
Windows. This module also exposes a typedef Path
which is equal to the
appropriate platform-specific path variant.
Both PosixPath
and WindowsPath
implement a trait GenericPath
, which
contains the set of methods that behave the same for both paths. They each also
implement some methods that could not be expressed in GenericPath
, yet behave
identically for both path flavors, such as .components()
.
The three main design goals of this module are 1) to avoid unnecessary allocation, 2) to behave the same regardless of which flavor of path is being used, and 3) to support paths that cannot be represented in UTF-8 (as Linux has no restriction on paths beyond disallowing NUL).
Usage
Usage of this module is fairly straightforward. Unless writing platform-specific
code, Path
should be used to refer to the platform-native path.
Creation of a path is typically done with either Path::new(some_str)
or
Path::new(some_vec)
. This path can be modified with .push()
and
.pop()
(and other setters). The resulting Path can either be passed to another
API that expects a path, or can be turned into a &[u8] with .as_vec()
or a
Option<&str> with .as_str()
. Similarly, attributes of the path can be queried
with methods such as .filename()
. There are also methods that return a new
path instead of modifying the receiver, such as .join()
or .dir_path()
.
Paths are always kept in normalized form. This means that creating the path
Path::new("a/b/../c")
will return the path a/c
. Similarly any attempt
to mutate the path will always leave it in normalized form.
When rendering a path to some form of output, there is a method .display()
which is compatible with the format!()
parameter {}
. This will render the
path as a string, replacing all non-utf8 sequences with the Replacement
Character (U+FFFD). As such it is not suitable for passing to any API that
actually operates on the path; it is only intended for display.
Example
let mut path = Path::new("/tmp/path"); println!("path: {}", path.display()); path.set_filename("foo"); path.push("bar"); println!("new path: {}", path.display()); println!("path exists: {}", path.exists());
Reexports
pub use PosixPath = self::posix::Path; |
pub use WindowsPath = self::windows::Path; |
pub use self::posix::Path; |
pub use self::posix::Components; |
pub use self::posix::RevComponents; |
pub use self::posix::StrComponents; |
pub use self::posix::RevStrComponents; |
pub use self::posix::SEP; |
pub use self::posix::SEP_BYTE; |
pub use self::posix::is_sep; |
pub use self::posix::is_sep_byte; |
Modules
posix | POSIX file path handling |
windows | Windows file path handling |
Structs
Display | Helper struct for printing paths with format!() |
Traits
BytesContainer | A trait that represents something bytes-like (e.g. a &[u8] or a &str) |
GenericPath | A trait that represents the generic operations available on paths |
GenericPathUnsafe | A trait that represents the unsafe operations on GenericPaths |