Normpath

https://docs.rs/normpath/
Admin
Normpath is a Rust crate that provides methods to normalize paths in the recommended way for the...
Tokens:24,090
Snippets:220
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### BasePath::join example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Example for BasePath::join. Shows that on Windows, leading . and .. components are normalized if possible, and that joining with a verbatim path is handled correctly.

```rust
use std::path::Path;

use normpath::BasePath;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"\\?\foo\baz\test.rs"),
        BasePath::try_new(r"\\?\foo\bar")
            .unwrap()
            .join("../baz/test.rs"),
    );
}
```

--------------------------------

### expand() example on Windows

Source: https://docs.rs/normpath/latest/normpath/trait.PathExt.html

Example for the expand method. On Windows, expands a short path (e.g., C:\DOCUME~1) to its long form (C:\Documents and Settings). The example is conditional on cfg!(windows) and uses the ? operator, so it must be inside a function returning Result.

```rust
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()?,
    );
}
```

--------------------------------

### BasePath::try_new example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Example for BasePath::try_new. On Windows, returns an error if the path is missing a prefix.

```rust
use std::path::Path;

use normpath::BasePath;

if cfg!(windows) {
    let path = r"X:\foo\bar";
    assert_eq!(Path::new(path), BasePath::try_new(path)?);

    assert!(BasePath::try_new(r"foo\bar").is_err());
}
```

--------------------------------

### normalize() example on Windows

Source: https://docs.rs/normpath/latest/normpath/trait.PathExt.html

Example for the normalize method. On Windows, normalizes a path with .. components to an absolute path. The example is conditional on cfg!(windows) and uses the ? operator, so it must be inside a function returning Result.

```rust
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()?,
    );
}
```

--------------------------------

### BasePath::new example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Example for BasePath::new. On Windows, if the path is missing a prefix, it is joined to the current directory. Returns an error if reading the current directory fails.

```rust
use std::path::Path;

use normpath::BasePath;

if cfg!(windows) {
    let path = Path::new(r"X:\foo\bar");
    assert_eq!(path, *BasePath::new(path)?);

    assert!(BasePath::new(Path::new(r"foo\bar")).is_ok());
}
```

--------------------------------

### BasePathBuf::push example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Pushes a path onto the existing BasePathBuf in place. Equivalent to BasePath::join but modifies self. The example pushes '../baz/test.rs' onto '\\?\foo\bar' to get '\\?\foo\baz\test.rs'.

```rust
use std::path::Path;

use normpath::BasePathBuf;

if cfg!(windows) {
    let mut path = BasePathBuf::try_new(r"\\?\foo\bar").unwrap();
    path.push("../baz/test.rs");
    assert_eq!(Path::new(r"\\?\foo\baz\test.rs"), path);
}
```

--------------------------------

### Expand a Windows short path with PathExt::expand

Source: https://docs.rs/normpath/latest/src/normpath/lib.rs.html

Shows how to call `expand()` on a Windows short path. The example is guarded by `cfg!(windows)` and uses `?` to propagate the `io::Error` that `expand()` returns if the path does not exist. The `#` lines are hidden by rustdoc and are not part of the user-visible example.

```rust
# use std::io;
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()?,
    );
}
#
# Ok::<_, io::Error>(())
```

--------------------------------

### localize_name() example

Source: https://docs.rs/normpath/latest/normpath/trait.PathExt.html

Example for the localize_name method. Returns the localized simple name for a path; here it returns "test.rs" for "/foo/bar/test.rs". The method is only available with the crate feature `localization`.

```rust
use std::path::Path;

use normpath::PathExt;

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

--------------------------------

### BasePathBuf::new example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Creates a BasePathBuf from a path. On Windows, a path with a drive prefix is accepted and equals the original path; a path without a prefix is also accepted (returns Ok).

```rust
use std::path::Path;

use normpath::BasePathBuf;

if cfg!(windows) {
    let path = r"X:\foo\bar";
    assert_eq!(Path::new(path), BasePathBuf::new(path)?);

    assert!(BasePathBuf::new(r"foo\bar").is_ok());
}
```

--------------------------------

### BasePath::parent example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Shows how to use `BasePath::parent` on Windows to get the parent of a path. The example asserts that the parent of `X:\foo\bar` is `X:\foo`. Note that `parent` returns a `Result` and may fail if the last component is not `Component::Normal` or `Component::RootDir`.

```rust
use std::path::Path;

use normpath::BasePath;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"X:\foo"),
        BasePath::try_new(r"X:\foo\bar").unwrap().parent()?.unwrap(),
    );
}

```

--------------------------------

### pub fn starts_with<P>(&self, base: P) -> bool where P: AsRef<Path>

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Checks if the path starts with the given base path. Equivalent to Path::starts_with.

```APIDOC
## pub fn starts_with<P>(&self, base: P) -> bool where P: AsRef<Path>

### Description
Checks if the path starts with the given base path. Equivalent to `Path::starts_with`.

### Method
`starts_with`

### Signature
`pub fn starts_with<P>(&self, base: P) -> bool where P: AsRef<Path>`

### Parameters
- `self` - The `BasePath` instance.
- `base` (P) - The base path to check against. Must implement `AsRef<Path>`.

### Returns
- `bool` - `true` if the path starts with `base`, otherwise `false`.
```

--------------------------------

### BasePathBuf::try_new example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Creates a BasePathBuf with try_new, which returns an error for paths without a prefix on Windows. A path with a drive prefix succeeds and equals the original path.

```rust
use std::path::Path;

use normpath::BasePathBuf;

if cfg!(windows) {
    let path = r"X:\foo\bar";
    assert_eq!(Path::new(path), BasePathBuf::try_new(path)?);

    assert!(BasePathBuf::try_new(r"foo\bar").is_err());
}
```

--------------------------------

### shorten() example

Source: https://docs.rs/normpath/latest/normpath/trait.PathExt.html

Shortens a path to its 8.3 short form on Windows. Returns an error if the path does not exist, even on Unix.

```rust
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()?,
    );
}
```

--------------------------------

### Example: Find target directory using normpath

Source: https://docs.rs/normpath/latest/normpath/index.html

Shows how to use BasePathBuf and PathExt to normalize a path and iterate through its components to find a 'target' directory. The function returns an io::Result<Option<BasePathBuf>>, handling normalization errors and popping components.

```rust
use std::io;
use std::path::Path;

use normpath::BasePathBuf;
use normpath::PathExt;

fn find_target_dir(path: &Path) -> io::Result<Option<BasePathBuf>> {
    let mut path = path.normalize()?;
    while !path.ends_with("target") {
        match path.pop() {
            Ok(true) => continue,
            Ok(false) => {}
            Err(_) => {
                eprintln!("Some components could not be normalized.");
            }
        }
        return Ok(None);
    }
    Ok(Some(path))
}
```

--------------------------------

### normalize_virtually() example

Source: https://docs.rs/normpath/latest/normpath/trait.PathExt.html

Use on Windows to normalize a path without touching the file system. Returns an error if the path cannot be normalized or contains a null byte; nonexistent paths do not cause an error.

```rust
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()?,
);
```

--------------------------------

### BasePath::parent example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Example for BasePath::parent. Returns the path without its last component, and returns Ok(None) if the last component is Component::RootDir. Returns an error if the last component is not Normal or RootDir.

```rust
use std::path::Path;

use normpath::BasePath;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"X:\foo"),
        BasePath::try_new(r"X:\foo\bar").unwrap().parent()?.unwrap(),
    );
}
```

--------------------------------

### BasePath::parent_unchecked example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Shows how to use `BasePath::parent_unchecked` on Windows to get the parent of a path without error checking. The example asserts that the parent of `X:\foo\..` is `X:\foo`. This method is equivalent to `Path::parent` and is usually better to use `parent` instead.

```rust
use std::path::Path;

use normpath::BasePath;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"X:\foo"),
        BasePath::try_new(r"X:\foo\..")
            .unwrap()
            .parent_unchecked()
            .unwrap(),
    );
}

```

--------------------------------

### BasePathBuf::pop example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Pops the last component in place. Returns Ok(true) when a component is removed and Ok(false) when the parent is None. The example shows popping 'bar' from 'X:\foo\bar' to get 'X:\foo'.

```rust
use std::path::Path;

use normpath::BasePathBuf;

if cfg!(windows) {
    let mut path = BasePathBuf::try_new(r"X:\foo\bar").unwrap();
    assert!(path.pop()?);
    assert_eq!(Path::new(r"X:\foo"), path);
}
```

--------------------------------

### Normalize a path with PathExt::normalize

Source: https://docs.rs/normpath/latest/src/normpath/lib.rs.html

Shows how to call `normalize()` on a `Path` using the `PathExt` trait. The example is guarded by `cfg!(windows)` and asserts that the normalized path equals the expected Windows path. It returns `io::Error` on failure.

```rust
# use std::io;
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()?,
    );
}
#
# Ok::<_, io::Error>(())
```

--------------------------------

### Normalize a path virtually with PathExt::normalize_virtually

Source: https://docs.rs/normpath/latest/src/normpath/lib.rs.html

Shows how to call `normalize_virtually()` on a `Path` using the `PathExt` trait. The example is guarded by `#[cfg(windows)]` and asserts that the normalized path equals the expected Windows path. It returns `io::Error` on failure.

```rust
# use std::io;
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()?,
);
#
# Ok::<_, io::Error>(())
```

--------------------------------

### Shorten a path with PathExt::shorten

Source: https://docs.rs/normpath/latest/src/normpath/lib.rs.html

Shows how to call `shorten()` on a `Path` using the `PathExt` trait. The example is guarded by `cfg!(windows)` and asserts that the shortened path equals the expected Windows short path. It returns `io::Error` on failure.

```rust
# use std::io;
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()?,
    );
}
#
# Ok::<_, io::Error>(())
```

--------------------------------

### BasePathBuf::pop_unchecked example

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Pops the last component without checking for a parent. Equivalent to PathBuf::pop. The example removes '..' from 'X:\foo\..' to get 'X:\foo'.

```rust
use std::path::Path;

use normpath::BasePathBuf;

if cfg!(windows) {
    let mut path = BasePathBuf::try_new(r"X:\foo\..").unwrap();
    assert!(path.pop_unchecked());
    assert_eq!(Path::new(r"X:\foo"), path);
}
```

--------------------------------

### starts_with

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::starts_with.

```APIDOC
## starts_with

### Description
Equivalent to Path::starts_with.

### Method
N/A (Rust method)

### Signature
pub fn starts_with<P>(&self, base: P) -> bool
where P: AsRef<Path>,

### Parameters
- base (P) - Required - The path prefix to check.

### Returns
- bool - True if the path starts with the given prefix.

```

--------------------------------

### as_os_str

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Returns a reference to the wrapped path as a platform string.

```APIDOC
## as_os_str

### Description
Returns a reference to the wrapped path as a platform string.

### Method
N/A (Rust method)

### Signature
pub fn as_os_str(&self) -> &OsStr

### Parameters
None

### Returns
- &OsStr - A reference to the platform string representation of the path.

```

--------------------------------

### BasePath implementation with new, try_new, and path accessors

Source: https://docs.rs/normpath/latest/src/normpath/base.rs.html

The full source of the `BasePath` type and its methods, including `new`, `try_new`, `as_os_str`, `as_path`, `canonicalize`, and `components`. It shows the internal `from_inner` helper and the `cow_path_into_base_path` function. The `new` method joins a missing prefix to the current directory on Windows and returns an error if reading the current directory fails.

```rust
use std::borrow::Borrow;
use std::borrow::Cow;
use std::cmp::Ordering;
use std::ffi::OsStr;
use std::ffi::OsString;
use std::fs::Metadata;
use std::fs::ReadDir;
use std::hash::Hash;
use std::hash::Hasher;
use std::io;
use std::mem;
use std::ops::Deref;
use std::path::Component;
use std::path::Components;
use std::path::Path;
use std::path::PathBuf;

use super::error::MissingPrefixBufError;
use super::error::MissingPrefixError;
use super::error::ParentError;
use super::imp;
use super::PathExt;

fn cow_path_into_base_path(path: Cow<'_, Path>) -> Cow<'_, BasePath> {
    debug_assert!(imp::is_base(&path));

    match path {
        Cow::Borrowed(path) => {
            Cow::Borrowed(BasePath::from_inner(path.as_os_str()))
        }
        Cow::Owned(path) => Cow::Owned(BasePathBuf(path)),
    }
}

/// A borrowed path that has a [prefix] on Windows.
///
/// Note that comparison traits such as [`PartialEq`] will compare paths
/// literally instead of comparing components. The former is more efficient and
/// easier to use correctly.
///
/// # Safety
///
/// This type should not be used for memory safety, but implementations can
/// panic if this path is missing a prefix on Windows. A safe `new_unchecked`
/// method might be added later that can safely create invalid base paths.
///
/// [prefix]: ::std::path::Prefix
#[derive(Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[repr(transparent)]
pub struct BasePath(pub(super) OsStr);

impl BasePath {
    pub(super) fn from_inner(path: &OsStr) -> &Self {
        // SAFETY: This struct has a layout that makes this operation safe.
        unsafe { mem::transmute(path) }
    }

    /// Creates a new base path.
    ///
    /// On Windows, if `path` is missing a [prefix], it will be joined to the
    /// current directory.
    ///
    /// # Errors
    ///
    /// Returns an error if reading the current directory fails.
    ///
    /// # Examples
    ///
    /// ```
    /// # use std::io;
    /// use std::path::Path;
    ///
    /// use normpath::BasePath;
    ///
    /// if cfg!(windows) {
    ///     let path = Path::new(r"X:\foo\bar");
    ///     assert_eq!(path, *BasePath::new(path)?);
    ///
    ///     assert!(BasePath::new(Path::new(r"foo\bar")).is_ok());
    /// }
    /// #
    /// # Ok::<_, io::Error>(())
    /// ```
    ///
    /// [prefix]: ::std::path::Prefix
    #[inline]
    pub fn new<'a, P>(path: P) -> io::Result<Cow<'a, Self>>
    where
        P: Into<Cow<'a, Path>>,
    {
        let path = path.into();
        match path {
            Cow::Borrowed(path) => Self::try_new(path)
                .map(Cow::Borrowed)
                .or_else(|_| imp::to_base(path).map(Cow::Owned)),
            Cow::Owned(path) => BasePathBuf::new(path).map(Cow::Owned),
        }
    }

    /// Returns a reference to the wrapped path as a platform string.
    #[inline]
    #[must_use]
    pub fn as_os_str(&self) -> &OsStr {
        &self.0
    }

    /// Returns a reference to the wrapped path.
    #[inline]
    #[must_use]
    pub fn as_path(&self) -> &Path {
        Path::new(&self.0)
    }

    /// Equivalent to [`Path::canonicalize`].
    #[inline]
    pub fn canonicalize(&self) -> io::Result<BasePathBuf> {
        self.as_path().canonicalize().map(|base| {
            debug_assert!(imp::is_base(&base));
            BasePathBuf(base)
        })
    }

    /// Equivalent to [`Path::components`].
    #[inline]
    pub fn components(&self) -> Components<'_> {
        self.as_path().components()
    }
```

--------------------------------

### BasePath::new

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Creates a new base path, joining to the current directory on Windows if the path lacks a prefix. Returns an error if reading the current directory fails.

```APIDOC
## BasePath::new

### Description
Creates a new base path. On Windows, if the path is missing a prefix, it will be joined to the current directory.

### Method
new

### Signature
pub fn new<'a, P>(path: P) -> Result<Cow<'a, Self>> where P: Into<Cow<'a, Path>>

### Parameters
- **path** (P) - Required - The path to create a base path from.

### Errors
Returns an error if reading the current directory fails.

### Example
rust
use std::path::Path;
use normpath::BasePath;

if cfg!(windows) {
    let path = Path::new(r"X:\foo\bar");
    assert_eq!(path, *BasePath::new(path)?);
    assert!(BasePath::new(Path::new(r"foo\bar")).is_ok());
}

```

--------------------------------

### components

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::components.

```APIDOC
## components

### Description
Equivalent to Path::components.

### Method
N/A (Rust method)

### Signature
pub fn components(&self) -> Components<'_>

### Parameters
None

### Returns
- Components<'_> - An iterator over the components of the path.

```

--------------------------------

### Normalize and pop path components to find target directory

Source: https://docs.rs/normpath

Shows how to use `PathExt::normalize` and `BasePathBuf::pop` to walk up a path until it ends with `target`. The function returns `Ok(Some(path))` when found, `Ok(None)` when the path is exhausted, and prints an error message if normalization fails.

```rust
use std::io;
use std::path::Path;

use normpath::BasePathBuf;
use normpath::PathExt;

fn find_target_dir(path: &Path) -> io::Result<Option<BasePathBuf>> {
    let mut path = path.normalize()?;
    while !path.ends_with("target") {
        match path.pop() {
            Ok(true) => continue,
            Ok(false) => {}
            Err(_) => {
                eprintln!("Some components could not be normalized.");
            }
        }
        return Ok(None);
    }
    Ok(Some(path))
}

```

--------------------------------

### impl PartialOrd<BasePathBuf> for Cow<'_, Path>

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

PartialOrd implementation allowing comparison between a Cow<Path> and a BasePathBuf.

```APIDOC
## impl PartialOrd<BasePathBuf> for Cow<'_, Path>

### Description
Allows comparing a Cow<Path> with a BasePathBuf using the standard comparison operators.

### Methods

#### partial_cmp(&self, other: &BasePathBuf) -> Option<Ordering>
Returns an ordering between self and other if one exists.

#### lt(&self, other: &Rhs) -> bool
Tests less than (for self and other) and is used by the < operator.

#### le(&self, other: &Rhs) -> bool
Tests less than or equal to (for self and other) and is used by the <= operator.

#### gt(&self, other: &Rhs) -> bool
Tests greater than (for self and other) and is used by the > operator.

#### ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for self and other) and is used by the >= operator.
```

--------------------------------

### impl PartialOrd<BasePathBuf> for Cow<'_, BasePath>

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

PartialOrd implementation for comparing a Cow<BasePath> with BasePathBuf.

```APIDOC
## impl PartialOrd<BasePathBuf> for Cow<'_, BasePath>

### Description
PartialOrd implementation for comparing a Cow<BasePath> with BasePathBuf.

### Methods

#### fn partial_cmp(&self, other: &BasePathBuf) -> Option<Ordering>
This method returns an ordering between `self` and `other` values if one exists.

#### fn lt(&self, other: &Rhs) -> bool
Tests less than (for `self` and `other`) and is used by the `<` operator.

#### fn le(&self, other: &Rhs) -> bool
Tests less than or equal to (for `self` and `other`) and is used by the `<=` operator.

#### fn gt(&self, other: &Rhs) -> bool
Tests greater than (for `self` and `other`) and is used by the `>` operator.

#### fn ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator.
```

--------------------------------

### impl PartialOrd<Cow<'_, Path>> for BasePathBuf

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

PartialOrd implementation allowing comparison between a Cow<Path> and a BasePathBuf.

```APIDOC
## impl PartialOrd<Cow<'_, Path>> for BasePathBuf

### Description
Allows comparing a Cow<Path> with a BasePathBuf using the standard comparison operators.

### Methods

#### partial_cmp(&self, other: &Cow<'_, Path>) -> Option<Ordering>
Returns an ordering between self and other if one exists.

#### lt(&self, other: &Rhs) -> bool
Tests less than (for self and other) and is used by the < operator.

#### le(&self, other: &Rhs) -> bool
Tests less than or equal to (for self and other) and is used by the <= operator.

#### gt(&self, other: &Rhs) -> bool
Tests greater than (for self and other) and is used by the > operator.

#### ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for self and other) and is used by the >= operator.
```

--------------------------------

### extension

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::extension.

```APIDOC
## extension

### Description
Equivalent to Path::extension.

### Method
N/A (Rust method)

### Signature
pub fn extension(&self) -> Option<&OsStr>

### Parameters
None

### Returns
- Option<&OsStr> - The extension of the file name, if any.

```

--------------------------------

### BasePathBuf::new

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Creates a new BasePathBuf from a path, equivalent to BasePath::new but returns an owned path. Returns an error if the path does not have a Windows prefix.

```APIDOC
## BasePathBuf::new

### Description
Creates a new BasePathBuf from a path, equivalent to BasePath::new but returns an owned path. Returns an error if the path does not have a Windows prefix.

### Method
new

### Signature
pub fn new<P>(path: P) -> Result<Self> where P: Into<PathBuf>

### Parameters
- **path** (P) - Required - The path to wrap, must implement Into<PathBuf>.

### Returns
- **Result<Self>** - Ok(BasePathBuf) if the path has a Windows prefix, otherwise an error.

### Example
```rust
use std::path::Path;
use normpath::BasePathBuf;

if cfg!(windows) {
    let path = r"X:\foo\bar";
    assert_eq!(Path::new(path), BasePathBuf::new(path)?);
    assert!(BasePathBuf::new(r"foo\bar").is_ok());
}
```
```

--------------------------------

### impl PartialOrd<Cow<'_, BasePath>> for BasePathBuf

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

PartialOrd implementation allowing comparison between a Cow<BasePath> and a BasePathBuf.

```APIDOC
## impl PartialOrd<Cow<'_, BasePath>> for BasePathBuf

### Description
Allows comparing a Cow<BasePath> with a BasePathBuf using the standard comparison operators.

### Methods

#### partial_cmp(&self, other: &Cow<'_, BasePath>) -> Option<Ordering>
Returns an ordering between self and other if one exists.

#### lt(&self, other: &Rhs) -> bool
Tests less than (for self and other) and is used by the < operator.

#### le(&self, other: &Rhs) -> bool
Tests less than or equal to (for self and other) and is used by the <= operator.

#### gt(&self, other: &Rhs) -> bool
Tests greater than (for self and other) and is used by the > operator.

#### ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for self and other) and is used by the >= operator.
```

--------------------------------

### as_path

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Returns a reference to the wrapped path.

```APIDOC
## as_path

### Description
Returns a reference to the wrapped path.

### Method
N/A (Rust method)

### Signature
pub fn as_path(&self) -> &Path

### Parameters
None

### Returns
- &Path - A reference to the wrapped path.

```

--------------------------------

### BasePathBuf::try_new

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Creates a new BasePathBuf from a path, equivalent to BasePath::try_new but returns an owned path. Returns a MissingPrefixBufError if the path does not have a Windows prefix.

```APIDOC
## BasePathBuf::try_new

### Description
Creates a new BasePathBuf from a path, equivalent to BasePath::try_new but returns an owned path. Returns a MissingPrefixBufError if the path does not have a Windows prefix.

### Method
try_new

### Signature
pub fn try_new<P>(path: P) -> Result<Self, MissingPrefixBufError> where P: Into<PathBuf>

### Parameters
- **path** (P) - Required - The path to wrap, must implement Into<PathBuf>.

### Returns
- **Result<Self, MissingPrefixBufError>** - Ok(BasePathBuf) if the path has a Windows prefix, otherwise Err(MissingPrefixBufError).

### Example
```rust
use std::path::Path;
use normpath::BasePathBuf;

if cfg!(windows) {
    let path = r"X:\foo\bar";
    assert_eq!(Path::new(path), BasePathBuf::try_new(path)?);
    assert!(BasePathBuf::try_new(r"foo\bar").is_err());
}
```
```

--------------------------------

### file_name

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::file_name.

```APIDOC
## file_name

### Description
Equivalent to Path::file_name.

### Method
N/A (Rust method)

### Signature
pub fn file_name(&self) -> Option<&OsStr>

### Parameters
None

### Returns
- Option<&OsStr> - The file name of the path, if any.

```

--------------------------------

### BasePathBuf::into_os_string

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Returns the wrapped path as a platform string (OsString).

```APIDOC
## BasePathBuf::into_os_string

### Description
Returns the wrapped path as a platform string (OsString).

### Method
into_os_string

### Signature
pub fn into_os_string(self) -> OsString

### Returns
- **OsString** - The wrapped path as an OS string.
```

--------------------------------

### expand

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to PathExt::expand.

```APIDOC
## expand

### Description
Equivalent to PathExt::expand.

### Method
N/A (Rust method)

### Signature
pub fn expand(&self) -> Result<Cow<'_, Self>>

### Parameters
None

### Returns
- Result<Cow<'_, Self>> - The expanded path.

```

--------------------------------

### join

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

An improved version of Path::join that handles more edge cases.

```APIDOC
## join

### Description
An improved version of Path::join that handles more edge cases. For example, on Windows, leading . and .. components of path will be normalized if possible. If self is a verbatim path, it would be invalid to normalize them later. You should still call normalize before parent to normalize some additional components.

### Method
N/A (Rust method)

### Signature
pub fn join<P>(&self, path: P) -> BasePathBuf
where P: AsRef<Path>,

### Parameters
- path (P) - Required - The path to join.

### Returns
- BasePathBuf - The joined path.

### Examples
```
use std::path::Path;

use normpath::BasePath;

if cfg!(windows) {
    assert_eq!(
        Path::new(r"\\?\foo\baz\test.rs"),
        BasePath::try_new(r"\\?\foo\bar")
            .unwrap()
            .join("../baz/test.rs"),
    );
}
```

```

--------------------------------

### metadata

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::metadata.

```APIDOC
## metadata

### Description
Equivalent to Path::metadata.

### Method
N/A (Rust method)

### Signature
pub fn metadata(&self) -> Result<Metadata>

### Parameters
None

### Returns
- Result<Metadata> - The metadata of the path.

```

--------------------------------

### pub fn try_exists(&self) -> Result<bool>

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Checks whether the path exists. Equivalent to Path::try_exists.

```APIDOC
## pub fn try_exists(&self) -> Result<bool>

### Description
Checks whether the path exists. Equivalent to `Path::try_exists`.

### Method
`try_exists`

### Signature
`pub fn try_exists(&self) -> Result<bool>`

### Parameters
- `self` - The `BasePath` instance.

### Returns
- `Result<bool>` - A result containing `true` if the path exists, `false` otherwise, or an error.
```

--------------------------------

### BasePath::components

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Equivalent to Path::components. Returns the components of the path.

```APIDOC
## BasePath::components

### Description
Equivalent to `Path::components`.

### Method
components

### Signature
pub fn components(&self) -> Components<'_>

### Returns
- **Components<'_>** - The components of the path.
```

--------------------------------

### BasePathBuf::try_new

Source: https://docs.rs/normpath/latest/src/normpath/base.rs.html

Creates a new BasePathBuf from a path, returning an error if the path does not have a base prefix. This is the non-normalizing constructor.

```APIDOC
## BasePathBuf::try_new

### Description
Creates a new `BasePathBuf` from a path, returning an error if the path does not have a base prefix. This is the non-normalizing constructor.

### Method
`pub fn try_new<P>(path: P) -> Result<Self, MissingPrefixBufError> where P: Into<PathBuf>`

### Parameters
- `path` (P) - Required - The path to create a `BasePathBuf` from.

### Returns
- `Result<Self, MissingPrefixBufError>` - The resulting `BasePathBuf` or a `MissingPrefixBufError` if the path lacks a base prefix.

### Example
```rust
use std::path::Path;
use normpath::BasePathBuf;

let path = r"X:\foo\bar";
assert_eq!(Path::new(path), BasePathBuf::try_new(path)?);
assert!(BasePathBuf::try_new(r"foo\bar").is_err());
```
```

--------------------------------

### BasePath::expand

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Equivalent to PathExt::expand. Expands the path.

```APIDOC
## BasePath::expand

### Description
Equivalent to `PathExt::expand`.

### Method
expand

### Signature
pub fn expand(&self) -> Result<Cow<'_, Self>>

### Returns
- **Result<Cow<'_, Self>>** - The expanded path.
```

--------------------------------

### BasePath::try_new

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Creates a new base path, returning an error on Windows if the path is missing a prefix. This method is useful for validating that a path has a prefix.

```APIDOC
## BasePath::try_new

### Description
Creates a new base path. On Windows, returns an error if the path is missing a prefix.

### Method
try_new

### Signature
pub fn try_new<P>(path: &P) -> Result<&Self, MissingPrefixError> where P: AsRef<Path> + ?Sized

### Parameters
- **path** (&P) - Required - The path to create a base path from.

### Errors
On Windows, returns an error if the path is missing a prefix.

### Example
rust
use std::path::Path;
use normpath::BasePath;

if cfg!(windows) {
    let path = r"X:\foo\bar";
    assert_eq!(Path::new(path), BasePath::try_new(path)?);
    assert!(BasePath::try_new(r"foo\bar").is_err());
}

```

--------------------------------

### BasePath::join

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

An improved version of Path::join that handles more edge cases, such as normalizing leading . and .. components on Windows.

```APIDOC
## BasePath::join

### Description
An improved version of `Path::join` that handles more edge cases. For example, on Windows, leading `.` and `..` components of `path` will be normalized if possible.

### Method
join

### Signature
pub fn join<P>(&self, path: P) -> BasePathBuf where P: AsRef<Path>

### Parameters
- **path** (P) - Required - The path to join.

### Returns
- **BasePathBuf** - The joined path.

### Example
rust
use std::path::Path;
use normpath::BasePath;

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

```

--------------------------------

### MissingPrefixBufError::as_path

Source: https://docs.rs/normpath/latest/normpath/error/struct.MissingPrefixBufError.html

Returns a reference to the path that caused this error.

```APIDOC
## MissingPrefixBufError::as_path

### Description
Returns a reference to the path that caused this error.

### Method
as_path

### Signature
pub fn as_path(&self) -> &Path

### Parameters
None

### Returns
- **&Path** - A reference to the path that caused the error.

```

--------------------------------

### file_stem

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::file_stem.

```APIDOC
## file_stem

### Description
Equivalent to Path::file_stem.

### Method
N/A (Rust method)

### Signature
pub fn file_stem(&self) -> Option<&OsStr>

### Parameters
None

### Returns
- Option<&OsStr> - The file stem of the path, if any.

```

--------------------------------

### is_file

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::is_file.

```APIDOC
## is_file

### Description
Equivalent to Path::is_file.

### Method
N/A (Rust method)

### Signature
pub fn is_file(&self) -> bool

### Parameters
None

### Returns
- bool - True if the path is a file.

```

--------------------------------

### BasePathBuf::new

Source: https://docs.rs/normpath/latest/src/normpath/base.rs.html

Creates a new BasePathBuf from a path, normalizing it to have a base prefix. Returns an io::Result, converting errors from normalization.

```APIDOC
## BasePathBuf::new

### Description
Creates a new `BasePathBuf` from a path, normalizing it to have a base prefix. Returns an `io::Result`, converting errors from normalization.

### Method
`pub fn new<P>(path: P) -> io::Result<Self> where P: Into<PathBuf>`

### Parameters
- `path` (P) - Required - The path to create a `BasePathBuf` from.

### Returns
- `io::Result<Self>` - The resulting `BasePathBuf` or an I/O error.

### Example
```rust
use std::path::Path;
use normpath::BasePathBuf;

let path = r"X:\foo\bar";
assert_eq!(Path::new(path), BasePathBuf::new(path)?);
assert!(BasePathBuf::new(r"foo\bar").is_ok());
```
```

--------------------------------

### exists

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::exists.

```APIDOC
## exists

### Description
Equivalent to Path::exists.

### Method
N/A (Rust method)

### Signature
pub fn exists(&self) -> bool

### Parameters
None

### Returns
- bool - True if the path exists.

```

--------------------------------

### BasePathBuf::push

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to BasePath::join but modifies self in place.

```APIDOC
## BasePathBuf::push

### Description
Equivalent to BasePath::join but modifies self in place.

### Method
push

### Signature
pub fn push<P>(&mut self, path: P) where P: AsRef<Path>

### Parameters
- **path** (P) - Required - The path to push, must implement AsRef<Path>.

### Example
```rust
use std::path::Path;
use normpath::BasePathBuf;

if cfg!(windows) {
    let mut path = BasePathBuf::try_new(r"\\?\foo\bar").unwrap();
    path.push("../baz/test.rs");
    assert_eq!(Path::new(r"\\?\foo\baz\test.rs"), path);
}
```
```

--------------------------------

### impl PartialOrd<BasePathBuf> for &Path

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

PartialOrd implementation allowing comparison between a reference to Path and a BasePathBuf.

```APIDOC
## impl PartialOrd<BasePathBuf> for &Path

### Description
Allows comparing a reference to a Path with a BasePathBuf using the standard comparison operators.

### Methods

#### partial_cmp(&self, other: &BasePathBuf) -> Option<Ordering>
Returns an ordering between self and other if one exists.

#### lt(&self, other: &Rhs) -> bool
Tests less than (for self and other) and is used by the < operator.

#### le(&self, other: &Rhs) -> bool
Tests less than or equal to (for self and other) and is used by the <= operator.

#### gt(&self, other: &Rhs) -> bool
Tests greater than (for self and other) and is used by the > operator.

#### ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for self and other) and is used by the >= operator.
```

--------------------------------

### symlink_metadata

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::symlink_metadata.

```APIDOC
## symlink_metadata

### Description
Equivalent to Path::symlink_metadata.

### Method
N/A (Rust method)

### Signature
pub fn symlink_metadata(&self) -> Result<Metadata>

### Parameters
None

### Returns
- Result<Metadata> - The metadata of the path, not following symlinks.

```

--------------------------------

### expand

Source: https://docs.rs/normpath/latest/normpath/trait.PathExt.html

Expands a path to its full form. Implemented for Path.

```APIDOC
## expand

### Description
Expands a path to its full form.

### Method
expand

### Signature
fn expand(&self) -> Result<Cow<'_, Self>>

### Parameters
None

### Errors
Not specified in source.

### Example
Not provided in source.
```

--------------------------------

### pub fn shorten(&self) -> Result<Cow<'_, Self>>

Source: https://docs.rs/normpath/latest/normpath/struct.BasePath.html

Shortens the path to its shortest equivalent form. Equivalent to PathExt::shorten.

```APIDOC
## pub fn shorten(&self) -> Result<Cow<'_, Self>>

### Description
Shortens the path to its shortest equivalent form. Equivalent to `PathExt::shorten`.

### Method
`shorten`

### Signature
`pub fn shorten(&self) -> Result<Cow<'_, Self>>`

### Parameters
- `self` - The `BasePath` instance.

### Returns
- `Result<Cow<'_, Self>>` - A result containing a borrowed or owned `BasePath` on success, or an error.
```

--------------------------------

### impl PartialOrd<BasePathBuf> for PathBuf

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

PartialOrd implementation allowing comparison between a PathBuf and a BasePathBuf.

```APIDOC
## impl PartialOrd<BasePathBuf> for PathBuf

### Description
Allows comparing a PathBuf with a BasePathBuf using the standard comparison operators.

### Methods

#### partial_cmp(&self, other: &BasePathBuf) -> Option<Ordering>
Returns an ordering between self and other if one exists.

#### lt(&self, other: &Rhs) -> bool
Tests less than (for self and other) and is used by the < operator.

#### le(&self, other: &Rhs) -> bool
Tests less than or equal to (for self and other) and is used by the <= operator.

#### gt(&self, other: &Rhs) -> bool
Tests greater than (for self and other) and is used by the > operator.

#### ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for self and other) and is used by the >= operator.
```

--------------------------------

### impl Serialize for BasePathBuf

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Provides Serde serialization support for BasePathBuf when the serde feature is enabled.

```APIDOC
## impl Serialize for BasePathBuf

### Description
Provides Serde serialization support for BasePathBuf when the serde feature is enabled.

### Methods

#### fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where S: Serializer
Serialize this value into the given Serde serializer.
```

--------------------------------

### read_dir

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::read_dir.

```APIDOC
## read_dir

### Description
Equivalent to Path::read_dir.

### Method
N/A (Rust method)

### Signature
pub fn read_dir(&self) -> Result<ReadDir>

### Parameters
None

### Returns
- Result<ReadDir> - An iterator over the entries in the directory.

```

--------------------------------

### impl PartialOrd<BasePath> for BasePathBuf

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

PartialOrd implementation for comparing BasePathBuf with BasePath.

```APIDOC
## impl PartialOrd<BasePath> for BasePathBuf

### Description
PartialOrd implementation for comparing BasePathBuf with BasePath.

### Methods

#### fn partial_cmp(&self, other: &BasePath) -> Option<Ordering>
This method returns an ordering between `self` and `other` values if one exists.

#### fn lt(&self, other: &Rhs) -> bool
Tests less than (for `self` and `other`) and is used by the `<` operator.

#### fn le(&self, other: &Rhs) -> bool
Tests less than or equal to (for `self` and `other`) and is used by the `<=` operator.

#### fn gt(&self, other: &Rhs) -> bool
Tests greater than (for `self` and `other`) and is used by the `>` operator.

#### fn ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator.
```

--------------------------------

### normalize

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to PathExt::normalize.

```APIDOC
## normalize

### Description
Equivalent to PathExt::normalize.

### Method
N/A (Rust method)

### Signature
pub fn normalize(&self) -> Result<BasePathBuf>

### Parameters
None

### Returns
- Result<BasePathBuf> - The normalized path.

```

--------------------------------

### try_exists

Source: https://docs.rs/normpath/latest/normpath/struct.BasePathBuf.html

Equivalent to Path::try_exists.

```APIDOC
## try_exists

### Description
Equivalent to Path::try_exists.

### Method
N/A (Rust method)

### Signature
pub fn try_exists(&self) -> Result<bool>

### Parameters
None

### Returns
- Result<bool> - True if the path exists, or an error if the existence cannot be determined.

```
Tokens:
Raw