Module std::path

1.0.0 · source ·
Expand description

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.

Paths can be parsed into Components by iterating over the structure returned by the components method on Path. Components roughly correspond to the substrings between path separators (/ or \). You can reconstruct an equivalent path from components with the push method on PathBuf; note that the paths may differ syntactically by the normalization described in the documentation for the components method.

Case sensitivity

Unless otherwise indicated path methods that do not access the filesystem, such as Path::starts_with and Path::ends_with, are case sensitive no matter the platform or filesystem. An exception to this is made for Windows drive letters.

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;

// This way works...
let mut path = PathBuf::from("c:\\");

path.push("windows");
path.push("system32");

path.set_extension("dll");

// ... but push is best used if you don't know everything up
// front. If you do, this way is better:
let path: PathBuf = ["c:\\", "windows", "system32.dll"].iter().collect();
Run

Macros

Structs

Enums

  • Component
    A single component of a path.
  • Prefix
    Windows path prefixes, e.g., C: or \\server\share.
  • State 🔒
    Component parsing works by a double-ended state machine; the cursors at the front and back of the path each keep track of what parts of the path have been consumed so far.

Constants

  • MAIN_SEPARATOR
    The primary separator of path components for the current platform.
  • MAIN_SEPARATOR_STR
    The primary separator of path components for the current platform.

Functions