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, ., .., strings containing / or \0, and unassigned Unicode characters), 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. Comparing or ordering elements with different case sensitivities will panic.

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 /).

let pe = PathElementCS::from_bytes(b"hello.txt")?;
assert_eq!(pe.normalized(), "hello.txt");

// Invalid UTF-8 is replaced with U+FFFD
let pe = PathElementCS::from_bytes(b"hello\xff.txt")?;
assert_eq!(pe.normalized(), "hello\u{FFFD}.txt");

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 /).

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

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 /).

let pe = PathElementCI::from_bytes(b"Hello.TXT")?;
assert_eq!(pe.normalized(), "hello.txt");

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.

let cs = PathElement::new("Hello.txt", CaseSensitivity::Sensitive)?;
assert_eq!(cs.normalized(), "Hello.txt");

let ci = PathElement::new("Hello.txt", CaseSensitivity::Insensitive)?;
assert_eq!(ci.normalized(), "hello.txt");

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.

assert_eq!(PathElementCS::new("a")?.case_sensitivity(), CaseSensitivity::Sensitive);
assert_eq!(PathElementCI::new("a")?.case_sensitivity(), CaseSensitivity::Insensitive);

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.

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

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.

let cs = PathElementCS::new("Caf\u{00E9}.txt")?;
assert_eq!(cs.normalized(), "Caf\u{00E9}.txt"); // case preserved

let ci = PathElementCI::new("Caf\u{00E9}.txt")?;
assert_eq!(ci.normalized(), "caf\u{00E9}.txt"); // 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.

let pe = PathElementCS::new("hello.txt")?;
assert!(matches!(pe.into_normalized(), Cow::Borrowed("hello.txt")));

pub fn is_os_compatible(&self) -> bool

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

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

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>.

let pe = PathElementCS::new("hello.txt")?;
assert!(matches!(pe.into_os_compatible(), Cow::Borrowed("hello.txt")));

pub fn os_str(&self) -> &OsStr

Available on crate feature std only.

Returns the OS-compatible form as an OsStr reference.

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

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>.

let pe = PathElementCS::new("hello.txt")?;
assert!(matches!(pe.into_os_str(), Cow::Borrowed(s) if s == OsStr::new("hello.txt")));

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).

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

let borrowed = PathElementCS::new("hello")?;
assert!(!borrowed.is_owned());

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.

let pe = PathElementCS::new("hello.txt")?;
let owned: PathElementCS<'static> = pe.into_owned();
assert!(owned.is_owned());
assert_eq!(owned.normalized(), "hello.txt");

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.