Struct SPath

pub struct SPath { /* private fields */ }

An SPath is a posix normalized Path using camino Utf8PathBuf as strogate. It can be constructed from a String, Path, io::DirEntry, or walkdir::DirEntry

• It’s Posix normalized /, all redundant // and /./ are removed
• Garanteed to be UTF8

Implementations

impl SPath

Constructors that guarantee the SPath contract described in the struct

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

Constructor for SPath accepting anything that implements Into. IMPORTANT: This will normalize the path (posix style

pub fn from_std_path_buf(path_buf: PathBuf) -> Result<Self>

Constructor from standard PathBuf.

pub fn from_std_path(path: impl AsRef<Path>) -> Result<Self>

Constructor from standard Path and all impl AsRef.

pub fn from_walkdir_entry(wd_entry: DirEntry) -> Result<Self>

Constructor from walkdir::DirEntry

pub fn from_std_path_ok(path: impl AsRef<Path>) -> Option<Self>

Constructor for anything that implements AsRef.

Returns Option. Useful for filter_map.

pub fn from_std_path_buf_ok(path_buf: PathBuf) -> Option<Self>

Constructed from PathBuf returns an Option, none if validation fails. Useful for filter_map.

pub fn from_fs_entry_ok(fs_entry: DirEntry) -> Option<Self>

Constructor from fs::DirEntry returning an Option, none if validation fails. Useful for filter_map.

pub fn from_walkdir_entry_ok(wd_entry: DirEntry) -> Option<Self>

Constructor from walkdir::DirEntry returning an Option, none if validation fails. Useful for filter_map.

impl SPath

Public into path

pub fn into_std_path_buf(self) -> PathBuf

Consumes the SPath and returns its PathBuf.

pub fn std_path(&self) -> &Path

Returns a reference to the internal std Path.

pub fn path(&self) -> &Utf8Path

Returns a reference to the internal Utf8Path.

impl SPath

Public getters

pub fn to_str(&self) -> &str

👎Deprecated: use as_str()

Returns the &str of the path.

NOTE: We know that this must be Some() since the SPath constructor guarantees that the path.as_str() is valid.

pub fn as_str(&self) -> &str

Returns the &str of the path.

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

Returns the Option<&str> representation of the path.file_name()

pub fn name(&self) -> &str

Returns the &str representation of the path.file_name()

Note: If no file name will be an empty string

pub fn parent_name(&self) -> &str

Returns the parent name, and empty static &str if no present

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

Returns the Option<&str> representation of the file_stem()

Note: if the OsStr cannot be made into utf8 will be None

pub fn stem(&self) -> &str

Returns the &str representation of the file_name()

Note: If no stem, will be an empty string

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

Returns the Option<&str> representation of the extension().

NOTE: This should never be a non-UTF-8 string as the path was validated during SPath construction.

pub fn ext(&self) -> &str

Returns the extension or “” if no extension

pub fn is_dir(&self) -> bool

Returns true if the path represents a directory.

pub fn is_file(&self) -> bool

Returns true if the path represents a file.

pub fn exists(&self) -> bool

Checks if the path exists.

pub fn is_absolute(&self) -> bool

Returns true if the internal path is absolute.

pub fn is_relative(&self) -> bool

Returns true if the internal path is relative.

impl SPath

Meta

pub fn meta(&self) -> Result<SMeta>

Get a Simple Metadata structure SMeta with created_epoch_us, modified_epoch_us, and size (all i64) (size will be ‘0’ for any none file)

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

Returns the std metadata

pub fn modified(&self) -> Result<SystemTime>

👎Deprecated: use spath.meta()

Returns the path.metadata modified SystemTime

pub fn modified_us(&self) -> Result<i64>

👎Deprecated: use spath.meta()

Returns the epoch duration in microseconds. Note: The maximum UTC date would be approximately 2262-04-11. Thus, for all intents and purposes, it is far enough to not worry.

impl SPath

Transformers

pub fn canonicalize(&self) -> Result<SPath>

This perform a OS Canonicalization.

pub fn collapse(&self) -> SPath

Collapse a path without performing I/O.

All redundant separator and up-level references are collapsed.

However, this does not resolve links.

pub fn into_collapsed(self) -> SPath

Same as [collapse] but consume and create a new SPath only if needed

pub fn is_collapsed(&self) -> bool

Return true if the path is collapsed.

Quirk

If the path does not start with ./ but contains ./ in the middle, then this function might returns true.

pub fn parent(&self) -> Option<SPath>

Returns the parent directory as an Option.

pub fn append_suffix(&self, suffix: &str) -> SPath

Returns a new SPath with the given suffix appended to the filename (after the eventual extension)

Use [join] to join path segments.

Example:

• foo.rs + _backup → foo.rs_backup

pub fn join(&self, leaf_path: impl Into<Utf8PathBuf>) -> SPath

Joins the provided path with the current path and returns an SPath.

pub fn join_std_path(&self, leaf_path: impl AsRef<Path>) -> Result<SPath>

Joins a standard Path to the path of this SPath.

pub fn new_sibling(&self, leaf_path: impl AsRef<str>) -> SPath

Creates a new sibling SPath with the given leaf_path.

pub fn new_sibling_std_path(&self, leaf_path: impl AsRef<Path>) -> Result<SPath>

Creates a new sibling SPath with the given standard path.

pub fn diff(&self, base: impl AsRef<Utf8Path>) -> Option<SPath>

pub fn try_diff(&self, base: impl AsRef<Utf8Path>) -> Result<SPath>

pub fn replace_prefix( &self, base: impl AsRef<str>, with: impl AsRef<str>, ) -> SPath

pub fn into_replace_prefix( self, base: impl AsRef<str>, with: impl AsRef<str>, ) -> SPath

impl SPath

Path/UTF8Path/Camino passthrough

pub fn as_std_path(&self) -> &Path

pub fn strip_prefix(&self, prefix: impl AsRef<Path>) -> Result<SPath>

Returns a path that, when joined onto base, yields self.

Errors

If base is not a prefix of self

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

Determines whether base is a prefix of self.

Only considers whole path components to match.

Examples

use camino::Utf8Path;

let path = Utf8Path::new("/etc/passwd");

assert!(path.starts_with("/etc"));
assert!(path.starts_with("/etc/"));
assert!(path.starts_with("/etc/passwd"));
assert!(path.starts_with("/etc/passwd/")); // extra slash is okay
assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay

assert!(!path.starts_with("/e"));
assert!(!path.starts_with("/etc/passwd.txt"));

assert!(!Utf8Path::new("/etc/foo.rs").starts_with("/etc/foo"));

impl SPath

Extensions

pub fn into_ensure_extension(self, ext: &str) -> Self

Consumes the SPath and returns one with the given extension ensured:

• Sets the extension if not already equal.
• Returns self if the extension is already present.

Params

• ext e.g. html (not . prefixed)

pub fn ensure_extension(&self, ext: &str) -> Self

Returns a new SPath with the given extension ensured.

• Since this takes a reference, it will return a Clone no matter what.
• Use [into_ensure_extension] to consume and create a new SPath only if needed.

Delegates to into_ensure_extension.

Params

• ext e.g. html (not . prefixed)

pub fn append_extension(&self, ext: &str) -> Self

Appends the extension, even if one already exists or is the same.

Params

• ext e.g. html (not . prefixed)

impl SPath

Other

pub fn dir_before_glob(&self) -> Option<SPath>

Returns a new SPath for the eventual directory before the first glob expression.

If not a glob, will return none

Examples

• /some/path/**/src/*.rs → /some/path
• **/src/*.rs → ""
• /some/{src,doc}/**/* → /some

Trait Implementations

impl AsRef<Path> for SPath

fn as_ref(&self) -> &Path

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

impl AsRef<SPath> for SFile

fn as_ref(&self) -> &SPath

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

impl AsRef<SPath> for SPath

fn as_ref(&self) -> &SPath

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

impl AsRef<Utf8Path> for SPath

fn as_ref(&self) -> &Utf8Path

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

impl AsRef<str> for SPath

fn as_ref(&self) -> &str

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

impl Clone for SPath

fn clone(&self) -> SPath

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SPath

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

Formats the value using the given formatter.

impl Display for SPath

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

Formats the value using the given formatter.

impl From<&SFile> for SPath

fn from(val: &SFile) -> Self

Converts to this type from the input type.

impl From<&SPath> for PathBuf

fn from(val: &SPath) -> Self

Converts to this type from the input type.

impl From<&SPath> for String

fn from(val: &SPath) -> Self

Converts to this type from the input type.

impl From<&String> for SPath

fn from(path: &String) -> Self

Converts to this type from the input type.

impl From<&Utf8Path> for SPath

fn from(path: &Utf8Path) -> Self

Converts to this type from the input type.

impl From<&str> for SPath

fn from(path: &str) -> Self

Converts to this type from the input type.

impl From<SFile> for SPath

fn from(val: SFile) -> Self

Converts to this type from the input type.

impl From<SPath> for PathBuf

fn from(val: SPath) -> Self

Converts to this type from the input type.

impl From<SPath> for String

fn from(val: SPath) -> Self

Converts to this type from the input type.

impl From<SPath> for Utf8PathBuf

fn from(val: SPath) -> Self

Converts to this type from the input type.

impl From<String> for SPath

fn from(path: String) -> Self

Converts to this type from the input type.

impl From<Utf8PathBuf> for SPath

fn from(path_buf: Utf8PathBuf) -> Self

Converts to this type from the input type.

impl TryFrom<DirEntry> for SPath

type Error = Error

The type returned in the event of a conversion error.

fn try_from(fs_entry: DirEntry) -> Result<SPath>

Performs the conversion.

impl TryFrom<DirEntry> for SPath

type Error = Error

The type returned in the event of a conversion error.

fn try_from(wd_entry: DirEntry) -> Result<SPath>

Performs the conversion.

impl TryFrom<PathBuf> for SPath

type Error = Error

The type returned in the event of a conversion error.

fn try_from(path_buf: PathBuf) -> Result<SPath>

Performs the conversion.

impl TryFrom<SPath> for SFile

type Error = Error

The type returned in the event of a conversion error.

fn try_from(path: SPath) -> Result<SFile>

Performs the conversion.