Module std::path

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 includes 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;
use std::ffi::OsStr;

let path = Path::new("/tmp/foo/bar.txt");

let parent = path.parent();
assert_eq!(parent, Some(Path::new("/tmp/foo")));

let file_stem = path.file_stem();
assert_eq!(file_stem, Some(OsStr::new("bar")));

let extension = path.extension();
assert_eq!(extension, Some(OsStr::new("txt")));

To build or modify paths, use PathBuf:

use std::path::PathBuf;

let mut path = PathBuf::from("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 and b.

• Current directory components represent the . character. For example, ./a has a current directory component and a normal component a.

• The root directory component represents a separator that designates starting from root. For example, /a/b has a root directory component followed by normal components a and b.

On Windows, an additional component type comes into play:

• Prefix components, of which there is a large variety. For example, C: and \\server\share are prefixes. The path C:windows has a prefix component C: and a normal component windows; the path C:\windows has a prefix component C:, a root directory component, and a normal component windows.

Normalization

Aside from splitting on the separator(s), there is a small amount of "normalization":

• Repeated separators are ignored: a/b and a//b both have components a and b.

• Occurrences of . 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/./b, a/b/, /a/b/. and a/b all have components a and b, but ./a/b has a leading current directory component.

No other normalization takes place by default. In particular, a/c and a/b/../c are distinct, to account for the possibility that b is a symbolic link (so its parent isn't a). Further normalization is possible to build on top of the components APIs, and will be included in this library in the near future.

Structs

Components	The core iterator giving the components of a path.
Display	Helper struct for safely printing paths with format!() and {}
Iter	An iterator over the components of a path, as OsStr slices.
Path	A slice of a path (akin to str).
PathBuf	An owned, mutable path (akin to String).
PrefixComponent	A Windows path prefix, e.g. C: or \\server\share.
StripPrefixError	An error returned from the Path::strip_prefix method indicating that the prefix was not found in self.

Enums

Component	A single component of a path.
Prefix	Path prefixes (Windows only).

Constants

MAIN_SEPARATOR

The primary separator of path components for the current platform.

Functions

is_separator

Determines whether the character is one of the permitted path separators for the current platform.