pub trait PathExt: Sealed {
// Required methods
fn localize_name(&self) -> Cow<'_, OsStr>;
fn normalize(&self) -> Result<BasePathBuf>;
fn normalize_virtually(&self) -> Result<BasePathBuf>;
}
Expand description
Additional methods added to Path
.
Required Methods§
sourcefn localize_name(&self) -> Cow<'_, OsStr>
fn localize_name(&self) -> Cow<'_, OsStr>
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());
sourcefn normalize(&self) -> Result<BasePathBuf>
fn normalize(&self) -> Result<BasePathBuf>
Normalizes self
relative to the current directory.
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)
However, 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.
§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()?,
);
}
sourcefn normalize_virtually(&self) -> Result<BasePathBuf>
fn normalize_virtually(&self) -> Result<BasePathBuf>
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()?,
);
Implementations on Foreign Types§
source§impl PathExt for Path
impl PathExt for Path
source§fn localize_name(&self) -> Cow<'_, OsStr>
fn localize_name(&self) -> Cow<'_, OsStr>
localization
only.