Struct SafeRelativePathBuf 

pub struct SafeRelativePathBuf(/* private fields */);

An owned relative path that statically cannot escape its parent.

SafeRelativePathBuf is to SafeRelativePath what PathBuf is to Path in the standard library: same guarantee, same string form, owned instead of borrowed. Construct one by parsing a string with str::parse (or from_relative_path), or deserialise one from anywhere serde reaches.

All methods on SafeRelativePath are reachable through Deref, so try_join, to_full_path, safe_parent, and friends are all in scope without an explicit reborrow.

Example

use zenops_safe_relative_path::SafeRelativePathBuf;

let p: SafeRelativePathBuf = "configs/app.toml".parse().unwrap();
assert_eq!(p.as_str(), "configs/app.toml");
assert_eq!(p.safe_parent().unwrap().as_str(), "configs");

Implementations

impl SafeRelativePathBuf

pub fn from_relative_path<P>(v: &P) -> Result<Self, Error>

where P: AsRef<RelativePath> + ?Sized,

Parse and validate an arbitrary path into a SafeRelativePathBuf.

Same contract as SafeRelativePath::from_relative_path — rejects any path containing .. — but returns an owned buffer. Most callers can reach for str::parse instead, which forwards here.

Methods from Deref<Target = SafeRelativePath>

pub fn to_safe_relative_path_buf(&self) -> SafeRelativePathBuf

Copy this borrowed path into an owned SafeRelativePathBuf.

pub fn normalize_safe(&self) -> SafeRelativePathBuf

Collapse . components and produce a normalised owned path.

Unlike Path::canonicalize this is purely lexical — no filesystem access. A SafeRelativePath cannot contain .. segments, so normalisation only ever drops . components.

Example

use zenops_safe_relative_path::SafeRelativePath;

let p = SafeRelativePath::from_relative_path("a/./b").unwrap();
assert_eq!(p.normalize_safe().as_str(), "a/b");

pub fn safe_join( &self, path: impl AsRef<SafeRelativePath>, ) -> SafeRelativePathBuf

Join another already-safe path onto this one.

The infallible counterpart to try_join: both sides are already known to be safe, so the join cannot introduce traversal and no validation is needed.

Example

use zenops_safe_relative_path::srpath;

let joined = srpath!("config").safe_join(srpath!("app.toml"));
assert_eq!(joined.as_str(), "config/app.toml");

pub fn try_join( &self, path: impl AsRef<RelativePath>, ) -> Result<SafeRelativePathBuf, Error>

Join another path onto this one, returning an error if the joined segment would escape.

This is the safe counterpart to Path::join for inputs that come from configuration or another untrusted source: the result is still a relative path contained by the original base.

Example

use zenops_safe_relative_path::srpath;

let base = srpath!("config");
assert_eq!(
    base.try_join("app.toml").unwrap().as_str(),
    "config/app.toml",
);
assert!(base.try_join("../../etc/passwd").is_err());

pub fn as_str(&self) -> &str

View the path as a string slice.

pub fn to_full_path(&self, base: impl AsRef<Path>) -> PathBuf

Resolve this relative path against base to produce an absolute PathBuf.

Use this at the edge of the program, when a SafeRelativePath finally needs to be handed to a filesystem call against a known root — typically $HOME or $XDG_CONFIG_HOME. The result is base followed by this path’s components, with no .. traversal between them.

Example

use std::path::Path;
use zenops_safe_relative_path::srpath;

let abs = srpath!("config/app.toml").to_full_path(Path::new("/home/ada"));
assert_eq!(abs, Path::new("/home/ada/config/app.toml"));

pub fn safe_parent(&self) -> Option<&SafeRelativePath>

Return the parent path, or None if there is no parent.

The parent of a SafeRelativePath is itself a SafeRelativePath — dropping a final component can never introduce traversal.

Example

use zenops_safe_relative_path::srpath;

assert_eq!(srpath!("a/b/c").safe_parent().unwrap().as_str(), "a/b");
assert!(srpath!("").safe_parent().is_none());

Trait Implementations

impl AsRef<OsStr> for SafeRelativePathBuf

fn as_ref(&self) -> &OsStr

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<RelativePath> for SafeRelativePathBuf

fn as_ref(&self) -> &RelativePath

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<SafeRelativePath> for SafeRelativePathBuf

fn as_ref(&self) -> &SafeRelativePath

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for SafeRelativePathBuf

fn clone(&self) -> SafeRelativePathBuf

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SafeRelativePathBuf

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for SafeRelativePathBuf

type Target = SafeRelativePath

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for SafeRelativePathBuf

fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for SafeRelativePathBuf

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for SafeRelativePathBuf

impl<'a> From<&'a SafeRelativePath> for SafeRelativePathBuf

fn from(value: &'a SafeRelativePath) -> Self

Converts to this type from the input type.

impl From<SafeRelativePathBuf> for Arc<SafeRelativePath>

fn from(value: SafeRelativePathBuf) -> Self

Converts to this type from the input type.

impl FromStr for SafeRelativePathBuf

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for SafeRelativePathBuf

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SafeRelativePathBuf

fn cmp(&self, other: &SafeRelativePathBuf) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SafeRelativePathBuf

fn eq(&self, other: &SafeRelativePathBuf) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for SafeRelativePathBuf

fn partial_cmp(&self, other: &SafeRelativePathBuf) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for SafeRelativePathBuf

fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SafeRelativePathBuf