# 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 `Component`s by iterating over the structure returned by the `components` method on `Path`. `Component`s 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

## Structs

- Ancestors
  An iterator over `Path` and its ancestors.
- Components
  An iterator over the `Component`s of a `Path`.
- Display
  Helper struct for safely printing paths with `format!` and `{}`.
- Iter
  An iterator over the `Component`s 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 structure wrapping a Windows path prefix as well as its unparsed string representation.
- StripPrefixError
  An error returned from `Path::strip_prefix` if the prefix was not found.

## Enums

- Component
  A single component of a path.
- Prefix
  Windows path prefixes, e.g., `C:` or `\\server\share`.

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

- absolute Experimental
  Makes the path absolute without accessing the filesystem.
- is_separator
  Determines whether the character is one of the permitted path separators for the current platform.