Struct CanonicalPath

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

A reference type for a canonical filesystem path

More specifically: it is at least guaranteed to be canonical at the time it is created. There are potential TOCTTOU problems if the underlying filesystem structure changes after path canonicalization.

Implementations

impl CanonicalPath

pub fn new<P>(path: &P) -> Result<&Self>

where P: AsRef<Path> + ?Sized,

Create a canonical path, returning error if the supplied path is not canonical

pub unsafe fn from_path_unchecked<P>(path: &P) -> &Self

where P: AsRef<Path> + ?Sized,

Create a canonical path from a path, skipping the canonicalization check

This uses the same unsafe reference conversion tricks as std to convert from AsRef<Path> to AsRef<CanonicalPath>, i.e. &CanonicalPath is a newtype for &Path in the same way &Path is a newtype for &OsStr.

pub fn to_canonical_path_buf(&self) -> CanonicalPathBuf

Convert a canonical path reference into an owned CanonicalPathBuf

pub fn as_path(&self) -> &Path

Return a Path reference.

pub fn as_os_str(&self) -> &OsStr

Return an OsStr reference.

pub fn to_str(&self) -> Option<&str>

Yields a &str slice if the path is valid unicode.

pub fn parent(&self) -> Result<CanonicalPathBuf>

Return a canonical parent path of this path, or io::Error if the path is the root directory or another canonicalization error occurs.

pub fn file_name(&self) -> Option<&OsStr>

Returns the final component of the path, if there is one.

pub fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool

Determines whether base is a prefix of self.

pub fn ends_with<P: AsRef<Path>>(&self, child: P) -> bool

Determines whether child is a suffix of self.

pub fn file_stem(&self) -> Option<&OsStr>

Extracts the stem (non-extension) portion of self.file_name.

pub fn extension(&self) -> Option<&OsStr>

Extracts the extension of self.file_name, if possible.

pub fn with_file_name<S: AsRef<OsStr>>( &self, file_name: S, ) -> Result<CanonicalPathBuf>

Creates an owned CanonicalPathBuf like self but with the given file name.

pub fn with_extension<S: AsRef<OsStr>>( &self, extension: S, ) -> Result<CanonicalPathBuf>

Creates an owned CanonicalPathBuf like self but with the given extension.

pub fn components(&self) -> Components<'_>

Produces an iterator over the Components of a path

pub fn iter(&self) -> Iter<'_>

Produces an iterator over the path’s components viewed as OsStr slices.

pub fn display(&self) -> Display<'_>

Returns an object that implements Display for safely printing paths that may contain non-Unicode data.

pub fn metadata(&self) -> Result<Metadata>

Queries the file system to get information about a file, directory, etc.

Unlike the std version of this method, it will not follow symlinks, since as a canonical path we should be symlink-free.

pub fn join<P: AsRef<Path>>(&self, path: P) -> Result<CanonicalPathBuf>

Join a path onto a canonical path, returning a CanonicalPathBuf.

pub fn read_dir(&self) -> Result<ReadDir>

Returns an iterator over the entries within a directory.

The iterator will yield instances of io::Result. New errors may be encountered after an iterator is initially constructed.

This is an alias to fs::read_dir.

pub fn exists(&self) -> bool

Does this path exist?

pub fn is_file(&self) -> bool

Is this path a file?

pub fn is_dir(&self) -> bool

Is this path a directory?

Trait Implementations

impl AsRef<CanonicalPath> for CanonicalPathBuf

fn as_ref(&self) -> &CanonicalPath

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

impl AsRef<Path> for CanonicalPath

fn as_ref(&self) -> &Path

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

impl Borrow<CanonicalPath> for CanonicalPathBuf

fn borrow(&self) -> &CanonicalPath

Immutably borrows from an owned value.

impl Debug for CanonicalPath

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

Formats the value using the given formatter.

impl Hash for CanonicalPath

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

impl Ord for CanonicalPath

fn cmp(&self, other: &CanonicalPath) -> Ordering

This method returns an Ordering between self and other.

impl PartialEq for CanonicalPath

fn eq(&self, other: &CanonicalPath) -> 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 PartialOrd for CanonicalPath

fn partial_cmp(&self, other: &CanonicalPath) -> 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 ToOwned for CanonicalPath

type Owned = CanonicalPathBuf

The resulting type after obtaining ownership.

fn to_owned(&self) -> CanonicalPathBuf

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl Eq for CanonicalPath

impl StructuralPartialEq for CanonicalPath