Trait PathExtension

Source

pub trait PathExtension {
    // Required methods
    fn file_name_str(&self) -> Result<&str>;
    fn ensure_exists(&self) -> Result<()>;
    fn simplified(&self) -> &Path;
    fn normalize(&self) -> Result<PathBuf>;
    fn normalize_executable(&self) -> Result<PathBuf>;
    fn parent_abs_times(&self, x: usize) -> Result<PathBuf>;
    fn try_to_rel_from(&self, path: impl AsRef<Path>) -> Cow<'_, Path>;
    fn command(&self) -> CommandBuilder;

    // Provided methods
    fn normalize_exists(&self) -> Result<PathBuf> { ... }
    fn parent_abs(&self) -> Result<PathBuf> { ... }
    fn try_to_rel(&self) -> Cow<'_, Path> { ... }
}

Available on crate feature fs only.

Expand description

§File System Paths and Strings

Rust works with Strings, which are UTF-8 encoded bytes. However, not all operating systems work with UTF-8. That’s why Rust has OsString, which has platform-specific implementations. And PathBufs are wrappers for OsString.

However, often when writing platform-independent code, we want to stay in the UTF-8 realm, but conversion can be painful because you must handle the error when the OsString is not valid UTF-8.

use std::ffi::{OsString, OsStr};

use cu::pre::*;

fn take_os_string(s: &OsStr) -> cu::Result<()> {
    match s.to_str() {
        Some(s) => {
            cu::info!("valid utf-8: {s}");
            Ok(())
        }
        None => {
            cu::bail!("not valid utf-8!");
        }
    }
}

cu provides extension traits that integrates with cu::Result, so you can have the error handling by simply propagate with ?.

There are 4 traits, all will be included into scope with use cu::pre::*;. The path extensions also have utilities for working with file system specifically, (such as normalizing it), which is why they require the fs feature.

OsStrExtension
OsStrExtensionOwned
PathExtension - requires fs feature

Required Methods§

Source

fn file_name_str(&self) -> Result<&str>

Get file name. Error if the file name is not UTF-8 or other error occurs

Source

fn ensure_exists(&self) -> Result<()>

Check that the path exists, or fail with an error

Source

fn simplified(&self) -> &Path

Return the simplified path if the path has a Windows UNC prefix

The behavior is the same cross-platform.

Source

fn normalize(&self) -> Result<PathBuf>

Get absolute path for a path.

This is different from canonicalize() since that fails for paths that don’t exist. Here, we do a fallback that normalizes the path manually if canonicalize() fails:

If the path is absolute, then empty, ., and .. path segments are normalized and removed, and error if it tries to get the parent of root at some point.
If the path is relative, then the path is normalized the same way as above, and then appended to the absolute path of the current working directory.

On Windows only, it returns the most compatible form using the dunce crate instead of UNC, and the drive letter is also normalized to upper case

Source

fn normalize_executable(&self) -> Result<PathBuf>

Like normalize, but with the additional guarantee that:

The file name of the output will be the same as the input. This is because the executable can be a multicall binary that behaves differently depending on the executable name.
The path exists and is not a directory

Source

fn parent_abs_times(&self, x: usize) -> Result<PathBuf>

Effecitvely chaining parent_abs x times

Source

fn try_to_rel_from(&self, path: impl AsRef<Path>) -> Cow<'_, Path>

Try converting self to a relative path from a base path

Source

fn command(&self) -> CommandBuilder

Available on crate feature process only.

Start building a child process with the path as the executable

See Spawn Commands

Provided Methods§

Source

fn normalize_exists(&self) -> Result<PathBuf>

Like normalize, but with the additional guarantee that the path exists

Source

fn parent_abs(&self) -> Result<PathBuf>

Get the parent path as an absolute path

Path navigation is very complex and that’s why we are paying a little performance cost and always returning PathBuf, and always converting the path to absolute.

For path manipulation (i.e. as a OsStr), instead of navigation, use std parent() instead

Source