Struct SystemPath

Source

pub struct SystemPath(/* private fields */);

Expand description

A slice of a path on System (akin to str).

The path is guaranteed to be valid UTF-8.

Implementations§

Source §

impl SystemPath

Source

pub fn new(path: &(impl AsRef<Utf8Path> + ?Sized)) -> &Self

Source

pub fn simplified(&self) -> &SystemPath

Takes any path, and when possible, converts Windows UNC paths to regular paths. If the path can’t be converted, it’s returned unmodified.

On non-Windows this is no-op.

\\?\C:\Windows will be converted to C:\Windows, but \\?\C:\COM will be left as-is (due to a reserved filename).

Use this to pass arbitrary paths to programs that may not be UNC-aware.

It’s generally safe to pass UNC paths to legacy programs, because these paths contain a reserved prefix, so will gracefully fail if used with legacy APIs that don’t support UNC.

This function does not perform any I/O.

Currently paths with unpaired surrogates aren’t converted even if they could be, due to limitations of Rust’s OsStr API.

To check if a path remained as UNC, use path.as_os_str().as_encoded_bytes().starts_with(b"\\\\").

Source

pub fn is_absolute(&self) -> bool

Returns true if the SystemPath is absolute, i.e., if it is independent of the current directory.

On Unix, a path is absolute if it starts with the root, so is_absolute and has_root are equivalent.
On Windows, a path is absolute if it has a prefix and starts with the root: c:\windows is absolute, while c:temp and \temp are not.

§Examples

use ruff_db::system::SystemPath;

assert!(!SystemPath::new("foo.txt").is_absolute());

Source

pub fn extension(&self) -> Option<&str>

Extracts the file extension, if possible.

The extension is:

None, if there is no file name;
None, if there is no embedded .;
None, if the file name begins with . and has no other .s within;
Otherwise, the portion of the file name after the final .

§Examples

use ruff_db::system::SystemPath;

assert_eq!("rs", SystemPath::new("foo.rs").extension().unwrap());
assert_eq!("gz", SystemPath::new("foo.tar.gz").extension().unwrap());

See Path::extension for more details.

Source

pub fn starts_with(&self, base: impl AsRef<SystemPath>) -> bool

Determines whether base is a prefix of self.

Only considers whole path components to match.

§Examples

use ruff_db::system::SystemPath;

let path = SystemPath::new("/etc/passwd");

assert!(path.starts_with("/etc"));
assert!(path.starts_with("/etc/"));
assert!(path.starts_with("/etc/passwd"));
assert!(path.starts_with("/etc/passwd/")); // extra slash is okay
assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay

assert!(!path.starts_with("/e"));
assert!(!path.starts_with("/etc/passwd.txt"));

assert!(!SystemPath::new("/etc/foo.rs").starts_with("/etc/foo"));

Source

pub fn ends_with(&self, child: impl AsRef<SystemPath>) -> bool

Determines whether child is a suffix of self.

Only considers whole path components to match.

§Examples

use ruff_db::system::SystemPath;

let path = SystemPath::new("/etc/resolv.conf");

assert!(path.ends_with("resolv.conf"));
assert!(path.ends_with("etc/resolv.conf"));
assert!(path.ends_with("/etc/resolv.conf"));

assert!(!path.ends_with("/resolv.conf"));
assert!(!path.ends_with("conf")); // use .extension() instead

Source

pub fn parent(&self) -> Option<&SystemPath>

Returns the FileSystemPath without its final component, if there is one.

Returns None if the path terminates in a root or prefix.

§Examples

use ruff_db::system::SystemPath;

let path = SystemPath::new("/foo/bar");
let parent = path.parent().unwrap();
assert_eq!(parent, SystemPath::new("/foo"));

let grand_parent = parent.parent().unwrap();
assert_eq!(grand_parent, SystemPath::new("/"));
assert_eq!(grand_parent.parent(), None);

Source

pub fn ancestors(&self) -> impl Iterator<Item = &SystemPath>

Produces an iterator over SystemPath and its ancestors.

The iterator will yield the SystemPath that is returned if the parent method is used zero or more times. That means, the iterator will yield &self, &self.parent().unwrap(), &self.parent().unwrap().parent().unwrap() and so on. If the parent method returns None, the iterator will do likewise. The iterator will always yield at least one value, namely &self.

§Examples

use ruff_db::system::SystemPath;

let mut ancestors = SystemPath::new("/foo/bar").ancestors();
assert_eq!(ancestors.next(), Some(SystemPath::new("/foo/bar")));
assert_eq!(ancestors.next(), Some(SystemPath::new("/foo")));
assert_eq!(ancestors.next(), Some(SystemPath::new("/")));
assert_eq!(ancestors.next(), None);

let mut ancestors = SystemPath::new("../foo/bar").ancestors();
assert_eq!(ancestors.next(), Some(SystemPath::new("../foo/bar")));
assert_eq!(ancestors.next(), Some(SystemPath::new("../foo")));
assert_eq!(ancestors.next(), Some(SystemPath::new("..")));
assert_eq!(ancestors.next(), Some(SystemPath::new("")));
assert_eq!(ancestors.next(), None);

Source

pub fn components(&self) -> Utf8Components<'_> ⓘ

Produces an iterator over the camino::Utf8Components of the path.

When parsing the path, there is a small amount of normalization:

Repeated separators are ignored, so a/b and a//b both have a and b as components.
Occurrences of . are normalized away, except if they are at the beginning of the path. For example, a/./b, a/b/, a/b/. and a/b all have a and b as components, but ./a/b starts with an additional CurDir component.
A trailing slash is normalized away, /a/b and /a/b/ are equivalent.

Note that no other normalization takes place; in particular, a/c and a/b/../c are distinct, to account for the possibility that b is a symbolic link (so its parent isn’t a).

§Examples

use camino::{Utf8Component};
use ruff_db::system::SystemPath;

let mut components = SystemPath::new("/tmp/foo.txt").components();

assert_eq!(components.next(), Some(Utf8Component::RootDir));
assert_eq!(components.next(), Some(Utf8Component::Normal("tmp")));
assert_eq!(components.next(), Some(Utf8Component::Normal("foo.txt")));
assert_eq!(components.next(), None)

Source

pub fn file_name(&self) -> Option<&str>

Returns the final component of the FileSystemPath, if there is one.

If the path is a normal file, this is the file name. If it’s the path of a directory, this is the directory name.

Returns None if the path terminates in ...

§Examples

use camino::Utf8Path;
use ruff_db::system::SystemPath;

assert_eq!(Some("bin"), SystemPath::new("/usr/bin/").file_name());
assert_eq!(Some("foo.txt"), SystemPath::new("tmp/foo.txt").file_name());
assert_eq!(Some("foo.txt"), SystemPath::new("foo.txt/.").file_name());
assert_eq!(Some("foo.txt"), SystemPath::new("foo.txt/.//").file_name());
assert_eq!(None, SystemPath::new("foo.txt/..").file_name());
assert_eq!(None, SystemPath::new("/").file_name());

Source

pub fn file_stem(&self) -> Option<&str>

Extracts the stem (non-extension) portion of self.file_name.

The stem is:

None, if there is no file name;
The entire file name if there is no embedded .;
The entire file name if the file name begins with . and has no other .s within;
Otherwise, the portion of the file name before the final .

§Examples

use ruff_db::system::SystemPath;

assert_eq!("foo", SystemPath::new("foo.rs").file_stem().unwrap());
assert_eq!("foo.tar", SystemPath::new("foo.tar.gz").file_stem().unwrap());

Source

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

Returns a path that, when joined onto base, yields self.

§Errors

If base is not a prefix of self (i.e., starts_with returns false), returns Err.

§Examples

use ruff_db::system::{SystemPath, SystemPathBuf};

let path = SystemPath::new("/test/haha/foo.txt");

assert_eq!(path.strip_prefix("/"), Ok(SystemPath::new("test/haha/foo.txt")));
assert_eq!(path.strip_prefix("/test"), Ok(SystemPath::new("haha/foo.txt")));
assert_eq!(path.strip_prefix("/test/"), Ok(SystemPath::new("haha/foo.txt")));
assert_eq!(path.strip_prefix("/test/haha/foo.txt"), Ok(SystemPath::new("")));
assert_eq!(path.strip_prefix("/test/haha/foo.txt/"), Ok(SystemPath::new("")));

assert!(path.strip_prefix("test").is_err());
assert!(path.strip_prefix("/haha").is_err());

let prefix = SystemPathBuf::from("/test/");
assert_eq!(path.strip_prefix(prefix), Ok(SystemPath::new("haha/foo.txt")));

Source

pub fn join(&self, path: impl AsRef<SystemPath>) -> SystemPathBuf

Creates an owned SystemPathBuf with path adjoined to self.

See std::path::PathBuf::push for more details on what it means to adjoin a path.

§Examples

use ruff_db::system::{SystemPath, SystemPathBuf};

assert_eq!(SystemPath::new("/etc").join("passwd"), SystemPathBuf::from("/etc/passwd"));

Source

pub fn with_extension(&self, extension: &str) -> SystemPathBuf

Creates an owned SystemPathBuf like self but with the given extension.

See std::path::PathBuf::set_extension for more details.

§Examples

use ruff_db::system::{SystemPath, SystemPathBuf};

let path = SystemPath::new("foo.rs");
assert_eq!(path.with_extension("txt"), SystemPathBuf::from("foo.txt"));

let path = SystemPath::new("foo.tar.gz");
assert_eq!(path.with_extension(""), SystemPathBuf::from("foo.tar"));
assert_eq!(path.with_extension("xz"), SystemPathBuf::from("foo.tar.xz"));
assert_eq!(path.with_extension("").with_extension("txt"), SystemPathBuf::from("foo.txt"));

Source

pub fn to_path_buf(&self) -> SystemPathBuf

Converts the path to an owned SystemPathBuf.

Source

pub fn as_str(&self) -> &str

Returns the path as a string slice.

Source

pub fn as_std_path(&self) -> &Path

Returns the std path for the file.

Source

pub fn as_utf8_path(&self) -> &Utf8Path

Returns the Utf8Path for the file.

Source

pub fn from_std_path(path: &Path) -> Option<&SystemPath>

Source

pub fn absolute( path: impl AsRef<SystemPath>, cwd: impl AsRef<SystemPath>, ) -> SystemPathBuf

Makes a path absolute and normalizes it without accessing the file system.

Adapted from cargo

§Examples

§Posix paths

  use ruff_db::system::{SystemPath, SystemPathBuf};

  // Relative to absolute
  let absolute = SystemPath::absolute("foo/./bar", "/tmp");
  assert_eq!(absolute, SystemPathBuf::from("/tmp/foo/bar"));

  // Path's going past the root are normalized to the root
  let absolute = SystemPath::absolute("../../../", "/tmp");
  assert_eq!(absolute, SystemPathBuf::from("/"));

  // Absolute to absolute
  let absolute = SystemPath::absolute("/foo//test/.././bar.rs", "/tmp");
  assert_eq!(absolute, SystemPathBuf::from("/foo/bar.rs"));

§Windows paths

  use ruff_db::system::{SystemPath, SystemPathBuf};

  // Relative to absolute
  let absolute = SystemPath::absolute(r"foo\.\bar", r"C:\tmp");
  assert_eq!(absolute, SystemPathBuf::from(r"C:\tmp\foo\bar"));

  // Path's going past the root are normalized to the root
  let absolute = SystemPath::absolute(r"..\..\..\", r"C:\tmp");
  assert_eq!(absolute, SystemPathBuf::from(r"C:\"));

  // Absolute to absolute
  let absolute = SystemPath::absolute(r"C:\foo//test\..\./bar.rs", r"C:\tmp");
  assert_eq!(absolute, SystemPathBuf::from(r"C:\foo\bar.rs"));