Cross-platform path manipulation.
This module provides two types,
Path (akin to
str), for working with paths abstractly. These types are thin wrappers
OsStr respectively, meaning that they work directly
on strings according to the local platform's path syntax.
Path manipulation includes both parsing components from slices and building new owned paths.
To parse a path, you can create a
Path slice from a
slice and start asking questions:
use std::path::Path; let path = Path::new("/tmp/foo/bar.txt"); let file = path.file_name(); let extension = path.extension(); let parent_dir = path.parent();
To build or modify paths, use
use std::path::PathBuf; let mut path = PathBuf::from("c:\\"); path.push("windows"); path.push("system32"); path.set_extension("dll");
The path APIs are built around the notion of "components", which roughly
correspond to the substrings between path separators (
/ and, on Windows,
\). The APIs for path parsing are largely specified in terms of the path's
components, so it's important to clearly understand how those are determined.
A path can always be reconstructed into an equivalent path by
putting together its components via
push. Syntactically, the
paths may differ by the normalization described below.
Components come in several types:
Normal components are the default: standard references to files or directories. The path
a/bhas two normal components,
Current directory components represent the
.character. For example,
./ahas a current directory component and a normal component
The root directory component represents a separator that designates starting from root. For example,
/a/bhas a root directory component followed by normal components
On Windows, an additional component type comes into play:
- Prefix components, of which there is a large variety. For example,
\\server\shareare prefixes. The path
C:windowshas a prefix component
C:and a normal component
windows; the path
C:\windowshas a prefix component
C:, a root directory component, and a normal component
Aside from splitting on the separator(s), there is a small amount of "normalization":
Repeated separators are ignored:
a//bboth have components
.are normalized away, except if they are at the beginning of the path (in which case they are often meaningful in terms of path searching). So, for example,
a/ball have components
./a/bhas a leading current directory component.
No other normalization takes place by default. In particular,
a/b/../c are distinct, to account for the possibility
b is a symbolic link (so its parent isn't
normalization is possible to build on top of the components APIs,
and will be included in this library in the near future.
The core iterator giving the components of a path.
Helper struct for safely printing paths with
An iterator over the components of a path, as
A slice of a path (akin to
An owned, mutable path (akin to
A Windows path prefix, e.g.
A single component of a path.
Path prefixes (Windows only).
The primary separator for the current platform
Determines whether the character is one of the permitted path separators for the current platform.