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
670 downloads per month
Used in rustyscript
19KB
254 lines
MaybePath
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
vs1.5002 ns
- Clone:
811.02 ps
vs2.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
vs1.6596 ns
- Clone:
3.8059 ns
vs3.2304 ns
- AsRef x1000:
2.1066 µs
vs3.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