Struct SFile

pub struct SFile { /* private fields */ }

An SFile can be constructed from a Path, io::DirEntry, or walkdir::DirEntry and guarantees the following:

• The entry is a file (exists).
• It has a file name.
• The full path is UTF-8 valid.

Implementations

impl SFile

Constructors that guarantee the SFile contract described in the struct

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

Constructor for SFile accepting anything that implements Into.

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>

Constructors for anything that implements AsRef.

Returns Option. Useful for filter_map.

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

Constructor from PathBuf returning 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 SFile

Public into path

pub fn into_std_path_buf(self) -> PathBuf

Consumes the SFile and returns its PathBuf.

pub fn std_path(&self) -> &Path

Returns a reference to the internal standard Path.

pub fn path(&self) -> &SPath

Returns a reference to the internal Utf8Path.

impl SFile

Public getters

pub fn to_str(&self) -> &str

👎Deprecated: Use as_str() instead

Returns the &str of the path.

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

pub fn as_str(&self) -> &str

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().

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 SFile construction.

pub fn ext(&self) -> &str

Same as .extension() but returns “” if no extension.

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 SFile

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() or spath.metadata

Returns the path.metadata modified as 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 not to worry.

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

👎Deprecated: use spath.meta()

Returns the file size in bytes as i64. Note: In the highly unlikely event that the size exceeds i64::MAX, i64::MAX is returned. i64::MAX represents 8,388,607 terabytes, providing ample margin before it becomes a concern.

impl SFile

Transformers

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

pub fn collapse(&self) -> SFile

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) -> SFile

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 SPath, if available.

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

Joins the current path with the specified leaf_path.

This method creates a new path by joining the existing path with a specified leaf_path and returns the result as an SPath.

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

Joins a standard Path to the path of this SFile.

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

Creates a new sibling path with the specified leaf_path.

Generates a new path in the same parent directory as the current file, appending the leaf_path.

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

Creates a new sibling path with the specified 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 SFile

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"));

Trait Implementations

impl AsRef<Path> for SFile

fn as_ref(&self) -> &Path

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

impl AsRef<SFile> for SFile

fn as_ref(&self) -> &SFile

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<Utf8Path> for SFile

fn as_ref(&self) -> &Utf8Path

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

impl AsRef<str> for SFile

fn as_ref(&self) -> &str

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

impl Clone for SFile

fn clone(&self) -> SFile

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SFile

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

Formats the value using the given formatter.

impl Display for SFile

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

Formats the value using the given formatter.

impl From<&SFile> for PathBuf

fn from(val: &SFile) -> 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<&SFile> for String

fn from(val: &SFile) -> Self

Converts to this type from the input type.

impl From<SFile> for PathBuf

fn from(val: SFile) -> 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<SFile> for String

fn from(val: SFile) -> Self

Converts to this type from the input type.

impl From<SFile> for Utf8PathBuf

fn from(val: SFile) -> Self

Converts to this type from the input type.

impl TryFrom<&String> for SFile

type Error = Error

The type returned in the event of a conversion error.

fn try_from(path: &String) -> Result<SFile>

Performs the conversion.

impl TryFrom<&str> for SFile

type Error = Error

The type returned in the event of a conversion error.

fn try_from(path: &str) -> Result<SFile>

Performs the conversion.

impl TryFrom<DirEntry> for SFile

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<DirEntry> for SFile

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<PathBuf> for SFile

type Error = Error

The type returned in the event of a conversion error.

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

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.

impl TryFrom<String> for SFile

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.