Trait PathExt

Source

pub trait PathExt: Sealed {
    // Required methods
    fn expand(&self) -> Result<Cow<'_, Self>>
       where Self: ToOwned;
    fn localize_name(&self) -> Cow<'_, OsStr>;
    fn normalize(&self) -> Result<BasePathBuf>;
    fn normalize_virtually(&self) -> Result<BasePathBuf>;
    fn shorten(&self) -> Result<Cow<'_, Self>>
       where Self: ToOwned;
}

Expand description

Additional methods added to Path.

Required Methods§

Source

fn expand(&self) -> Result<Cow<'_, Self>>
where Self: ToOwned,

Expands self from its short form, if the convention exists for the platform.

This method reverses shorten but may not return the original path. Additional components may be shortened that were not before calling shorten.

§Implementation

Currently, this method calls:

GetLongPathNameW on Windows.

However, the implementation is subject to change. This section is only informative.

§Errors

Returns an error if self does not exist, even on Unix.

§Examples

use std::path::Path;

use normpath::PathExt;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"C:\Documents and Settings"),
        Path::new(r"C:\DOCUME~1").expand()?,
    );
}

Source

fn localize_name(&self) -> Cow<'_, OsStr>

Available on crate feature localization only.

Returns the localized simple name for this path.

If the path does not exist or localization is not possible, the last component will be returned.

The returned string should only be used for display to users. It will be as similar as possible to the name displayed by the system file manager for the path. However, nothing should be assumed about the result.

§Implementation

Currently, this method calls:

[NSFileManager displayNameAtPath:] on MacOS (rust-lang/rfcs#845).
SHGetFileInfoW on Windows.

This function has a usage note in its documentation:

You should call this function from a background thread. Failure to do so could cause the UI to stop responding.

However, the implementation is subject to change. This section is only informative.

§Panics

Panics if the path ends with a .. component. In the future, this method might also panic for paths ending with . components, so they should not be given either. They currently cause a platform-dependent value to be returned.

You should usually only call this method on normalized paths to avoid these panics.

§Examples

use std::path::Path;

use normpath::PathExt;

assert_eq!("test.rs", &*Path::new("/foo/bar/test.rs").localize_name());

Source

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

Normalizes self relative to the current directory.

The purpose of normalization is to remove . and .. components of a path if possible and make it absolute. This may be necessary for operations on the path string to be more reliable.

This method will access the file system to normalize the path. If the path might not exist, normalize_virtually can be used instead, but it is only available on Windows. Other platforms require file system access to perform normalization.

§Unix Behavior

On Unix, normalization is equivalent to canonicalization.

§Windows Behavior

On Windows, normalization is similar to canonicalization, but:

the prefix of the path is rarely changed. Canonicalization would always return a verbatim path, which can be difficult to use. (rust-lang/rust#42869)
the result is more consistent. (rust-lang/rust#49342)
shared partition paths do not cause an error. (rust-lang/rust#52440)

Verbatim paths will not be modified, so they might still contain . or .. components. BasePath::join and BasePathBuf::push can normalize them before they become part of the path. Junction points will additionally not be resolved with the current implementation.

§Implementation

Currently, this method calls:

fs::canonicalize on Unix.
GetFullPathNameW on Windows.

However, the implementation is subject to change. This section is only informative.

§Errors

Returns an error if self cannot be normalized or does not exist, even on Windows.

This method is designed to give mostly consistent errors on different platforms, even when the functions it calls have different behavior. To normalize paths that might not exist, use normalize_virtually.

§Examples

use std::path::Path;

use normpath::PathExt;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"X:\foo\baz\test.rs"),
        Path::new("X:/foo/bar/../baz/test.rs").normalize()?,
    );
}

Source

fn normalize_virtually(&self) -> Result<BasePathBuf>

Available on Windows only.

Equivalent to normalize but does not access the file system.

§Errors

Returns an error if self cannot be normalized or contains a null byte. Nonexistent paths will not cause an error.

§Examples

use std::path::Path;

use normpath::PathExt;

#[cfg(windows)]
assert_eq!(
    Path::new(r"X:\foo\baz\test.rs"),
    Path::new("X:/foo/bar/../baz/test.rs").normalize_virtually()?,
);

Source

fn shorten(&self) -> Result<Cow<'_, Self>>
where Self: ToOwned,

Shortens self from its expanded form, if the convention exists for the platform.

This method reverses expand but may not return the original path. Additional components may be shortened that were not before calling expand.

§Implementation

Currently, this method calls:

GetShortPathNameW on Windows.

However, the implementation is subject to change. This section is only informative.

§Errors

Returns an error if self does not exist, even on Unix.

§Examples

use std::path::Path;

use normpath::PathExt;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"C:\DOCUME~1"),
        Path::new(r"C:\Documents and Settings").shorten()?,
    );
}