Struct VirtualPath 

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

SUMMARY: Hold a user‑facing path clamped to a virtual root ("/") over a PathBoundary.

DETAILS: virtualpath_display() shows rooted, forward‑slashed paths (e.g., "/a/b.txt"). Use virtual manipulation methods to compose paths while preserving clamping, then 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>

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

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

SUMMARY: Create the virtual root, creating the filesystem root if missing.

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

SUMMARY: Convert this VirtualPath back into a system‑facing StrictPath.

pub fn change_marker<NewMarker>(self) -> VirtualPath<NewMarker>

SUMMARY: Change the compile-time marker while keeping the virtual and strict views in sync.

WHEN TO USE:

• After authenticating/authorizing a user and granting them access to a virtual path
• When escalating or downgrading permissions (e.g., ReadOnly → ReadWrite)
• When reinterpreting a path’s domain (e.g., TempStorage → UserUploads)

WHEN NOT TO USE:

• When converting between path types - conversions preserve markers automatically
• When the current marker already matches your needs - no transformation needed
• When you haven’t verified authorization - NEVER change markers without checking permissions

PARAMETERS:

• _none_

RETURNS:

• VirtualPath<NewMarker>: Same clamped path encoded with the new marker.

ERRORS:

• _none_

SECURITY: This method performs no permission checks. Only elevate markers after verifying real authorization out-of-band.

EXAMPLE:

// Simulated authorization: verify user credentials before granting access
fn grant_user_access(user_token: &str, path: VirtualPath<GuestAccess>) -> Option<VirtualPath<UserAccess>> {
    if user_token == "valid-token-12345" {
        Some(path.change_marker())  // ✅ Only after token validation
    } else {
        None  // ❌ Invalid token
    }
}

let guest_path: VirtualPath<GuestAccess> = guest_root.virtual_join("docs/readme.md")?;
let user_path = grant_user_access("valid-token-12345", guest_path).expect("authorized");
assert_eq!(user_path.virtualpath_display().to_string(), "/docs/readme.md");

Type Safety Guarantee:

The following code fails to compile because you cannot pass a path with one marker type to a function expecting a different marker type. This compile-time check enforces that permission changes are explicit and cannot be bypassed accidentally.

fn require_editor(_: VirtualPath<EditorAccess>) {}
let guest_file = guest_root.virtual_join("docs/manual.txt").unwrap();
// ❌ Compile error: expected `VirtualPath<EditorAccess>`, found `VirtualPath<GuestAccess>`
require_editor(guest_file);

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

SUMMARY: Consume and return the VirtualRoot for its boundary (no directory creation).

RETURNS:

• Result<VirtualRoot<Marker>>: Virtual root anchored at the strict path’s directory.

ERRORS:

• StrictPathError::InvalidRestriction: Propagated from try_into_boundary when the strict path does not exist or is not a directory.

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

SUMMARY: Consume and return a VirtualRoot, creating the underlying directory if missing.

RETURNS:

• Result<VirtualRoot<Marker>>: Virtual root anchored at the strict path’s directory (created if necessary).

ERRORS:

• StrictPathError::InvalidRestriction: Propagated from try_into_boundary or directory creation failures wrapped in InvalidRestriction.

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

SUMMARY: Borrow the underlying system‑facing StrictPath (no allocation).

pub fn interop_path(&self) -> &OsStr

SUMMARY: Return the underlying system path as &OsStr for unavoidable third-party AsRef<Path> interop.

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

SUMMARY: Join a virtual path segment (virtual semantics) and re‑validate within the same restriction.

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

SUMMARY: Return the parent virtual path, or None at the virtual root.

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

SUMMARY: Return a new virtual path with file name changed, preserving clamping.

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

SUMMARY: Return a new virtual path with the extension changed, preserving clamping.

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

SUMMARY: Return the file name component of the virtual path, if any.

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

SUMMARY: Return the file stem of the virtual path, if any.

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

SUMMARY: Return the extension of the virtual path, if any.

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

SUMMARY: Return true if the virtual path starts with the given prefix (virtual semantics).

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

SUMMARY: Return true if the virtual path ends with the given suffix (virtual semantics).

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

SUMMARY: Return a Display wrapper that shows a rooted virtual path (e.g., `“/a/b.txt”).

pub fn exists(&self) -> bool

SUMMARY: Return true if the underlying system path exists.

pub fn is_file(&self) -> bool

SUMMARY: Return true if the underlying system path is a file.

pub fn is_dir(&self) -> bool

SUMMARY: Return true if the underlying system path is a directory.

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

SUMMARY: Return metadata for the underlying system path.

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

SUMMARY: Read 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>>

SUMMARY: Read raw bytes from the underlying system path (replacement for read_bytes).

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

SUMMARY: Read directory entries (discovery). Re‑join names with virtual_join(...) to preserve clamping.

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

SUMMARY: Write bytes to the underlying system path. Accepts &str, String, &[u8], Vec<u8], etc.

pub fn create_file(&self) -> Result<File>

SUMMARY: Create or truncate the file at this virtual path and return a writable handle.

PARAMETERS:

• none

RETURNS:

• std::fs::File: Writable handle scoped to the same virtual root restriction.

ERRORS:

• std::io::Error: Propagates operating-system errors when the parent directory is missing or file creation fails.

EXAMPLE:

let report = vroot.virtual_join("reports/summary.txt")?;
report.create_parent_dir_all()?;
let mut file = report.create_file()?;
file.write_all(b"summary")?;

pub fn open_file(&self) -> Result<File>

SUMMARY: Open the file at this virtual path in read-only mode.

PARAMETERS:

• none

RETURNS:

• std::fs::File: Read-only handle scoped to the same virtual root restriction.

ERRORS:

• std::io::Error: Propagates operating-system errors when the file is missing or inaccessible.

EXAMPLE:

let report = vroot.virtual_join("reports/summary.txt")?;
report.create_parent_dir_all()?;
report.write("summary")?;
let mut file = report.open_file()?;
let mut contents = String::new();
file.read_to_string(&mut contents)?;
assert_eq!(contents, "summary");

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

SUMMARY: Create all directories in the underlying system path if missing.

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

SUMMARY: Create the directory at this virtual location (non‑recursive). Fails if parent missing.

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

SUMMARY: Create only the immediate parent of this virtual path (non‑recursive). Ok(()) at virtual root.

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

SUMMARY: Recursively create all missing directories up to the immediate parent. Ok(()) at virtual root.

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

SUMMARY: Remove the file at the underlying system path.

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

SUMMARY: Remove the directory at the underlying system path.

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

SUMMARY: Recursively remove the directory and its contents at the underlying system path.

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

SUMMARY: Create a symlink at this virtual location pointing to target (same virtual root required).

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

SUMMARY: Create a hard link at this virtual location pointing to target (same virtual root).

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

SUMMARY: Rename/move within the same virtual root. Relative destinations are siblings; absolute are from root. Parents are not created automatically.

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

SUMMARY: Copy within the same virtual root. Relative destinations are siblings; absolute are from root. Parents are not created automatically. Returns bytes copied.

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>