Struct VirtualPath 

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

A user-facing path clamped to the virtual root path.

virtualpath_display() shows a rooted, forward-slashed path (e.g., "/a/b.txt"). Use virtual manipulation methods to compose paths while preserving clamping, and convert to StrictPath with unvirtual() for system-facing I/O.

Implementations

impl<Marker> VirtualPath<Marker>

pub fn with_root<P: AsRef<Path>>(root: P) -> Result<Self>

Create the virtual root ("/") for the given filesystem root.

Prefer this ergonomic constructor when you want to start from the virtual root for a given filesystem directory.

pub fn with_root_create<P: AsRef<Path>>(root: P) -> Result<Self>

Create the virtual root ("/"), creating the filesystem root if missing.

Creates the backing directory if needed.

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

Converts this VirtualPath back into a system-facing StrictPath.

pub fn try_into_root(self) -> VirtualRoot<Marker>

Consumes this VirtualPath and returns the VirtualRoot for its boundary.

Equivalent to self.unvirtual().try_into_boundary().virtualize() but without requiring intermediate variables. Does not create any directories.

pub fn try_into_root_create(self) -> VirtualRoot<Marker>

Consumes this VirtualPath and returns a VirtualRoot, creating the underlying directory if it does not exist.

If the boundary directory is somehow missing, it will be created before producing the VirtualRoot.

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

Borrows the underlying system-facing StrictPath (no allocation).

Use this to pass a &VirtualPath to APIs that accept &StrictPath.

pub fn interop_path(&self) -> &OsStr

Returns the underlying system path as &OsStr for AsRef<Path> interop.

pub fn virtual_join<P: AsRef<Path>>(&self, path: P) -> Result<Self>

Safely joins a virtual path segment (virtual semantics) and re-validates.

pub fn virtualpath_parent(&self) -> Result<Option<Self>>

Returns the parent virtual path, or None if at the virtual root.

pub fn virtualpath_with_file_name<S: AsRef<OsStr>>( &self, file_name: S, ) -> Result<Self>

Returns a new VirtualPath with the file name changed, preserving clamping.

pub fn virtualpath_with_extension<S: AsRef<OsStr>>( &self, extension: S, ) -> Result<Self>

Returns a new VirtualPath with the extension changed, preserving clamping.

pub fn virtualpath_file_name(&self) -> Option<&OsStr>

Returns the file name component of the virtual path, if any.

pub fn virtualpath_file_stem(&self) -> Option<&OsStr>

Returns the file stem of the virtual path, if any.

pub fn virtualpath_extension(&self) -> Option<&OsStr>

Returns the extension of the virtual path, if any.

pub fn virtualpath_starts_with<P: AsRef<Path>>(&self, p: P) -> bool

Returns true if the virtual path starts with the given prefix (virtual semantics).

pub fn virtualpath_ends_with<P: AsRef<Path>>(&self, p: P) -> bool

Returns true if the virtual path ends with the given suffix (virtual semantics).

pub fn virtualpath_display(&self) -> VirtualPathDisplay<'_, Marker>

Returns a Display wrapper that shows a rooted virtual path (e.g., "/a/b.txt").

pub fn exists(&self) -> bool

Returns true if the underlying system path exists.

pub fn is_file(&self) -> bool

Returns true if the underlying system path is a file.

pub fn is_dir(&self) -> bool

Returns true if the underlying system path is a directory.

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

Returns metadata for the underlying system path.

pub fn read_to_string(&self) -> Result<String>

Reads the file contents as String from the underlying system path.

pub fn read_bytes(&self) -> Result<Vec<u8>>

👎Deprecated since 0.1.0-alpha.5: Use read() instead

Reads the file contents as raw bytes from the underlying system path.

pub fn write_bytes(&self, data: &[u8]) -> Result<()>

👎Deprecated since 0.1.0-alpha.5: Use write(…) instead

Writes raw bytes to the underlying system path.

pub fn write_string(&self, data: &str) -> Result<()>

👎Deprecated since 0.1.0-alpha.5: Use write(…) instead

Writes a UTF-8 string to the underlying system path.

pub fn read(&self) -> Result<Vec<u8>>

Reads the file contents as raw bytes (replacement for read_bytes).

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

Reads the directory entries at the underlying system path (like std::fs::read_dir).

This is intended for discovery in the virtual space. Collect each entry’s file name via entry.file_name() and re‑join with virtual_join(...) to preserve clamping before I/O.

pub fn write<C: AsRef<[u8]>>(&self, contents: C) -> Result<()>

Writes data to the underlying system path. Accepts &str, String, &[u8], Vec<u8], etc.

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

Creates all directories in the underlying system path if missing.

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

Creates the directory at this virtual location (non-recursive).

Mirrors std::fs::create_dir and fails if the parent does not exist.

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

Creates only the immediate parent directory of this virtual path (non-recursive).

Acts in the virtual dimension: the parent is derived via virtualpath_parent() and then created on the underlying system path. Returns Ok(()) at virtual root.

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

Recursively creates all missing directories up to the immediate parent of this virtual path.

Acts in the virtual dimension; returns Ok(()) at virtual root.

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

Removes the file at the underlying system path.

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

Removes the directory at the underlying system path.

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

Recursively removes the directory and its contents at the underlying system path.

pub fn virtual_rename<P: AsRef<Path>>(&self, dest: P) -> Result<Self>

Renames or moves this virtual path to a new location within the same virtual root.

Destination paths are resolved in virtual space:

• Relative inputs are interpreted as siblings (resolved against the virtual parent).
• Absolute virtual inputs are treated as requests from the virtual root.

Clamping and boundary checks are enforced by virtual joins. No parent directories are created implicitly; call create_parent_dir_all() beforehand if needed.

pub fn virtual_copy<P: AsRef<Path>>(&self, dest: P) -> Result<Self>

Copies this virtual path to a new location within the same virtual root.

Destination paths are resolved in virtual space:

• Relative inputs are interpreted as siblings (resolved against the virtual parent).
• Absolute virtual inputs are treated as requests from the virtual root.

Clamping and boundary checks are enforced by virtual joins. No parent directories are created implicitly; call create_parent_dir_all() beforehand if needed. Returns the destination VirtualPath on success.

Trait Implementations

impl<Marker: Clone> Clone for VirtualPath<Marker>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Marker> Debug for VirtualPath<Marker>

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

Formats the value using the given formatter.

impl<Marker> Hash for VirtualPath<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 VirtualPath<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<StrictPath<Marker>> for VirtualPath<Marker>

fn eq(&self, other: &StrictPath<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<T: AsRef<Path>, Marker> PartialEq<T> for VirtualPath<Marker>

fn eq(&self, other: &T) -> 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<VirtualPath<Marker>> for StrictPath<Marker>

fn eq(&self, other: &VirtualPath<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 VirtualPath<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<T: AsRef<Path>, Marker> PartialOrd<T> for VirtualPath<Marker>

fn partial_cmp(&self, other: &T) -> 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 VirtualPath<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 VirtualPath<Marker>