Struct DirBuf

pub struct DirBuf { /* private fields */ }

Reusable directory buffer.

While the state of the internal buffer may change, semantically, it always has the same value as when it was constructed. This is to prevent you from accidentally making a permenant modification to its path instead of a temporary one.

Implementations

impl DirBuf

pub fn new(path: impl Into<PathBuf>) -> Self

impl DirBuf

pub fn with_capacity(capacity: usize) -> Self

Initialize an empty DirBuf with the given capacity.

pub fn into_inner(self) -> PathBuf

Return the internal buffer, resetting it to its initial state first.

impl DirBuf

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 DirBuf

fn as_ref(&self) -> &Path

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

impl Debug for DirBuf

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

Formats the value using the given formatter.

impl Default for DirBuf

fn default() -> DirBuf

Returns the “default value” for a type.

impl<T: AsRef<Path>> PartialEq<T> for DirBuf

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.