Add API docs for RelPath (#38923)

Also reduce the use of `unsafe` in that module.

Release Notes:

- N/A
This commit is contained in:
Max Brunsfeld
2025-09-26 00:49:10 +00:00
committed by GitHub
parent a5683f3541
commit 7980dbdaea
+63 -21
View File
@@ -9,18 +9,40 @@ use std::{
sync::Arc, sync::Arc,
}; };
/// A file system path that is guaranteed to be relative and normalized.
///
/// This type can be used to represent paths in a uniform way, regardless of
/// whether they refer to Windows or POSIX file systems, and regardless of
/// the host platform.
///
/// Internally, paths are stored in POSIX ('/'-delimited) format, but they can
/// be displayed in either POSIX or Windows format.
///
/// Relative paths are also guaranteed to be valid unicode.
#[repr(transparent)] #[repr(transparent)]
#[derive(PartialEq, Eq, Hash, Serialize)] #[derive(PartialEq, Eq, Hash, Serialize)]
pub struct RelPath(str); pub struct RelPath(str);
/// An owned representation of a file system path that is guaranteed to be
/// relative and normalized.
///
/// This type is to [`RelPath`] as [`std::path::PathBuf`] is to [`std::path::Path`]
#[derive(Clone, Serialize, Deserialize)] #[derive(Clone, Serialize, Deserialize)]
pub struct RelPathBuf(String); pub struct RelPathBuf(String);
impl RelPath { impl RelPath {
/// Creates an empty [`RelPath`].
pub fn empty() -> &'static Self { pub fn empty() -> &'static Self {
unsafe { Self::new_unchecked("") } Self::new_unchecked("")
} }
/// Converts a path with a given style into a [`RelPath`].
///
/// Returns an error if the path is absolute, or is not valid unicode.
///
/// This method will normalize the path by removing `.` components,
/// processing `..` components, and removing trailing separators. It does
/// not allocate unless it's necessary to reformat the path.
#[track_caller] #[track_caller]
pub fn new<'a>(path: &'a Path, path_style: PathStyle) -> Result<Cow<'a, Self>> { pub fn new<'a>(path: &'a Path, path_style: PathStyle) -> Result<Cow<'a, Self>> {
let mut path = path.to_str().context("non utf-8 path")?; let mut path = path.to_str().context("non utf-8 path")?;
@@ -49,7 +71,7 @@ impl RelPath {
} }
let mut result = match string { let mut result = match string {
Cow::Borrowed(string) => Cow::Borrowed(unsafe { Self::new_unchecked(string) }), Cow::Borrowed(string) => Cow::Borrowed(Self::new_unchecked(string)),
Cow::Owned(string) => Cow::Owned(RelPathBuf(string)), Cow::Owned(string) => Cow::Owned(RelPathBuf(string)),
}; };
@@ -67,7 +89,7 @@ impl RelPath {
return Err(anyhow!("path is not relative: {result:?}")); return Err(anyhow!("path is not relative: {result:?}"));
} }
} }
other => normalized.push(&RelPath::unix(other)?), other => normalized.push(RelPath::new_unchecked(other)),
} }
} }
result = Cow::Owned(normalized) result = Cow::Owned(normalized)
@@ -76,6 +98,10 @@ impl RelPath {
Ok(result) Ok(result)
} }
/// Converts a path that is already normalized and uses '/' separators
/// into a [`RelPath`] .
///
/// Returns an error if the path is not already in the correct format.
#[track_caller] #[track_caller]
pub fn unix<S: AsRef<Path> + ?Sized>(path: &S) -> anyhow::Result<&Self> { pub fn unix<S: AsRef<Path> + ?Sized>(path: &S) -> anyhow::Result<&Self> {
let path = path.as_ref(); let path = path.as_ref();
@@ -85,7 +111,8 @@ impl RelPath {
} }
} }
unsafe fn new_unchecked(s: &str) -> &Self { fn new_unchecked(s: &str) -> &Self {
// Safety: `RelPath` is a transparent wrapper around `str`.
unsafe { &*(s as *const str as *const Self) } unsafe { &*(s as *const str as *const Self) }
} }
@@ -140,7 +167,7 @@ impl RelPath {
} }
if let Some(suffix) = self.0.strip_prefix(&other.0) { if let Some(suffix) = self.0.strip_prefix(&other.0) {
if let Some(suffix) = suffix.strip_prefix('/') { if let Some(suffix) = suffix.strip_prefix('/') {
return Ok(unsafe { Self::new_unchecked(suffix) }); return Ok(Self::new_unchecked(suffix));
} else if suffix.is_empty() { } else if suffix.is_empty() {
return Ok(Self::empty()); return Ok(Self::empty());
} }
@@ -173,29 +200,31 @@ impl RelPath {
} else { } else {
Cow::Owned(format!("{}/{}", &self.0, &other.0)) Cow::Owned(format!("{}/{}", &self.0, &other.0))
}; };
Arc::from(unsafe { Self::new_unchecked(result.as_ref()) }) Arc::from(Self::new_unchecked(result.as_ref()))
}
pub fn to_proto(&self) -> String {
self.as_unix_str().to_owned()
} }
pub fn to_rel_path_buf(&self) -> RelPathBuf { pub fn to_rel_path_buf(&self) -> RelPathBuf {
RelPathBuf(self.0.to_string()) RelPathBuf(self.0.to_string())
} }
pub fn from_proto(path: &str) -> Result<Arc<Self>> {
Ok(Arc::from(Self::unix(path)?))
}
pub fn as_unix_str(&self) -> &str {
&self.0
}
pub fn into_arc(&self) -> Arc<Self> { pub fn into_arc(&self) -> Arc<Self> {
Arc::from(self) Arc::from(self)
} }
/// Convert the path into the wire representation.
pub fn to_proto(&self) -> String {
self.as_unix_str().to_owned()
}
/// Load the path from its wire representation.
pub fn from_proto(path: &str) -> Result<Arc<Self>> {
Ok(Arc::from(Self::unix(path)?))
}
/// Convert the path into a string with the given path style.
///
/// Whenever a path is presented to the user, it should be converted to
/// a string via this method.
pub fn display(&self, style: PathStyle) -> Cow<'_, str> { pub fn display(&self, style: PathStyle) -> Cow<'_, str> {
match style { match style {
PathStyle::Posix => Cow::Borrowed(&self.0), PathStyle::Posix => Cow::Borrowed(&self.0),
@@ -203,6 +232,19 @@ impl RelPath {
} }
} }
/// Get the internal unix-style representation of the path.
///
/// This should not be shown to the user.
pub fn as_unix_str(&self) -> &str {
&self.0
}
/// Interprets the path as a [`std::path::Path`], suitable for file system calls.
///
/// This is guaranteed to be a valid path regardless of the host platform, because
/// the `/` is accepted as a path separator on windows.
///
/// This should not be shown to the user.
pub fn as_std_path(&self) -> &Path { pub fn as_std_path(&self) -> &Path {
Path::new(&self.0) Path::new(&self.0)
} }
@@ -271,7 +313,7 @@ impl RelPathBuf {
} }
pub fn as_rel_path(&self) -> &RelPath { pub fn as_rel_path(&self) -> &RelPath {
unsafe { RelPath::new_unchecked(self.0.as_str()) } RelPath::new_unchecked(self.0.as_str())
} }
pub fn set_extension(&mut self, extension: &str) -> bool { pub fn set_extension(&mut self, extension: &str) -> bool {
@@ -340,7 +382,7 @@ const SEPARATOR: char = '/';
impl<'a> RelPathComponents<'a> { impl<'a> RelPathComponents<'a> {
pub fn rest(&self) -> &'a RelPath { pub fn rest(&self) -> &'a RelPath {
unsafe { RelPath::new_unchecked(self.0) } RelPath::new_unchecked(self.0)
} }
} }
@@ -374,7 +416,7 @@ impl<'a> Iterator for RelPathAncestors<'a> {
} else { } else {
self.0 = None; self.0 = None;
} }
Some(unsafe { RelPath::new_unchecked(result) }) Some(RelPath::new_unchecked(result))
} }
} }