Trait omnipath::windows::WinPathExt

pub trait WinPathExt: Sealed {
    // Required methods
    fn win_absolute(&self) -> Result<PathBuf>;
    fn to_winuser_path(&self) -> Result<PathBuf>;
    fn to_verbatim(&self) -> Result<PathBuf>;
    fn to_verbatim_exact(&self) -> Result<PathBuf>;
}

[Windows only] Extension functions that use the Windows API to resolve paths.

Required Methods

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

Makes the path absolute without resolving symlinks.

Unlike canonicalize the path does not need to exist. This will also not return verbatim paths unless given one.

Example

#[cfg(windows)]
{
    use omnipath::windows::WinPathExt;
    use std::path::Path;
    use std::env::current_dir;

    let path = Path::new(r"path\to\file");
    assert_eq!(
        path.win_absolute().unwrap(),
        // WARNING! Depending on the path, this may not always be equivalent.
        current_dir().unwrap().join(path)
    )
}

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

Convert a verbatim path to a win32 path.

If the path is not verbatim the the path is returned as-is.

Example

#[cfg(windows)]
{
    use omnipath::windows::WinPathExt;
    use std::path::Path;

    let path = Path::new(r"\\?\C:\path\to\file.txt");
    assert_eq!(
        path.to_winuser_path().unwrap(),
        Path::new(r"C:\path\to\file.txt")
    );

    let path = Path::new(r"\\?\UNC\server\share\file.txt");
    assert_eq!(
        path.to_winuser_path().unwrap(),
        Path::new(r"\\server\share\file.txt")
    );
}

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

Create a verbatim path.

Useful for passing exact paths to the Windows API. Otherwise paths are lossy (e.g. trailing dots are trimmed).

When displaying paths to the user, consider using to_winuser_path to display a user-friendly path.

Example

#[cfg(windows)]
{
    use omnipath::windows::WinPathExt;
    use std::path::Path;

    let path = Path::new(r"C:\path\to\file.txt");
    assert_eq!(
        path.to_verbatim().unwrap(),
        Path::new(r"\\?\C:\path\to\file.txt")
    );

    let path = Path::new(r"\\server\share\file.txt");
    assert_eq!(
        path.to_verbatim().unwrap(),
        Path::new(r"\\?\UNC\server\share\file.txt")
    );

    let path = Path::new(r"\\.\pipe\name");
    assert_eq!(
        path.to_verbatim().unwrap(),
        Path::new(r"\\?\pipe\name")
    );

    let path = Path::new(r"\\?\pipe\name");
    assert_eq!(
        path.to_verbatim().unwrap(),
        Path::new(r"\\?\pipe\name")
    );

    // Using `NUL` in the path would usually redirect to
    // `\\.\NUL`. But converting to a verbatim path allows it.
    let path = Path::new(r"C:\path\to\NUL");
    assert_eq!(
        path.to_verbatim().unwrap(),
        Path::new(r"\\?\C:\path\to\NUL")
    );
}

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

Convert to an exact verbatim path

Unlike to_verbatim, this will preserve the exact path name, changing only the root of the path.

Warning: This can be risky unless you really mean it. For example, a / will be taken as a file named /. Similarly ., .. will all be treated as normal file names instead of being special.

Example

#[cfg(windows)]
{
    use omnipath::windows::WinPathExt;
    use std::path::Path;

    // `.` and `..` will be interpreted as being normal file names.
    // So `..` is not the parent directory.
    let path = Path::new(r"C:\path.\to\.\..");
    assert_eq!(
        path.to_verbatim_exact().unwrap(),
        Path::new(r"\\?\C:\path.\to\.\..")
    );

    // Using `NUL` in the path would usually redirect to
    // `\\.\NUL`. But converting to a verbatim path allows it.
    let path = Path::new(r"C:\path\to\NUL");
    assert_eq!(
        path.to_verbatim_exact().unwrap(),
        Path::new(r"\\?\C:\path\to\NUL")
    );
}

Implementations on Foreign Types

impl WinPathExt for Path

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

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

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

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

Implementors