Struct SimplePath 

pub struct SimplePath {
    pub disallow_long: bool,
    pub allow_unknown_unc: bool,
    pub map_to_drive: bool,
    pub skip_dunce: bool,
    pub _unused: bool,
}

Simplifies Win32 File Namespaces paths (the “\\?\” prefix) for better readability and compatibility.

The following code is a snap-in replacement of fs::canonicalize.

SimplePath::default().canonicalize(path);

If you have net use Z: \\server\share:

	C:\dir	Z:\x
fs::canonicalize	\\?\C:\dir	\\?\UNC\server\share\x
SimplePath	C:\dir	\\server\share\x
SimplePath with map_to_drive	C:\dir	Z:\x

Fields

disallow_long: bool

Disallow simplifications if the result is a “long path” (longer than 260 characters). Initially false.

Long paths may not be supported by some programs and APIs. In such cases, using the Win32 File Namespaces (the “\\?\” prefix) can often work around the limitation. Setting this option to true can improve the compatibility with such cases.

On the other hand, some other programs such as PowerShell v7 can handle long paths, but they can’t handle the “\\?\” prefix. They work best with false.

Please also see the Maximum Path Length Limitation.

allow_unknown_unc: bool

Simplify all long UNC paths (prefixed by “\\?\UNC\”). Initially false.

Technically speaking, since the “\\?\” prefix (Win32 File Namespaces) disables all string parsing and sends the following string directly to the file system, simplifying the path is not always guaranteed to be safe or equivalent.

For this reason, the SimplePath simplifies connected network shares only by default. Set this option to true to simplify all paths prefixed by “\\?\UNC\”.

Please also see the safety note.

Examples

let path = Path::new(r"\\?\UNC\server\share\dir");
let simple = SimplePath { allow_unknown_unc: true, ..Default::default() };
#[cfg(windows)]
assert_eq!(&*simple.simplify(path).unwrap().unwrap(), r"\\server\share\dir");

map_to_drive: bool

Map to network share drive names when possible. Initially false.

Examples

let path = "file.txt";
let simple = SimplePath { map_to_drive: true, ..Default::default() };
let canonicalized = simple.canonicalize(path)?;

If the file.txt is in a network drive, the result is Z:\dir\file.txt instead of \\server\share\dir\file.txt.

The following code tries to preserve the original form of the path.

SimplePath {
    map_to_drive: !path.as_os_str().as_encoded_bytes().starts_with(br"\\"),
    ..Default::default()
}.canonicalize(path)?;

skip_dunce: bool

Skip the dunce simplification. Initially false.

_unused: bool

It is highly recommended to always use , ..Default::default(). Otherwise builds fail when new fields are added.

This field is not used in any ways, but exists to allow using , ..Default::default() even when all other fields are specified.

Implementations

impl SimplePath

pub fn canonicalize(&self, path: impl AsRef<Path>) -> Result<PathBuf>

A snap-in replacement for fs::canonicalize. It calls fs::canonicalize and simplify.

On other platforms than Windows, this is equivalent to fs::canonicalize.

Examples

use simple_path::SimplePath;
let canonicalized = SimplePath::default().canonicalize(path)?;
println!("{}", canonicalized.display());

pub fn simplify<'a>(&self, path: &'a Path) -> Result<Option<Cow<'a, Path>>>

Try to simplify the given path.

Returns Ok(None) if no simplification is applied, or on other platforms than Windows.

pub fn refresh() -> Result<()>

Refreshes the cached information.

pub fn display<'a>(&'a self, path: &'a Path) -> Display<'a>

Returns an object that implements Display for printing simplified paths.

Examples

let path = Path::new("file").canonicalize()?;
println!("{}", SimplePath::default().display(&path));

pub fn strip_prefix( path: &Path, base: impl AsRef<Path>, ) -> Result<&Path, StripPrefixError>

A snap-in replacement for Path::strip_prefix with a fix for a leading directory separator “\” left for UNC paths on Windows.

Examples

SimplePath::strip_prefix(path, base)

Trait Implementations

impl Clone for SimplePath

fn clone(&self) -> SimplePath

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SimplePath

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

Formats the value using the given formatter.

impl Default for SimplePath

fn default() -> SimplePath

Returns the “default value” for a type.