Module std::path1.0.0 [] [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 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")));Run

To build or modify paths, use PathBuf:

use std::path::PathBuf;

let mut path = PathBuf::from("c:\\");

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:

On Windows, an additional component type comes into play:


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

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.



The core iterator giving the components of a path.


Helper struct for safely printing paths with format!() and {}


An iterator over the components of a path, as OsStr slices.


A slice of a path (akin to str).


An owned, mutable path (akin to String).


A Windows path prefix, e.g. C: or \\server\share.


An error returned from the Path::strip_prefix method indicating that the prefix was not found in self.



A single component of a path.


Path prefixes (Windows only).



The primary separator of path components for the current platform.



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