Struct SinglePathComponent 

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

A path that is exactly one segment — no separators, no traversal.

Narrower than SafeRelativePath: where SafeRelativePath allows any number of components as long as none of them are .., SinglePathComponent permits exactly one. Reach for it when a value has to be a single name in a flat namespace — a package key, a configuration map key, a directory entry — and you want the type system to enforce that.

Derefs to SafeRelativePath, so a SinglePathComponent can be handed to anything that takes &SafeRelativePath without conversion.

Example

use zenops_safe_relative_path::SinglePathComponent;

assert!(SinglePathComponent::try_new("zsh").is_ok());

// More than one component — rejected.
assert!(SinglePathComponent::try_new("zsh/init.sh").is_err());
// Traversal — also rejected.
assert!(SinglePathComponent::try_new("..").is_err());

Implementations

impl SinglePathComponent

pub fn try_new(v: &str) -> Result<Self, Error>

Try to wrap a string as a SinglePathComponent.

Fails on anything containing /, anything with .. traversal, and the empty string.

pub fn as_safe_relative_path(&self) -> &SafeRelativePath

View this component as a SafeRelativePath.

SinglePathComponent already Derefs to SafeRelativePath, so most call sites don’t need this directly — it’s exposed for places where an explicit conversion reads more clearly than a reborrow.

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<SafeRelativePath> for SinglePathComponent

fn as_ref(&self) -> &SafeRelativePath

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

impl Clone for SinglePathComponent

fn clone(&self) -> SinglePathComponent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SinglePathComponent

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

Formats the value using the given formatter.

impl Deref for SinglePathComponent

type Target = SafeRelativePath

The resulting type after dereferencing.

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

Dereferences the value.

impl<'de> Deserialize<'de> for SinglePathComponent

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

Deserialize this value from the given Serde deserializer.

impl Display for SinglePathComponent

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

Formats the value using the given formatter.

impl Eq for SinglePathComponent

impl Hash for SinglePathComponent

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 SinglePathComponent

fn cmp(&self, other: &SinglePathComponent) -> 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 SinglePathComponent

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for SinglePathComponent

fn partial_cmp(&self, other: &SinglePathComponent) -> 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 StructuralPartialEq for SinglePathComponent