Struct canonical_path::CanonicalPath

pub struct CanonicalPath(_);

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.

Methods

impl CanonicalPath

pub fn new<P: ?Sized>(path: &P) -> Result<&Self> where
    P: AsRef<Path>, 

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

pub unsafe fn from_path_unchecked<P: ?Sized>(path: &P) -> &Self where
    P: AsRef<Path>, 

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

We utilize 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

Performs the conversion.

impl Borrow<CanonicalPath> for CanonicalPathBuf

fn borrow(&self) -> &CanonicalPath

Immutably borrows from an owned value.

impl Debug for CanonicalPath

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl PartialOrd for CanonicalPath

fn partial_cmp(&self, __arg_0: &CanonicalPath) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, __arg_0: &CanonicalPath) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, __arg_0: &CanonicalPath) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, __arg_0: &CanonicalPath) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, __arg_0: &CanonicalPath) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Ord for CanonicalPath

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

impl PartialEq for CanonicalPath

fn eq(&self, __arg_0: &CanonicalPath) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &CanonicalPath) -> bool

This method tests for !=.

impl Eq for CanonicalPath

impl Hash for CanonicalPath

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

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl AsRef<Path> for CanonicalPath

fn as_ref(&self) -> &Path

Performs the conversion.

impl ToOwned for CanonicalPath

type Owned = CanonicalPathBuf

fn to_owned(&self) -> CanonicalPathBuf

Creates owned data from borrowed data, usually by cloning.

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

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

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