Crate typed_path

source ·
Expand description

Typed Path

Crates.io Docs.rs CI RustC 1.58.1+

Provides typed variants of Path and PathBuf for Unix and Windows.

Install

[dependencies]
typed-path = "0.3"

Why?

Some applications need to manipulate Windows or UNIX paths on different platforms, for a variety of reasons: constructing portable file formats, parsing files from other platforms, handling archive formats, working with certain network protocols, and so on.

– Josh Triplett

Check out this issue of a discussion for this. The functionality actually exists within the standard library, but is not exposed!

This means that parsing a path like C:\path\to\file.txt will be parsed differently by std::path::Path depending on which platform you are on!

use std::path::Path;

fn main() {
    // On Windows, this prints out:
    //
    // * Prefix(PrefixComponent { raw: "C:", parsed: Disk(67) })
    // * RootDir
    // * Normal("path")
    // * Normal("to")
    // * Normal("file.txt")]
    //
    // But on Unix, this prints out:
    //
    // * Normal("C:\\path\\to\\file.txt")
    println!(
        "{:?}",
        Path::new(r"C:\path\to\file.txt")
            .components()
            .collect::<Vec<_>>()
    );
}

Usage

Byte paths

The library provides a generic Path<T> and PathBuf<T> that use [u8] and Vec<u8> underneath instead of OsStr and OsString. An encoding generic type is provided to dictate how the underlying bytes are parsed in order to support consistent path functionality no matter what operating system you are compiling against!

use typed_path::WindowsPath;

fn main() {
    // On all platforms, this prints out:
    //
    // * Prefix(PrefixComponent { raw: "C:", parsed: Disk(67) })
    // * RootDir
    // * Normal("path")
    // * Normal("to")
    // * Normal("file.txt")]
    //
    println!(
        "{:?}",
        WindowsPath::new(r"C:\path\to\file.txt")
            .components()
            .collect::<Vec<_>>()
    );
}

UTF8-enforced paths

Alongside the byte paths, this library also supports UTF8-enforced paths through UTF8Path<T> and UTF8PathBuf<T>, which internally use str and String. An encoding generic type is provided to dictate how the underlying characters are parsed in order to support consistent path functionality no matter what operating system you are compiling against!

use typed_path::Utf8WindowsPath;

fn main() {
    // On all platforms, this prints out:
    //
    // * Prefix(Utf8WindowsPrefixComponent { raw: "C:", parsed: Disk(67) })
    // * RootDir
    // * Normal("path")
    // * Normal("to")
    // * Normal("file.txt")]
    //
    println!(
        "{:?}",
        Utf8WindowsPath::new(r"C:\path\to\file.txt")
            .components()
            .collect::<Vec<_>>()
    );
}

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or apache-license) MIT license (LICENSE-MIT or mit-license) at your option.

Modules

Structs

Traits

Type Definitions