Struct SystemPathBuf 

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

An owned, mutable path on System (akin to String).

The path is guaranteed to be valid UTF-8.

Implementations

impl SystemPathBuf

pub fn new() -> Self

pub fn from_utf8_path_buf(path: Utf8PathBuf) -> Self

pub fn from_path_buf(path: PathBuf) -> Result<Self, PathBuf>

pub fn from_path_buf_lossy(path: PathBuf) -> Self

Try to convert from path directly, falling back to the lossy string representation on error.

pub fn push(&mut self, path: impl AsRef<SystemPath>)

Extends self with path.

If path is absolute, it replaces the current path.

On Windows:

• if path has a root but no prefix (e.g., \windows), it replaces everything except for the prefix (if any) of self.
• if path has a prefix but no root, it replaces self.

Examples

Pushing a relative path extends the existing path:

use ruff_db::system::SystemPathBuf;

let mut path = SystemPathBuf::from("/tmp");
path.push("file.bk");
assert_eq!(path, SystemPathBuf::from("/tmp/file.bk"));

Pushing an absolute path replaces the existing path:

use ruff_db::system::SystemPathBuf;

let mut path = SystemPathBuf::from("/tmp");
path.push("/etc");
assert_eq!(path, SystemPathBuf::from("/etc"));

pub fn into_utf8_path_buf(self) -> Utf8PathBuf

pub fn into_std_path_buf(self) -> PathBuf

pub fn into_string(self) -> String

pub fn as_path(&self) -> &SystemPath

Methods from Deref<Target = SystemPath>

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"\\\\").

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());

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.

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"));

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

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);

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);

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)

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());

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());

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")));

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"));

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"));

pub fn to_path_buf(&self) -> SystemPathBuf

Converts the path to an owned SystemPathBuf.

pub fn as_str(&self) -> &str

Returns the path as a string slice.

pub fn as_std_path(&self) -> &Path

Returns the std path for the file.

pub fn as_utf8_path(&self) -> &Utf8Path

Returns the Utf8Path for the file.

Trait Implementations

impl AsRef<Path> for SystemPathBuf

fn as_ref(&self) -> &Path

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<SystemPath> for SystemPathBuf

fn as_ref(&self) -> &SystemPath

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<SystemPath> for SystemPathBuf

fn borrow(&self) -> &SystemPath

Immutably borrows from an owned value.

impl Clone for SystemPathBuf

fn clone(&self) -> SystemPathBuf

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SystemPathBuf

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

Formats the value using the given formatter.

impl Default for SystemPathBuf

fn default() -> Self

Returns the “default value” for a type.

impl Deref for SystemPathBuf

type Target = SystemPath

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for SystemPathBuf

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

Formats the value using the given formatter.

impl Eq for SystemPathBuf

impl<P: AsRef<SystemPath>> Extend<P> for SystemPathBuf

fn extend<I: IntoIterator<Item = P>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<&str> for SystemPathBuf

fn from(value: &str) -> Self

Converts to this type from the input type.

impl From<String> for SystemPathBuf

fn from(value: String) -> Self

Converts to this type from the input type.

impl From<SystemPathBuf> for FilePath

fn from(value: SystemPathBuf) -> Self

Converts to this type from the input type.

impl From<SystemPathBuf> for Box<SystemPath>

fn from(path: SystemPathBuf) -> Self

Converts to this type from the input type.

impl<P: AsRef<SystemPath>> FromIterator<P> for SystemPathBuf

fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> Self

Creates a value from an iterator.

impl GetSize for SystemPathBuf

fn get_heap_size_with_tracker<T: GetSizeTracker>( &self, tracker: T, ) -> (usize, T)

Determines how many bytes this object occupies inside the heap while using a tracker.

fn get_stack_size() -> usize

Determines how may bytes this object occupies inside the stack.

fn get_heap_size(&self) -> usize

Determines how many bytes this object occupies inside the heap.

fn get_size(&self) -> usize

Determines the total size of the object.

fn get_size_with_tracker<T>(&self, tracker: T) -> (usize, T)

where T: GetSizeTracker,

Determines the total size of the object while using a tracker.

impl Hash for SystemPathBuf

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SystemPathBuf

fn cmp(&self, other: &SystemPathBuf) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for SystemPathBuf

fn eq(&self, other: &SystemPathBuf) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<FilePath> for SystemPathBuf

fn eq(&self, other: &FilePath) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<SystemPathBuf> for FilePath

fn eq(&self, other: &SystemPathBuf) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for SystemPathBuf

fn partial_cmp(&self, other: &SystemPathBuf) -> 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 StructuralPartialEq for SystemPathBuf