Struct VirtualRoot 

pub struct VirtualRoot<Marker = ()> { /* private fields */ }

A user-facing virtual root that produces VirtualPath values.

Implementations

impl<Marker> VirtualRoot<Marker>

pub fn try_new<P: AsRef<Path>>(root_path: P) -> Result<Self>

Creates a VirtualRoot from an existing directory.

Uses AsRef<Path> for maximum ergonomics, including direct TempDir support for clean shadowing patterns:

use strict_path::VirtualRoot;
let tmp_dir = tempfile::tempdir()?;
let tmp_dir = VirtualRoot::<()>::try_new(tmp_dir)?; // Clean variable shadowing

pub fn metadata(&self) -> Result<Metadata>

Returns filesystem metadata for the underlying root directory.

pub fn virtual_symlink(&self, link_path: &VirtualPath<Marker>) -> Result<()>

Creates a symbolic link at link_path that points to this VirtualRoot’s underlying directory.

pub fn virtual_hard_link(&self, link_path: &VirtualPath<Marker>) -> Result<()>

Creates a hard link at link_path that points to this VirtualRoot’s underlying directory.

pub fn read_dir(&self) -> Result<ReadDir>

Reads the directory entries at the virtual root (like std::fs::read_dir).

This is intended for discovery. Prefer collecting each entry’s file name via entry.file_name() and re-joining using virtual_join(...) (or strict_join(...) after converting) before performing I/O on child paths.

pub fn remove_dir(&self) -> Result<()>

Removes the underlying root directory (non-recursive).

Equivalent to std::fs::remove_dir(root). Fails if the directory is not empty.

pub fn remove_dir_all(&self) -> Result<()>

Recursively removes the underlying root directory and all its contents.

Equivalent to std::fs::remove_dir_all(root).

pub fn try_new_create<P: AsRef<Path>>(root_path: P) -> Result<Self>

Creates the directory if missing, then returns a VirtualRoot.

Uses AsRef<Path> for maximum ergonomics, including direct TempDir support for clean shadowing patterns:

use strict_path::VirtualRoot;
let tmp_dir = tempfile::tempdir()?;
let tmp_dir = VirtualRoot::<()>::try_new_create(tmp_dir)?; // Clean variable shadowing

pub fn virtual_join<P: AsRef<Path>>( &self, candidate_path: P, ) -> Result<VirtualPath<Marker>>

Joins a path to this virtual root, producing a clamped VirtualPath.

Preserves the virtual root through clamping and validates against the restriction. May return an error if resolution (e.g., via symlinks) would escape the restriction.

pub fn interop_path(&self) -> &OsStr

Returns the virtual root path for interop with AsRef<Path> APIs.

This provides allocation-free, OS-native string access to the virtual root for use with standard library APIs that accept AsRef<Path>.

pub fn exists(&self) -> bool

Returns true if the underlying path boundary root exists.

pub fn as_unvirtual(&self) -> &PathBoundary<Marker>

Returns a reference to the underlying PathBoundary.

This allows access to path boundary-specific operations like strictpath_display() while maintaining the borrowed relationship.

pub fn unvirtual(self) -> PathBoundary<Marker>

Consumes this VirtualRoot and returns the underlying PathBoundary.

This provides symmetry with PathBoundary::virtualize() and allows conversion back to the path boundary representation when virtual semantics are no longer needed.

Trait Implementations

impl<Marker> AsRef<Path> for VirtualRoot<Marker>

fn as_ref(&self) -> &Path

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

impl<Marker: Clone> Clone for VirtualRoot<Marker>

fn clone(&self) -> VirtualRoot<Marker>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Marker> Debug for VirtualRoot<Marker>

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

Formats the value using the given formatter.

impl<Marker> Display for VirtualRoot<Marker>

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

Formats the value using the given formatter.

impl<Marker: Default> FromStr for VirtualRoot<Marker>

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

Parse a VirtualRoot from a string path for universal ergonomics.

Creates the directory if it doesn’t exist, enabling seamless integration with any string-parsing context (clap, config files, environment variables, etc.):

let temp_dir = tempfile::tempdir()?;
let virtual_path = temp_dir.path().join("virtual_dir");
let vroot: VirtualRoot<()> = virtual_path.to_string_lossy().parse()?;
assert!(virtual_path.exists());

type Err = StrictPathError

The associated error which can be returned from parsing.

impl<Marker> Hash for VirtualRoot<Marker>

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<Marker> Ord for VirtualRoot<Marker>

fn cmp(&self, other: &Self) -> 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<Marker> PartialEq<&Path> for VirtualRoot<Marker>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialEq<Path> for VirtualRoot<Marker>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialEq<PathBoundary<Marker>> for VirtualRoot<Marker>

fn eq(&self, other: &PathBoundary<Marker>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialEq<PathBuf> for VirtualRoot<Marker>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialEq<VirtualRoot<Marker>> for PathBoundary<Marker>

fn eq(&self, other: &VirtualRoot<Marker>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialEq for VirtualRoot<Marker>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialOrd<&Path> for VirtualRoot<Marker>

fn partial_cmp(&self, other: &&Path) -> 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<Marker> PartialOrd<Path> for VirtualRoot<Marker>

fn partial_cmp(&self, other: &Path) -> 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<Marker> PartialOrd<PathBuf> for VirtualRoot<Marker>

fn partial_cmp(&self, other: &PathBuf) -> 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<Marker> PartialOrd for VirtualRoot<Marker>

fn partial_cmp(&self, other: &Self) -> 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<Marker> Eq for VirtualRoot<Marker>