std::path - Rust
Description: API documentation for the Rust `path` mod in crate `std`.
Keywords: rust, rustlang, rust-lang, path

# Module std::path 1.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.push("windows");
    path.push("system32");
    path.set_extension("dll");Run

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)