#path #static #initialization #const #cow

maybe_path

Zero overhead static initializer for Path

4 releases

new 0.1.3 Dec 3, 2024
0.1.2 Dec 2, 2024
0.1.1 Dec 2, 2024
0.1.0 Dec 2, 2024

#1268 in Filesystem

Download history 664/week @ 2024-11-30

670 downloads per month
Used in rustyscript

MIT/Apache

19KB
254 lines

MaybePath

Crates.io Build Status docs.rs License

A Near-Zero-Overhead read-only Path wrapper that can also hold a str.
The primary usecase is static initialization of a Path at compile-time.

It implements Deref<Target = Path>, so you can treat it as a drop-in replacement for Path in most cases.

Basic usage is as follows:

use maybe_path::{MaybePath, MaybePathBuf};

// These are both equivalent to `Path::new("foo/bar/baz")`
// But normally the const could not also be a `Path`
let path = MaybePath::new_path("foo/bar/baz");
const PATH: MaybePath = MaybePath::new_str("foo/bar/baz");

// An equivalent to `Cow<Path>` is also included
let not_a_cow = MaybePathBuf::new_path("foo/bar/baz");
const NOT_A_COW: MaybePathBuf = MaybePathBuf::new_str("foo/bar/baz");

Performance

MaybePath is a zero-runtime-cost abstraction over Path and str - it does however store a u8 discriminant internally. Benchmarks show that MaybePath is faster than Cow<Path> for most operations:

  • Read: 798.20 ps vs 1.5002 ns
  • Clone: 811.02 ps vs 2.3745 ns

MaybePathBuf, a drop-in replacement for Cow<Path> that includes a 3rd state for MaybePath's str variant
has performance matching that of Cow<Path>: ( Produced ASM is identical )

  • Read: 1.5958 ns vs 1.6596 ns
  • Clone: 3.8059 ns vs 3.2304 ns
  • AsRef x1000: 2.1066 µs vs 3.2081 µs

Safety

While it is possible to access the underlying memory as-is with as_path_unchecked or as_str_unchecked, it is not recommended to do so unless you are absolutely sure that the MaybePath is a Path or str.

However, in the current implementation of Path, all valid str's are valid paths - but this implementation detail may change in the future.

This implementation uses a union internally, since this method yields significant performance gains over using an enum.

Dependencies

~0.3–1MB
~21K SLoC