Struct DirBufEntry

pub struct DirBufEntry<'buf> { /* private fields */ }

Represents an entry within a DirBuf by reusing its internal buffer.

A DirBufEntry holds a mutable borrow of its parent, preventing the buffer from being unexpectedly modified while in use.

Implementations

impl<'buf> DirBufEntry<'buf>

pub fn join(&mut self, path: impl AsRef<Path>) -> DirBufEntry<'_>

Efficiently join a path with another.

The returned DirBufEntry reuses the underlying buffer, and must be dropped before join can be called again. The DirBufEntry holds a mutable reference to ensure join cannot be called before the DirBufEntry is dropped.

If the path segment is coming from untrusted user data and panics are undesirable, use try_join instead.

Panics

Panics if path is not a trivial path.

Performance

The overhead of the panic check is not insubstaintial. When multiple joins are used, this is still usually faster than using a PathBuf, but if you know the path is trivial (e.g. if it is a string literal), consider using join_unchecked to remove this overhead.

A trivial path can be joined to any path via a simple append.

Things that make a path non-trivial:

• .. components
• windows drive prefixes
• windows verbatim paths
• being an absolute path

pub fn join_lit(&mut self, path: &str) -> DirBufEntry<'_>

Variant of join optimized for string literals.

Semantic behavior is identical to Self::join, the only difference is performance.

For simple cases, this can have performance equivelent to that of Self::join_unchecked without the unsaftey, but for more complex cases, Self::join may be more performant.

It achives this performance gain by leveraging inlining and constant folding.

pub fn try_join( &mut self, path: impl AsRef<Path>, ) -> Result<DirBufEntry<'_>, JoinError>

Attempt to join a path with another.

The returned DirBufEntry reuses the underlying buffer, and must be dropped before join can be called again. The DirBufEntry holds a mutable reference to ensure join cannot be called before the DirBufEntry is dropped.

Panics

Panics if path is not a trivial path.

A trivial path can be joined to any path via a simple append.

Things that make a path non-trivial:

• .. components
• windows drive prefixes
• windows verbatim paths
• being an absolute path

pub unsafe fn join_unchecked( &mut self, path: impl AsRef<Path>, ) -> DirBufEntry<'_>

Join a path to another without checking that it is trivial.

Saftey

path must be a trivial path.

A trivial path can be joined to any path via a simple append.

Things that make a path non-trivial:

• .. components
• windows drive prefixes
• windows verbatim paths
• being an absolute path

Trait Implementations

impl AsRef<Path> for DirBufEntry<'_>

fn as_ref(&self) -> &Path

Converts this type into a shared reference of the (usually inferred) input type.

impl<'buf> Debug for DirBufEntry<'buf>

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

Formats the value using the given formatter.

impl<T: AsRef<Path>> PartialEq<T> for DirBufEntry<'_>

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.