Module std::pathUnstable
[-] [+]
[src]
Cross-platform path manipulation.
This module provides two types, PathBuf
and Path
(akin to String
and
str
), for working with paths abstractly. These types are thin wrappers
around OsString
and OsStr
respectively, meaning that they work directly
on strings according to the local platform's path syntax.
Simple usage
Path manipulation involves both parsing components from slices and building new owned paths.
To parse a path, you can create a Path
slice from a str
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 PathBuf
:
use std::path::PathBuf; let mut path = PathBuf::new("c:\\"); path.push("windows"); path.push("system32"); path.set_extension("dll");
Path components and normalization
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.
Component types
Components come in several types:
Normal components are the default: standard references to files or directories. The path
a/b
has two normal components,a
andb
.Current directory components represent the
.
character. For example,a/.
has a normal componenta
and a current directory component.The root directory component represents a separator that designates starting from root. For example,
/a/b
has a root directory component followed by normal componentsa
andb
.
On Windows, two additional component types come into play:
Prefix components, of which there is a large variety. For example,
C:
and\\server\share
are prefixes. The pathC:windows
has a prefix componentC:
and a normal componentwindows
; the pathC:\windows
has a prefix componentC:
, a root directory component, and a normal componentwindows
.Empty components, a special case for so-called "verbatim" paths where very little normalization is allowed. For example,
\\?\C:\
has a "verbatim" prefix\\?\C:
, a root component, and an empty component (as a way of representing the trailing\
. Such a trailing\
is in fact the only situation in which an empty component is produced.
Normalization
Aside from splitting on the separator(s), there is a small amount of "normalization":
Repeated separators are ignored:
a/b
anda//b
both have componentsa
andb
.Paths ending in a separator are treated as if they has a current directory component at the end (or, in verbatim paths, an empty component). For example, while
a/b
has componentsa
andb
, the pathsa/b/
anda/b/.
both have componentsa
,b
, and.
(current directory). The reason for this normalization is thata/b
anda/b/
are treated differently in some contexts, buta/b/
anda/b/.
are always treated the same.
No other normalization takes place by default. In particular, a/./b/
and
a/b
are treated distinctly in terms of components, as are a/c
and
a/b/../c
. Further normalization is possible to build on top of the
components APIs, and will be included in this library very soon.
Structs
Components | The core iterator giving the components of a path. |
Display | Helper struct for safely printing paths with |
Iter | An iterator over the components of a path, as |
Path | A slice of a path (akin to |
PathBuf | An owned, mutable path (akin to |
Enums
Component | A single component of a path. |
Prefix | Path prefixes (Windows only). |
Constants
MAIN_SEPARATOR | The primary sperator for the current platform |
Traits
AsPath | Freely convertible to a |
Functions
is_separator | Determine whether the character is one of the permitted path separators for the current platform. |