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

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")
    let path = Path::new(r"C:\path\to\file.txt");
    for component in path.components() {
        println!("* {:?}", component);
    }
}

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")]
    //
    let path = WindowsPath::new(r"C:\path\to\file.txt");
    for component in path.components() {
        println!("* {:?}", component);
    }
}

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")]
    //
    let path = Utf8WindowsPath::new(r"C:\path\to\file.txt");
    for component in path.components() {
        println!("* {:?}", component);
    }
}

Converting between encodings

There may be times in which you need to convert between encodings such as when you want to load a native path and convert it into another format. In that case, you can use the with_encoding method (or specific variants like with_unix_encoding and with_windows_encoding) to convert a Path or Utf8Path into their respective PathBuf and Utf8PathBuf with an explicit encoding:

use typed_path::{Utf8Path, Utf8UnixEncoding, Utf8WindowsEncoding};

fn main() {
    // Convert from Unix to Windows
    let unix_path = Utf8Path::<Utf8UnixEncoding>::new("/tmp/foo.txt");
    let windows_path = unix_path.with_encoding::<Utf8WindowsEncoding>();
    assert_eq!(windows_path, Utf8Path::<Utf8WindowsEncoding>::new(r"\tmp\foo.txt"));
   
    // Converting from Windows to Unix will drop any prefix
    let windows_path = Utf8Path::<Utf8WindowsEncoding>::new(r"C:\tmp\foo.txt");
    let unix_path = windows_path.with_encoding::<Utf8UnixEncoding>();
    assert_eq!(unix_path, Utf8Path::<Utf8UnixEncoding>::new(r"/tmp/foo.txt"));
   
    // Converting to itself should retain everything
    let path = Utf8Path::<Utf8WindowsEncoding>::new(r"C:\tmp\foo.txt");
    assert_eq!(
        path.with_encoding::<Utf8WindowsEncoding>(),
        Utf8Path::<Utf8WindowsEncoding>::new(r"C:\tmp\foo.txt"),
    );
}

Typed Paths

In the above examples, we were using paths where the encoding (Unix or Windows) was known at compile time. There may be situations where we need runtime support to decide and switch between encodings. For that, this crate provides the TypedPath and TypedPathBuf enumerations (and their Utf8TypedPath and Utf8TypedPathBuf variations):

use typed_path::Utf8TypedPath;

// Derive the path by determining if it is Unix or Windows
let path = Utf8TypedPath::derive(r"C:\path\to\file.txt");
assert!(path.is_windows());

// Change the encoding to Unix
let path = path.with_unix_encoding();
assert_eq!(path, "/path/to/file.txt");

Normalization

Alongside implementing the standard methods associated with Path and PathBuf from the standard library, this crate also implements several additional methods including the ability to normalize a path by resolving . and .. without the need to have the path exist.

use typed_path::Utf8UnixPath;

assert_eq!(
    Utf8UnixPath::new("foo/bar//baz/./asdf/quux/..").normalize(),
    Utf8UnixPath::new("foo/bar/baz/asdf"),
);

In addition, you can leverage absolutize to convert a path to an absolute form by prepending the current working directory if the path is relative and then normalizing it (requires std feature):

use typed_path::{utils, Utf8UnixPath};

// With an absolute path, it is just normalized
// NOTE: This requires `std` feature, otherwise `absolutize` is missing!
let path = Utf8UnixPath::new("/a/b/../c/./d");
assert_eq!(path.absolutize().unwrap(), Utf8UnixPath::new("/a/c/d"));

// With a relative path, it is first joined with the current working directory
// and then normalized
// NOTE: This requires `std` feature, otherwise `utf8_current_dir` and
//       `absolutize` are missing!
let cwd = utils::utf8_current_dir().unwrap().with_unix_encoding();
let path = cwd.join(Utf8UnixPath::new("a/b/../c/./d"));
assert_eq!(path.absolutize().unwrap(), cwd.join(Utf8UnixPath::new("a/c/d")));

Current directory

Helper functions are available in the utils module (requires std feature), and one of those provides an identical experience to std::env::current_dir:

// Retrieves the current directory as a NativePath:
//
// * For Unix family, this would be Path<UnixEncoding>
// * For Windows family, this would be Path<WindowsEncoding>
//
// NOTE: This requires `std` feature, otherwise `current_dir` is missing!
let _cwd = typed_path::utils::current_dir().unwrap();

// Retrieves the current directory as a Utf8NativePath:
//
// * For Unix family, this would be Utf8Path<Utf8UnixEncoding>
// * For Windows family, this would be Utf8Path<Utf8WindowsEncoding>
//
// NOTE: This requires `std` feature, otherwise `utf8_current_dir` is missing!
let _utf8_cwd = typed_path::utils::utf8_current_dir().unwrap();

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

  • constants
    Contains constants associated with different path formats.
  • utils

Structs

Enums

Traits

Type Aliases