Struct PathElementGeneric 

pub struct PathElementGeneric<'a, S> { /* private fields */ }

A validated, normalized single path element.

PathElementGeneric takes a raw path element name, validates it (rejecting empty strings, ., .., and /), normalizes it through a Unicode normalization pipeline, and computes an OS-compatible presentation form. All three views – original, normalized, and OS-compatible – are accessible without re-computation.

The type parameter S controls case sensitivity:

• CaseSensitive – compile-time case-sensitive (alias: PathElementCS).
• CaseInsensitive – compile-time case-insensitive (alias: PathElementCI).
• CaseSensitivity – runtime-selected (alias: PathElement).

Equality, ordering, and hashing are based on the normalized form, so two PathElementGeneric values with different originals but the same normalized form are considered equal.

Where possible, the normalized and OS-compatible forms borrow from the original string to avoid allocation.

Implementations

impl<'a> PathElementGeneric<'a, CaseSensitive>

pub fn new(original: impl Into<Cow<'a, str>>) -> Result<Self>

Creates a new case-sensitive path element from a string.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

let pe = PathElementCS::new("Hello.txt")?;
assert_eq!(pe.normalized(), "Hello.txt"); // case preserved

pub fn from_bytes(original: impl Into<Cow<'a, [u8]>>) -> Result<Self>

Creates a new case-sensitive path element from a byte slice.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

pub fn from_os_str(original: impl Into<Cow<'a, OsStr>>) -> Result<Self>

Available on crate feature std only.

Creates a new case-sensitive path element from an OS string.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

impl<'a> PathElementGeneric<'a, CaseInsensitive>

pub fn new(original: impl Into<Cow<'a, str>>) -> Result<Self>

Creates a new case-insensitive path element from a string.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

let pe = PathElementCI::new("Hello.txt")?;
assert_eq!(pe.normalized(), "hello.txt"); // case-folded

pub fn from_bytes(original: impl Into<Cow<'a, [u8]>>) -> Result<Self>

Creates a new case-insensitive path element from a byte slice.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

pub fn from_os_str(original: impl Into<Cow<'a, OsStr>>) -> Result<Self>

Available on crate feature std only.

Creates a new case-insensitive path element from an OS string.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

impl<'a> PathElementGeneric<'a, CaseSensitivity>

pub fn new( original: impl Into<Cow<'a, str>>, case_sensitivity: impl Into<CaseSensitivity>, ) -> Result<Self>

Creates a new path element with runtime-selected case sensitivity.

Errors

Returns Error if the name is invalid.

pub fn from_bytes( original: impl Into<Cow<'a, [u8]>>, case_sensitivity: impl Into<CaseSensitivity>, ) -> Result<Self>

Creates a new path element from a byte slice with runtime-selected case sensitivity.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

pub fn from_os_str( original: impl Into<Cow<'a, OsStr>>, case_sensitivity: impl Into<CaseSensitivity>, ) -> Result<Self>

Available on crate feature std only.

Creates a new path element from an OS string with runtime-selected case sensitivity.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

pub fn new_cs(original: impl Into<Cow<'a, str>>) -> Result<Self>

Convenience constructor for a case-sensitive PathElement.

Errors

Returns Error if the name is invalid.

pub fn new_ci(original: impl Into<Cow<'a, str>>) -> Result<Self>

Convenience constructor for a case-insensitive PathElement.

Errors

Returns Error if the name is invalid.

pub fn from_bytes_cs(original: impl Into<Cow<'a, [u8]>>) -> Result<Self>

Convenience constructor for a case-sensitive PathElement from bytes.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid.

pub fn from_bytes_ci(original: impl Into<Cow<'a, [u8]>>) -> Result<Self>

Convenience constructor for a case-insensitive PathElement from bytes.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid.

pub fn from_os_str_cs(original: impl Into<Cow<'a, OsStr>>) -> Result<Self>

Available on crate feature std only.

Convenience constructor for a case-sensitive PathElement from an OS string.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid.

pub fn from_os_str_ci(original: impl Into<Cow<'a, OsStr>>) -> Result<Self>

Available on crate feature std only.

Convenience constructor for a case-insensitive PathElement from an OS string.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid.

impl<'a, S> PathElementGeneric<'a, S>

where for<'s> CaseSensitivity: From<&'s S>,

pub fn from_bytes_with_case_sensitivity( original: impl Into<Cow<'a, [u8]>>, case_sensitivity: impl Into<S>, ) -> Result<Self>

Creates a new path element from a byte slice with an explicit case-sensitivity marker.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

This is the most general byte-input constructor. The typed aliases (PathElementCS::from_bytes(), PathElementCI::from_bytes()) and the runtime-dynamic constructors delegate to this method.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

pub fn from_os_str_with_case_sensitivity( original: impl Into<Cow<'a, OsStr>>, case_sensitivity: impl Into<S>, ) -> Result<Self>

Available on crate feature std only.

Creates a new path element from an OS string with an explicit case-sensitivity marker.

Invalid UTF-8 is accepted; see Normalization pipeline step 0.

Errors

Returns Error if the name is invalid (empty, ., .., or contains /).

pub fn with_case_sensitivity( original: impl Into<Cow<'a, str>>, case_sensitivity: impl Into<S>, ) -> Result<Self>

Creates a new path element with an explicit case-sensitivity marker.

This is the most general string constructor. The typed aliases (PathElementCS::new(), PathElementCI::new()) and the runtime-dynamic constructors delegate to this method.

Errors

Returns Error if the name is invalid (empty after normalization, ., .., or contains /).

pub fn case_sensitivity(&self) -> CaseSensitivity

Returns the case sensitivity of this path element as a CaseSensitivity enum.

impl<'a, S> PathElementGeneric<'a, S>

pub fn original(&self) -> &str

Returns the original input string, before any normalization.

let pe = PathElementCS::new("  Hello.txt  ")?;
assert_eq!(pe.original(), "  Hello.txt  ");
assert_eq!(pe.normalized(), "Hello.txt");

pub fn into_original(self) -> Cow<'a, str>

Consumes self and returns the original input string.

pub fn is_normalized(&self) -> bool

Returns true if the normalized form is identical to the original.

When this returns true, no allocation was needed for the normalized form.

assert!(PathElementCS::new("hello.txt")?.is_normalized());
assert!(!PathElementCS::new("  hello.txt  ")?.is_normalized());

pub fn normalized(&self) -> &str

Returns the normalized form of the path element name.

This is the canonical representation used for equality comparisons, ordering, and hashing. In case-sensitive mode it is NFC-normalized; in case-insensitive mode it is additionally case-folded.

pub fn into_normalized(self) -> Cow<'a, str>

Consumes self and returns the normalized form as a Cow.

Returns Cow::Borrowed when the normalized form is a substring of the original and the original was itself borrowed.

pub fn is_os_compatible(&self) -> bool

Returns true if the OS-compatible form is identical to the original.

pub fn os_compatible(&self) -> &str

Returns the OS-compatible presentation form of the path element name.

let pe = PathElementCS::new("hello.txt")?;
assert_eq!(pe.os_compatible(), "hello.txt");

pub fn into_os_compatible(self) -> Cow<'a, str>

Consumes self and returns the OS-compatible form as a Cow<str>.

pub fn os_str(&self) -> &OsStr

Available on crate feature std only.

Returns the OS-compatible form as an OsStr reference.

pub fn into_os_str(self) -> Cow<'a, OsStr>

Available on crate feature std only.

Consumes self and returns the OS-compatible form as a Cow<OsStr>.

pub fn is_borrowed(&self) -> bool

Returns true if the original string is borrowed (not owned).

let borrowed = PathElementCS::new(Cow::Borrowed("hello"))?;
assert!(borrowed.is_borrowed());

let owned = PathElementCS::new(Cow::<str>::Owned("hello".into()))?;
assert!(!owned.is_borrowed());

pub fn is_owned(&self) -> bool

Returns true if the original string is owned (not borrowed).

pub fn into_owned(self) -> PathElementGeneric<'static, S>

Consumes self and returns an equivalent PathElementGeneric with a 'static lifetime by cloning the original string if it was borrowed.

Trait Implementations

impl<'a, S: Clone> Clone for PathElementGeneric<'a, S>

fn clone(&self) -> PathElementGeneric<'a, S>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<S: Debug> Debug for PathElementGeneric<'_, S>

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

Formats the value using the given formatter.

impl<'a> From<PathElementGeneric<'a, CaseInsensitive>> for PathElement<'a>

Converts a compile-time case-insensitive element into a runtime-dynamic PathElement.

fn from(pe: PathElementCI<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<PathElementGeneric<'a, CaseSensitive>> for PathElement<'a>

Converts a compile-time case-sensitive element into a runtime-dynamic PathElement.

fn from(pe: PathElementCS<'a>) -> Self

Converts to this type from the input type.

impl<S> Ord for PathElementGeneric<'_, S>

where for<'s> CaseSensitivity: From<&'s S>,

Compares by normalized().

Panics

Panics if self and other have different CaseSensitivity values. This can only happen with the runtime-dynamic PathElement type alias. The typed aliases PathElementCS and PathElementCI always have matching sensitivity, so they never panic.

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<'a, S1, S2> PartialEq<PathElementGeneric<'a, S2>> for PathElementGeneric<'_, S1>

where for<'s> CaseSensitivity: From<&'s S1> + From<&'s S2>,

Compares by normalized().

Panics

Panics if self and other have different CaseSensitivity values. Use PartialOrd for a non-panicking comparison that returns None on mismatch.

fn eq(&self, other: &PathElementGeneric<'a, S2>) -> 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<'a, S1, S2> PartialOrd<PathElementGeneric<'a, S2>> for PathElementGeneric<'_, S1>

where for<'s> CaseSensitivity: From<&'s S1> + From<&'s S2>,

Compares by normalized(). Returns None if the two elements have different CaseSensitivity values.

fn partial_cmp(&self, other: &PathElementGeneric<'a, S2>) -> 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<'a> TryFrom<PathElementGeneric<'a, CaseSensitivity>> for PathElementCI<'a>

Attempts to convert a runtime-dynamic PathElement into a PathElementCI.

Succeeds if the element is case-insensitive. On failure, returns the element re-wrapped as a PathElementCS in the Err variant (no data is lost).

type Error = PathElementGeneric<'a, CaseSensitive>

The type returned in the event of a conversion error.

fn try_from(pe: PathElement<'a>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> TryFrom<PathElementGeneric<'a, CaseSensitivity>> for PathElementCS<'a>

Attempts to convert a runtime-dynamic PathElement into a PathElementCS.

Succeeds if the element is case-sensitive. On failure, returns the element re-wrapped as a PathElementCI in the Err variant (no data is lost).

type Error = PathElementGeneric<'a, CaseInsensitive>

The type returned in the event of a conversion error.

fn try_from(pe: PathElement<'a>) -> Result<Self, Self::Error>

Performs the conversion.

impl<S> Eq for PathElementGeneric<'_, S>

where for<'s> CaseSensitivity: From<&'s S>,

See PartialEq for panicking behavior on case sensitivity mismatch.