Struct Path 

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

A validated path in StructFS.

Path components must be valid Unicode identifiers (per UAX#31) or numeric strings (for array indexing). This ensures paths can be used as identifiers in most programming languages.

Refinement of LLPath

Path is a validated refinement of the low-level LLPath: it wraps an LLPath whose every component is additionally guaranteed to be valid UTF-8 and a valid component grammar (identifier or numeric). Because a Path is an LLPath that has been validated, widening (as_ll / into_ll) is free, and narrowing (validate) is the single place validation happens. Components are stored as byte components, so Path -> LLPath never copies and structural ops (join/slice/strip_prefix) clone Bytes (reference-count bumps) rather than deep-copying Strings.

Implementations

impl Path

pub fn parse(s: &str) -> Result<Self, PathError>

Parse a path string, validating components.

Path Syntax

• Components are separated by /
• Empty components are ignored (normalizes // and trailing /)
• Each component must be a valid identifier or numeric string

Examples

use structfs_core_store::Path;

let path = Path::parse("users/123/name").unwrap();
assert_eq!(path.len(), 3);

// Trailing slashes are normalized
assert_eq!(Path::parse("foo/bar/").unwrap(), Path::parse("foo/bar").unwrap());

pub fn from_components(components: Vec<String>) -> Self

Create a path from pre-validated components.

Panics

Panics if any component is invalid. Use try_from_components for fallible construction.

pub fn try_from_components(components: Vec<String>) -> Result<Self, PathError>

Try to create a path from components, validating each.

pub fn validate_component( component: &str, position: usize, ) -> Result<(), PathError>

Validate a single path component against the StructFS grammar.

The grammar is shared with the compile-time path! macro via the structfs-path-validation crate: a component is a UAX#31 identifier (an underscore prefix is allowed when followed by more identifier characters) or a pure numeric string.

position is only used to build the error; pass 0 when validating a component in isolation.

pub fn is_empty(&self) -> bool

Check if this path is empty (root path).

pub fn len(&self) -> usize

Get the number of components.

pub fn iter(&self) -> impl Iterator<Item = &str>

Iterate over components as validated &strs.

pub fn join(&self, other: &Path) -> Path

Join this path with another.

pub fn child(&self, component: impl Into<PathComponent>) -> Path

Return a new path with the component appended.

pub fn push(&mut self, component: impl Into<PathComponent>)

Append a component in place.

pub fn has_prefix(&self, prefix: &Path) -> bool

Check if this path has the given prefix.

pub fn strip_prefix(&self, prefix: &Path) -> Option<Path>

Strip a prefix from this path.

Returns None if the prefix doesn’t match.

pub fn slice(&self, start: usize, end: usize) -> Path

Get a slice of components as a new path.

pub fn as_ll(&self) -> &LLPath

Borrow this path as its underlying LLPath — the free widening from the validated high-level contract to the opaque low-level one.

pub fn into_ll(self) -> LLPath

Consume this path into its underlying LLPath — free widening with no component copy.

pub fn validate(ll: LLPath) -> Result<Self, PathError>

Validate an LLPath into a Path — the single narrowing point where opaque bytes become a validated identifier path. Reuses the Bytes components (no copy); fails if any component is not valid UTF-8 or not a valid component grammar.

pub fn from_ll_unchecked(ll: LLPath) -> Self

Wrap an LLPath known to already satisfy the Path invariant, without re-validating. This is the byte-path analogue of from_validated_components: use it for paths that originated host-side from a Path (e.g. a write result path echoed back), so internal LL->HL hops don’t re-pay validation. Debug builds re-check as a safety net.

pub fn to_ll_path(&self) -> LLPath

Convert to an owned LL path (byte components).

Now a cheap clone (each component is a reference-counted Bytes); prefer as_ll/into_ll to avoid even that.

pub fn try_from_ll_path(ll_path: &[impl AsRef<[u8]>]) -> Result<Self, PathError>

Try to create from borrowed LL path components (byte slices).

Copies the components into owned Bytes and validates. Fails if any component is not valid UTF-8 or not a valid identifier. For an owned LLPath, prefer validate to reuse its Bytes.

Trait Implementations

impl Clone for Path

fn clone(&self) -> Path

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Path

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Path

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

Deserialize this value from the given Serde deserializer.

impl Display for Path

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

Formats the value using the given formatter.

impl Eq for Path

impl From<PathComponent> for Path

fn from(c: PathComponent) -> Self

Converts to this type from the input type.

impl FromIterator<PathComponent> for Path

fn from_iter<I: IntoIterator<Item = PathComponent>>(iter: I) -> Self

Creates a value from an iterator.

impl Hash for Path

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 Index<usize> for Path

type Output = str

The returned type after indexing.

fn index(&self, i: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Ord for Path

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

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Path

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Path

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 Serialize for Path

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

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Path