1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
#![cfg_attr(doc, doc = include_str!("../README.md"))]
#![cfg_attr(feature = "nightly-safe-impl", feature(os_string_truncate))]
#![warn(
clippy::pedantic,
clippy::undocumented_unsafe_blocks,
clippy::unnecessary_safety_doc,
)]
#![allow(clippy::inline_always)]
use std::path::{Path, PathBuf};
use std::ffi::OsString;
mod inner;
pub use inner::{DirBuf, DirBufEntry};
macro_rules! impl_common {
($($x:tt)+) => {
impl $($x)+ {
/// Efficiently join a path with another.
///
/// The returned [`DirBufEntry`] reuses the underlying buffer,
/// and must be dropped before `join` can be called again.
/// The `DirBufEntry` holds a mutable reference to ensure
/// `join` cannot be called before the `DirBufEntry` is dropped.
///
/// If the path segment is coming from untrusted user data and
/// panics are undesirable, use [`try_join`](Self::try_join) instead.
///
/// # Panics
/// Panics if `path` is not a [trivial path](crate#trivial-paths).
///
/// # Performance
/// The overhead of the panic check is not insubstantial.
/// When multiple `join`s are used, this is still usually
/// faster than using a `PathBuf`, but if you know
/// the path is trivial (e.g. if it is a string literal),
/// consider using [`join_unchecked`](Self::join_unchecked) to remove this overhead.
///
#[inline]
#[must_use]
pub fn join(&mut self, path: impl AsRef<Path>) -> DirBufEntry<'_> {
match self.try_join_inner(path.as_ref()) {
Err(err) => panic!("unable to join paths: {err}"),
Ok(entry) => entry,
}
}
/// Variant of `join` optimized for string literals.
///
/// Semantic behavior is identical to [`Self::join`],
/// the only difference is performance.
///
/// For simple cases, this can have performance equivalent to
/// that of [`Self::join_unchecked`] without the unsafety,
/// but for more complex cases,
/// [`Self::join`] may be more performant.
///
/// It achieves this performance gain by leveraging inlining and
/// constant folding.
#[inline(always)]
#[must_use]
pub fn join_lit(&mut self, path: &str) -> DirBufEntry<'_> {
#[cfg(unix)]
{
if trivially_trivial(path) {
// SAFETY: just checked if it is trivial
return unsafe { self.join_inner(path.as_ref()) };
}
}
self.join(path)
}
/// Attempt to join a path with another.
///
/// The returned [`DirBufEntry`] reuses the underlying buffer,
/// and must be dropped before `join` can be called again.
/// The `DirBufEntry` holds a mutable reference to ensure
/// `join` cannot be called before the `DirBufEntry` is dropped.
///
/// # Errors
///
/// An error is returned if the path is not [trivial](crate#trivial-paths).
#[inline]
pub fn try_join(&mut self, path: impl AsRef<Path>) -> Result<DirBufEntry<'_>, JoinError> {
self.try_join_inner(path.as_ref())
}
/// Join a path to another without checking that it is trivial.
///
/// # Safety
/// `path` must be a [trivial path](crate#trivial-paths).
#[inline]
#[must_use]
pub unsafe fn join_unchecked(&mut self, path: impl AsRef<Path>) -> DirBufEntry<'_> {
// SAFETY: invariant guranteed by caller
unsafe { self.join_inner(path.as_ref()) }
}
#[inline]
fn try_join_inner(&mut self, path: &Path) -> Result<DirBufEntry<'_>, JoinError> {
check_trivial(path)?;
// SAFETY: we just checked if the path is trivial
unsafe { Ok(self.join_inner(path)) }
}
/// # Safety
/// The path must be a [trivial path](crate#trivial-paths).
#[must_use]
unsafe fn join_inner(&mut self, path: &Path) -> DirBufEntry<'_> {
// we call this before each operation instead of when `DirBufEntry` is dropped
// to make sure it is leak-safe.
// SAFETY: the path must be trivial by this function's precondition
unsafe {self.push(path)};
self.as_entry()
}
/// Borrow as a [`Path`].
pub fn as_path(&self) -> &Path {
self.as_ref()
}
}
}
}
impl DirBuf {
/// Initialize an empty `DirBuf` with the given capacity.
#[must_use]
pub fn with_capacity(capacity: usize) -> Self {
let buf = PathBuf::with_capacity(capacity);
DirBuf::new(buf)
}
/// Return the internal buffer, resetting it to its initial state first.
#[must_use]
pub fn into_inner(mut self) -> PathBuf {
let mut r = PathBuf::new();
// SAFETY: we consume the `DirBuf` so no further operations can be performed on it.
std::mem::swap(unsafe { self.reset() }, &mut r);
r
}
}
impl<T: AsRef<Path>> PartialEq<T> for DirBuf {
fn eq(&self, other: &T) -> bool {
self.as_ref() == other.as_ref()
}
}
impl<T: AsRef<Path>> PartialEq<T> for DirBufEntry<'_> {
fn eq(&self, other: &T) -> bool {
self.as_ref() == other.as_ref()
}
}
impl_common!(DirBuf);
impl_common!(<'buf> DirBufEntry<'buf>);
/// An error that occurred while attempting to join two paths.
#[derive(thiserror::Error, Debug, Clone)]
#[error("path {path:?} is not trivial due to {component:?}")]
pub struct JoinError {
path: PathBuf,
component: OsString,
}
#[cold]
fn cold<T>(x: T) -> T {
x
}
#[inline(always)]
const fn trivially_trivial(s: &str) -> bool {
let mut i = 0;
let bytes = s.as_bytes();
if bytes.is_empty() { return true; }
if bytes[0] == b'/' { return false; }
while i < bytes.len() {
if bytes[i] == b'.' {
return false;
}
i += 1;
}
true
}
#[inline]
fn check_trivial(path: &Path) -> Result<(), JoinError> {
use std::path::Component as Comp;
for comp in path.components() {
match &comp {
Comp::CurDir | Comp::Normal(..) => {
// ok, do nothing
},
_ => return cold(Err(JoinError{
path: path.into(),
component: comp.as_os_str().to_owned(),
})),
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn it_works() {
let mut d = DirBuf::new("foo");
assert_eq!(d.join("bar"), Path::new("foo/bar"));
assert_eq!(d, "foo");
}
}