Module std::pathUnstable

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:

fn main() { 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(); }

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:

fn main() { use std::path::PathBuf; let mut path = PathBuf::new("c:\\"); path.push("windows"); path.push("system32"); path.set_extension("dll"); }

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 and b.

• Current directory components represent the . character. For example, a/. has a normal component a 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 components a and b.

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 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.

• 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 and a//b both have components a and b.

• 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 components a and b, the paths a/b/ and a/b/. both have components a, b, and . (current directory). The reason for this normalization is that a/b and a/b/ are treated differently in some contexts, but a/b/ and a/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 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).

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 Path.

Functions

is_separator

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