Struct typed_path::PathBuf
source · pub struct PathBuf<T>where
T: for<'enc> Encoding<'enc>,{ /* private fields */ }
Expand description
An owned, mutable path that mirrors std::path::PathBuf
, but operatings using an
Encoding
to determine how to parse the underlying bytes.
This type provides methods like push
and set_extension
that mutate
the path in place. It also implements Deref
to Path
, meaning that
all methods on Path
slices are available on PathBuf
values as well.
§Examples
You can use push
to build up a PathBuf
from
components:
use typed_path::{PathBuf, WindowsEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = PathBuf::<WindowsEncoding>::new();
path.push(r"C:\");
path.push("windows");
path.push("system32");
path.set_extension("dll");
However, push
is best used for dynamic situations. This is a better way
to do this when you know all of the components ahead of time:
use typed_path::{PathBuf, WindowsEncoding};
let path: PathBuf<WindowsEncoding> = [r"C:\", "windows", "system32.dll"].iter().collect();
We can still do better than this! Since these are all strings, we can use
From::from
:
use typed_path::{PathBuf, WindowsEncoding};
let path = PathBuf::<WindowsEncoding>::from(br"C:\windows\system32.dll");
Which method works best depends on what kind of situation you’re in.
Implementations§
source§impl<T> PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PathBuf<T>where
T: for<'enc> Encoding<'enc>,
sourcepub fn new() -> Self
pub fn new() -> Self
Allocates an empty PathBuf
.
§Examples
use typed_path::{PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let path = PathBuf::<UnixEncoding>::new();
sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Creates a new PathBuf
with a given capacity used to create the
internal Vec<u8>
. See with_capacity
defined on Vec
.
§Examples
use typed_path::{PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = PathBuf::<UnixEncoding>::with_capacity(10);
let capacity = path.capacity();
// This push is done without reallocating
path.push(r"C:\");
assert_eq!(capacity, path.capacity());
sourcepub fn push<P: AsRef<Path<T>>>(&mut self, path: P)
pub fn push<P: AsRef<Path<T>>>(&mut self, path: P)
Extends self
with path
.
If path
is absolute, it replaces the current path.
With WindowsPathBuf
:
- if
path
has a root but no prefix (e.g.,\windows
), it replaces everything except for the prefix (if any) ofself
. - if
path
has a prefix but no root, it replacesself
. - if
self
has a verbatim prefix (e.g.\\?\C:\windows
) andpath
is not empty, the new path is normalized: all references to.
and..
are removed.
§Examples
Pushing a relative path extends the existing path:
use typed_path::{PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = PathBuf::<UnixEncoding>::from("/tmp");
path.push("file.bk");
assert_eq!(path, PathBuf::from("/tmp/file.bk"));
Pushing an absolute path replaces the existing path:
use typed_path::{PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = PathBuf::<UnixEncoding>::from("/tmp");
path.push("/etc");
assert_eq!(path, PathBuf::from("/etc"));
sourcepub fn push_checked<P: AsRef<Path<T>>>(
&mut self,
path: P
) -> Result<(), CheckedPathError>
pub fn push_checked<P: AsRef<Path<T>>>( &mut self, path: P ) -> Result<(), CheckedPathError>
Like PathBuf::push
, extends self
with path
, but also checks to ensure that path
abides by a set of rules.
§Rules
path
cannot contain a prefix component.path
cannot contain a root component.path
cannot contain invalid filename bytes.path
cannot contain parent components such that the current path would be escaped.
§Examples
Pushing a relative path extends the existing path:
use typed_path::{PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = PathBuf::<UnixEncoding>::from("/tmp");
// Pushing a relative path works like normal
assert!(path.push_checked("file.bk").is_ok());
assert_eq!(path, PathBuf::from("/tmp/file.bk"));
Pushing a relative path that contains unresolved parent directory references fails with an error:
use typed_path::{CheckedPathError, PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = PathBuf::<UnixEncoding>::from("/tmp");
// Pushing a relative path that contains parent directory references that cannot be
// resolved within the path is considered an error as this is considered a path
// traversal attack!
assert_eq!(path.push_checked(".."), Err(CheckedPathError::PathTraversalAttack));
assert_eq!(path, PathBuf::from("/tmp"));
Pushing an absolute path fails with an error:
use typed_path::{CheckedPathError, PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = PathBuf::<UnixEncoding>::from("/tmp");
// Pushing an absolute path will fail with an error
assert_eq!(path.push_checked("/etc"), Err(CheckedPathError::UnexpectedRoot));
assert_eq!(path, PathBuf::from("/tmp"));
sourcepub fn pop(&mut self) -> bool
pub fn pop(&mut self) -> bool
Truncates self
to self.parent
.
Returns false
and does nothing if self.parent
is None
.
Otherwise, returns true
.
§Examples
use typed_path::{Path, PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut p = PathBuf::<UnixEncoding>::from("/spirited/away.rs");
p.pop();
assert_eq!(Path::new("/spirited"), p);
p.pop();
assert_eq!(Path::new("/"), p);
sourcepub fn set_file_name<S: AsRef<[u8]>>(&mut self, file_name: S)
pub fn set_file_name<S: AsRef<[u8]>>(&mut self, file_name: S)
Updates self.file_name
to file_name
.
If self.file_name
was None
, this is equivalent to pushing
file_name
.
Otherwise it is equivalent to calling pop
and then pushing
file_name
. The new path will be a sibling of the original path.
(That is, it will have the same parent.)
§Examples
use typed_path::{PathBuf, UnixEncoding};
// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut buf = PathBuf::<UnixEncoding>::from("/");
assert!(buf.file_name() == None);
buf.set_file_name("bar");
assert!(buf == PathBuf::from("/bar"));
assert!(buf.file_name().is_some());
buf.set_file_name("baz.txt");
assert!(buf == PathBuf::from("/baz.txt"));
sourcepub fn set_extension<S: AsRef<[u8]>>(&mut self, extension: S) -> bool
pub fn set_extension<S: AsRef<[u8]>>(&mut self, extension: S) -> bool
Updates self.extension
to extension
.
Returns false
and does nothing if self.file_name
is None
,
returns true
and updates the extension otherwise.
If self.extension
is None
, the extension is added; otherwise
it is replaced.
§Examples
use typed_path::{Path, PathBuf, UnixEncoding};
let mut p = PathBuf::<UnixEncoding>::from("/feel/the");
p.set_extension("force");
assert_eq!(Path::new("/feel/the.force"), p.as_path());
p.set_extension("dark_side");
assert_eq!(Path::new("/feel/the.dark_side"), p.as_path());
sourcepub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>
pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>
Invokes try_reserve
on the underlying instance of Vec
.
sourcepub fn reserve_exact(&mut self, additional: usize)
pub fn reserve_exact(&mut self, additional: usize)
Invokes reserve_exact
on the underlying instance of Vec
.
sourcepub fn try_reserve_exact(
&mut self,
additional: usize
) -> Result<(), TryReserveError>
pub fn try_reserve_exact( &mut self, additional: usize ) -> Result<(), TryReserveError>
Invokes try_reserve_exact
on the underlying instance of Vec
.
sourcepub fn shrink_to_fit(&mut self)
pub fn shrink_to_fit(&mut self)
Invokes shrink_to_fit
on the underlying instance of Vec
.
Methods from Deref<Target = Path<T>>§
sourcepub fn as_bytes(&self) -> &[u8] ⓘ
pub fn as_bytes(&self) -> &[u8] ⓘ
Yields the underlying [[u8]
] slice.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let bytes = Path::<UnixEncoding>::new("foo.txt").as_bytes();
assert_eq!(bytes, b"foo.txt");
sourcepub fn to_str(&self) -> Option<&str>
pub fn to_str(&self) -> Option<&str>
Yields a &str
slice if the Path
is valid unicode.
This conversion may entail doing a check for UTF-8 validity. Note that validation is performed because non-UTF-8 strings are perfectly valid for some OS.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("foo.txt");
assert_eq!(path.to_str(), Some("foo.txt"));
sourcepub fn to_string_lossy(&self) -> Cow<'_, str>
pub fn to_string_lossy(&self) -> Cow<'_, str>
Converts a Path
to a Cow<str>
.
Any non-Unicode sequences are replaced with
U+FFFD REPLACEMENT CHARACTER
.
§Examples
Calling to_string_lossy
on a Path
with valid unicode:
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("foo.txt");
assert_eq!(path.to_string_lossy(), "foo.txt");
Had path
contained invalid unicode, the to_string_lossy
call might
have returned "fo�.txt"
.
sourcepub fn to_path_buf(&self) -> PathBuf<T>
pub fn to_path_buf(&self) -> PathBuf<T>
sourcepub fn is_absolute(&self) -> bool
pub fn is_absolute(&self) -> bool
Returns true
if the Path
is absolute, i.e., if it is independent of
the current directory.
-
On Unix (
UnixPath
]), a path is absolute if it starts with the root, sois_absolute
andhas_root
are equivalent. -
On Windows (
WindowsPath
), a path is absolute if it has a prefix and starts with the root:c:\windows
is absolute, whilec:temp
and\temp
are not.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert!(!Path::<UnixEncoding>::new("foo.txt").is_absolute());
sourcepub fn is_relative(&self) -> bool
pub fn is_relative(&self) -> bool
Returns true
if the Path
is relative, i.e., not absolute.
See is_absolute
’s documentation for more details.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert!(Path::<UnixEncoding>::new("foo.txt").is_relative());
sourcepub fn is_valid(&self) -> bool
pub fn is_valid(&self) -> bool
Returns true
if the path is valid, meaning that all of its components are valid.
See Component::is_valid
’s documentation for more details.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert!(Path::<UnixEncoding>::new("foo.txt").is_valid());
assert!(!Path::<UnixEncoding>::new("foo\0.txt").is_valid());
sourcepub fn has_root(&self) -> bool
pub fn has_root(&self) -> bool
Returns true
if the Path
has a root.
-
On Unix (
UnixPath
), a path has a root if it begins with/
. -
On Windows (
WindowsPath
), a path has a root if it:- has no prefix and begins with a separator, e.g.,
\windows
- has a prefix followed by a separator, e.g.,
c:\windows
but notc:windows
- has any non-disk prefix, e.g.,
\\server\share
- has no prefix and begins with a separator, e.g.,
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert!(Path::<UnixEncoding>::new("/etc/passwd").has_root());
sourcepub fn parent(&self) -> Option<&Self>
pub fn parent(&self) -> Option<&Self>
Returns the Path
without its final component, if there is one.
Returns None
if the path terminates in a root or prefix.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("/foo/bar");
let parent = path.parent().unwrap();
assert_eq!(parent, Path::new("/foo"));
let grand_parent = parent.parent().unwrap();
assert_eq!(grand_parent, Path::new("/"));
assert_eq!(grand_parent.parent(), None);
sourcepub fn ancestors(&self) -> Ancestors<'_, T> ⓘ
pub fn ancestors(&self) -> Ancestors<'_, T> ⓘ
Produces an iterator over Path
and its ancestors.
The iterator will yield the Path
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 typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let mut ancestors = Path::<UnixEncoding>::new("/foo/bar").ancestors();
assert_eq!(ancestors.next(), Some(Path::new("/foo/bar")));
assert_eq!(ancestors.next(), Some(Path::new("/foo")));
assert_eq!(ancestors.next(), Some(Path::new("/")));
assert_eq!(ancestors.next(), None);
// NOTE: A path cannot be created on its own without a defined encoding
let mut ancestors = Path::<UnixEncoding>::new("../foo/bar").ancestors();
assert_eq!(ancestors.next(), Some(Path::new("../foo/bar")));
assert_eq!(ancestors.next(), Some(Path::new("../foo")));
assert_eq!(ancestors.next(), Some(Path::new("..")));
assert_eq!(ancestors.next(), Some(Path::new("")));
assert_eq!(ancestors.next(), None);
sourcepub fn file_name(&self) -> Option<&[u8]>
pub fn file_name(&self) -> Option<&[u8]>
Returns the final component of the Path
, 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 typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert_eq!(Some(b"bin".as_slice()), Path::<UnixEncoding>::new("/usr/bin/").file_name());
assert_eq!(Some(b"foo.txt".as_slice()), Path::<UnixEncoding>::new("tmp/foo.txt").file_name());
assert_eq!(Some(b"foo.txt".as_slice()), Path::<UnixEncoding>::new("foo.txt/.").file_name());
assert_eq!(Some(b"foo.txt".as_slice()), Path::<UnixEncoding>::new("foo.txt/.//").file_name());
assert_eq!(None, Path::<UnixEncoding>::new("foo.txt/..").file_name());
assert_eq!(None, Path::<UnixEncoding>::new("/").file_name());
sourcepub fn strip_prefix<P>(&self, base: P) -> Result<&Path<T>, StripPrefixError>
pub fn strip_prefix<P>(&self, base: P) -> Result<&Path<T>, 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 typed_path::{Path, PathBuf, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("/test/haha/foo.txt");
assert_eq!(path.strip_prefix("/"), Ok(Path::new("test/haha/foo.txt")));
assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt")));
assert_eq!(path.strip_prefix("/test/"), Ok(Path::new("haha/foo.txt")));
assert_eq!(path.strip_prefix("/test/haha/foo.txt"), Ok(Path::new("")));
assert_eq!(path.strip_prefix("/test/haha/foo.txt/"), Ok(Path::new("")));
assert!(path.strip_prefix("test").is_err());
assert!(path.strip_prefix("/haha").is_err());
let prefix = PathBuf::<UnixEncoding>::from("/test/");
assert_eq!(path.strip_prefix(prefix), Ok(Path::new("haha/foo.txt")));
sourcepub fn starts_with<P>(&self, base: P) -> bool
pub fn starts_with<P>(&self, base: P) -> bool
Determines whether base
is a prefix of self
.
Only considers whole path components to match.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::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!(!Path::<UnixEncoding>::new("/etc/foo.rs").starts_with("/etc/foo"));
sourcepub fn ends_with<P>(&self, child: P) -> bool
pub fn ends_with<P>(&self, child: P) -> bool
Determines whether child
is a suffix of self
.
Only considers whole path components to match.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::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
sourcepub fn file_stem(&self) -> Option<&[u8]>
pub fn file_stem(&self) -> Option<&[u8]>
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 typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert_eq!(b"foo", Path::<UnixEncoding>::new("foo.rs").file_stem().unwrap());
assert_eq!(b"foo.tar", Path::<UnixEncoding>::new("foo.tar.gz").file_stem().unwrap());
sourcepub fn extension(&self) -> Option<&[u8]>
pub fn extension(&self) -> Option<&[u8]>
Extracts the extension of self.file_name
, 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 typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert_eq!(b"rs", Path::<UnixEncoding>::new("foo.rs").extension().unwrap());
assert_eq!(b"gz", Path::<UnixEncoding>::new("foo.tar.gz").extension().unwrap());
sourcepub fn normalize(&self) -> PathBuf<T>
pub fn normalize(&self) -> PathBuf<T>
Returns an owned PathBuf
by resolving ..
and .
segments.
When multiple, sequential path segment separation characters are found (e.g. /
for Unix
and either \
or /
on Windows), they are replaced by a single instance of the
platform-specific path segment separator (/
on Unix and \
on Windows).
§Examples
use typed_path::{Path, PathBuf, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert_eq!(
Path::<UnixEncoding>::new("foo/bar//baz/./asdf/quux/..").normalize(),
PathBuf::from("foo/bar/baz/asdf"),
);
When starting with a root directory, any ..
segment whose parent is the root directory
will be filtered out:
use typed_path::{Path, PathBuf, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert_eq!(
Path::<UnixEncoding>::new("/../foo").normalize(),
PathBuf::from("/foo"),
);
If any ..
is left unresolved as the path is relative and no parent is found, it is
discarded:
use typed_path::{Path, PathBuf, UnixEncoding, WindowsEncoding};
assert_eq!(
Path::<UnixEncoding>::new("../foo/..").normalize(),
PathBuf::from(""),
);
// Windows prefixes also count this way, but the prefix remains
assert_eq!(
Path::<WindowsEncoding>::new(r"C:..\foo\..").normalize(),
PathBuf::from(r"C:"),
);
sourcepub fn absolutize(&self) -> Result<PathBuf<T>>
pub fn absolutize(&self) -> Result<PathBuf<T>>
Converts a path to an absolute form by normalizing
the path, returning a
PathBuf
.
In the case that the path is relative, the current working directory is prepended prior to normalizing.
§Examples
use typed_path::{utils, Path, UnixEncoding};
// With an absolute path, it is just normalized
let path = Path::<UnixEncoding>::new("/a/b/../c/./d");
assert_eq!(path.absolutize().unwrap(), Path::new("/a/c/d"));
// With a relative path, it is first joined with the current working directory
// and then normalized
let cwd = utils::current_dir().unwrap().with_encoding::<UnixEncoding>();
let path = cwd.join(Path::new("a/b/../c/./d"));
assert_eq!(path.absolutize().unwrap(), cwd.join(Path::new("a/c/d")));
sourcepub fn join<P: AsRef<Path<T>>>(&self, path: P) -> PathBuf<T>
pub fn join<P: AsRef<Path<T>>>(&self, path: P) -> PathBuf<T>
Creates an owned PathBuf
with path
adjoined to self
.
See PathBuf::push
for more details on what it means to adjoin a path.
§Examples
use typed_path::{Path, PathBuf, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
assert_eq!(
Path::<UnixEncoding>::new("/etc").join("passwd"),
PathBuf::from("/etc/passwd"),
);
sourcepub fn join_checked<P: AsRef<Path<T>>>(
&self,
path: P
) -> Result<PathBuf<T>, CheckedPathError>
pub fn join_checked<P: AsRef<Path<T>>>( &self, path: P ) -> Result<PathBuf<T>, CheckedPathError>
Creates an owned PathBuf
with path
adjoined to self
, checking the path
to ensure
it is safe to join. When dealing with user-provided paths, this is the preferred method.
See PathBuf::push_checked
for more details on what it means to adjoin a path safely.
§Examples
use typed_path::{CheckedPathError, Path, PathBuf, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("/etc");
// A valid path can be joined onto the existing one
assert_eq!(path.join_checked("passwd"), Ok(PathBuf::from("/etc/passwd")));
// An invalid path will result in an error
assert_eq!(path.join_checked("/sneaky/replacement"), Err(CheckedPathError::UnexpectedRoot));
sourcepub fn with_file_name<S: AsRef<[u8]>>(&self, file_name: S) -> PathBuf<T>
pub fn with_file_name<S: AsRef<[u8]>>(&self, file_name: S) -> PathBuf<T>
Creates an owned PathBuf
like self
but with the given file name.
See PathBuf::set_file_name
for more details.
§Examples
use typed_path::{Path, PathBuf, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("/tmp/foo.txt");
assert_eq!(path.with_file_name("bar.txt"), PathBuf::from("/tmp/bar.txt"));
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("/tmp");
assert_eq!(path.with_file_name("var"), PathBuf::from("/var"));
sourcepub fn with_extension<S: AsRef<[u8]>>(&self, extension: S) -> PathBuf<T>
pub fn with_extension<S: AsRef<[u8]>>(&self, extension: S) -> PathBuf<T>
Creates an owned PathBuf
like self
but with the given extension.
See PathBuf::set_extension
for more details.
§Examples
use typed_path::{Path, PathBuf, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("foo.rs");
assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt"));
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("foo.tar.gz");
assert_eq!(path.with_extension(""), PathBuf::from("foo.tar"));
assert_eq!(path.with_extension("xz"), PathBuf::from("foo.tar.xz"));
assert_eq!(path.with_extension("").with_extension("txt"), PathBuf::from("foo.txt"));
sourcepub fn components(&self) -> <T as Encoding<'_>>::Components
pub fn components(&self) -> <T as Encoding<'_>>::Components
Produces an iterator over the Component
s of the path.
When parsing the path, there is a small amount of normalization:
-
Repeated separators are ignored, so
a/b
anda//b
both havea
andb
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/.
anda/b
all havea
andb
as components, but./a/b
starts with an additionalCurDir
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 typed_path::{Path, UnixComponent, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let mut components = Path::<UnixEncoding>::new("/tmp/foo.txt").components();
assert_eq!(components.next(), Some(UnixComponent::RootDir));
assert_eq!(components.next(), Some(UnixComponent::Normal(b"tmp")));
assert_eq!(components.next(), Some(UnixComponent::Normal(b"foo.txt")));
assert_eq!(components.next(), None)
Examples found in repository?
More examples
sourcepub fn iter(&self) -> Iter<'_, T> ⓘ
pub fn iter(&self) -> Iter<'_, T> ⓘ
Produces an iterator over the path’s components viewed as [[u8]
] slices.
For more information about the particulars of how the path is separated
into components, see components
.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let mut it = Path::<UnixEncoding>::new("/tmp/foo.txt").iter();
assert_eq!(it.next(), Some(typed_path::constants::unix::SEPARATOR_STR.as_bytes()));
assert_eq!(it.next(), Some(b"tmp".as_slice()));
assert_eq!(it.next(), Some(b"foo.txt".as_slice()));
assert_eq!(it.next(), None)
sourcepub fn display(&self) -> Display<'_, T>
pub fn display(&self) -> Display<'_, T>
Returns an object that implements Display
for safely printing paths
that may contain non-Unicode data. This may perform lossy conversion,
depending on the platform. If you would like an implementation which
escapes the path please use Debug
instead.
§Examples
use typed_path::{Path, UnixEncoding};
// NOTE: A path cannot be created on its own without a defined encoding
let path = Path::<UnixEncoding>::new("/tmp/foo.rs");
println!("{}", path.display());
sourcepub fn with_encoding<U>(&self) -> PathBuf<U>where
U: for<'enc> Encoding<'enc>,
pub fn with_encoding<U>(&self) -> PathBuf<U>where
U: for<'enc> Encoding<'enc>,
Creates an owned PathBuf
like self
but with a different encoding.
§Note
As part of the process of converting between encodings, the path will need to be rebuilt.
This involves pushing
each component, which may result in differences in the resulting
path such as resolving .
and ..
early or other unexpected side effects.
§Examples
use typed_path::{Path, UnixEncoding, WindowsEncoding};
// Convert from Unix to Windows
let unix_path = Path::<UnixEncoding>::new("/tmp/foo.txt");
let windows_path = unix_path.with_encoding::<WindowsEncoding>();
assert_eq!(windows_path, Path::<WindowsEncoding>::new(r"\tmp\foo.txt"));
// Converting from Windows to Unix will drop any prefix
let windows_path = Path::<WindowsEncoding>::new(r"C:\tmp\foo.txt");
let unix_path = windows_path.with_encoding::<UnixEncoding>();
assert_eq!(unix_path, Path::<UnixEncoding>::new(r"/tmp/foo.txt"));
// Converting to itself should retain everything
let path = Path::<WindowsEncoding>::new(r"C:\tmp\foo.txt");
assert_eq!(
path.with_encoding::<WindowsEncoding>(),
Path::<WindowsEncoding>::new(r"C:\tmp\foo.txt"),
);
sourcepub fn with_encoding_checked<U>(&self) -> Result<PathBuf<U>, CheckedPathError>where
U: for<'enc> Encoding<'enc>,
pub fn with_encoding_checked<U>(&self) -> Result<PathBuf<U>, CheckedPathError>where
U: for<'enc> Encoding<'enc>,
Like with_encoding
, creates an owned PathBuf
like self
but with a different
encoding. Additionally, checks to ensure that the produced path will be valid.
§Note
As part of the process of converting between encodings, the path will need to be rebuilt.
This involves pushing and checking
each component, which may result in differences in
the resulting path such as resolving .
and ..
early or other unexpected side effects.
§Examples
use typed_path::{CheckedPathError, Path, UnixEncoding, WindowsEncoding};
// Convert from Unix to Windows
let unix_path = Path::<UnixEncoding>::new("/tmp/foo.txt");
let windows_path = unix_path.with_encoding_checked::<WindowsEncoding>().unwrap();
assert_eq!(windows_path, Path::<WindowsEncoding>::new(r"\tmp\foo.txt"));
// Converting from Windows to Unix will drop any prefix
let windows_path = Path::<WindowsEncoding>::new(r"C:\tmp\foo.txt");
let unix_path = windows_path.with_encoding_checked::<UnixEncoding>().unwrap();
assert_eq!(unix_path, Path::<UnixEncoding>::new(r"/tmp/foo.txt"));
// Converting from Unix to Windows with invalid filename characters like `:` should fail
let unix_path = Path::<UnixEncoding>::new("/|invalid|/foo.txt");
assert_eq!(
unix_path.with_encoding_checked::<WindowsEncoding>(),
Err(CheckedPathError::InvalidFilename),
);
// Converting from Unix to Windows with unexpected prefix embedded in path should fail
let unix_path = Path::<UnixEncoding>::new("/path/c:/foo.txt");
assert_eq!(
unix_path.with_encoding_checked::<WindowsEncoding>(),
Err(CheckedPathError::UnexpectedPrefix),
);
sourcepub fn has_unix_encoding(&self) -> bool
pub fn has_unix_encoding(&self) -> bool
Returns true if the encoding for the path is for Unix.
§Examples
use typed_path::{UnixPath, WindowsPath};
assert!(UnixPath::new("/some/path").has_unix_encoding());
assert!(!WindowsPath::new(r"\some\path").has_unix_encoding());
sourcepub fn with_unix_encoding(&self) -> PathBuf<UnixEncoding>
pub fn with_unix_encoding(&self) -> PathBuf<UnixEncoding>
Creates an owned PathBuf
like self
but using UnixEncoding
.
See Path::with_encoding
for more information.
sourcepub fn with_unix_encoding_checked(
&self
) -> Result<PathBuf<UnixEncoding>, CheckedPathError>
pub fn with_unix_encoding_checked( &self ) -> Result<PathBuf<UnixEncoding>, CheckedPathError>
Creates an owned PathBuf
like self
but using UnixEncoding
, ensuring it is a valid
Unix path.
See Path::with_encoding_checked
for more information.
pub fn to_typed_path(&self) -> TypedPath<'_>
pub fn to_typed_path_buf(&self) -> TypedPathBuf
sourcepub fn has_windows_encoding(&self) -> bool
pub fn has_windows_encoding(&self) -> bool
Returns true if the encoding for the path is for Windows.
§Examples
use typed_path::{UnixPath, WindowsPath};
assert!(!UnixPath::new("/some/path").has_windows_encoding());
assert!(WindowsPath::new(r"\some\path").has_windows_encoding());
sourcepub fn with_windows_encoding(&self) -> PathBuf<WindowsEncoding>
pub fn with_windows_encoding(&self) -> PathBuf<WindowsEncoding>
Creates an owned PathBuf
like self
but using WindowsEncoding
.
See Path::with_encoding
for more information.
sourcepub fn with_windows_encoding_checked(
&self
) -> Result<PathBuf<WindowsEncoding>, CheckedPathError>
pub fn with_windows_encoding_checked( &self ) -> Result<PathBuf<WindowsEncoding>, CheckedPathError>
Creates an owned PathBuf
like self
but using WindowsEncoding
, ensuring it is a
valid Windows path.
See Path::with_encoding_checked
for more information.
pub fn to_typed_path(&self) -> TypedPath<'_>
pub fn to_typed_path_buf(&self) -> TypedPathBuf
Trait Implementations§
source§impl<T, P> Extend<P> for PathBuf<T>
impl<T, P> Extend<P> for PathBuf<T>
source§fn extend<I: IntoIterator<Item = P>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = P>>(&mut self, iter: I)
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl<T, P> FromIterator<P> for PathBuf<T>
impl<T, P> FromIterator<P> for PathBuf<T>
source§fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> Self
fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> Self
source§impl<'a, T> IntoIterator for &'a PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> IntoIterator for &'a PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<T> Ord for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> Ord for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<&'a [u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<&'a [u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<&'a Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<&'a Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<T> PartialEq<[u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialEq<[u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<Cow<'a, [u8]>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<Cow<'a, [u8]>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<Cow<'a, Path<T>>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<Cow<'a, Path<T>>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<T> PartialEq<Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialEq<Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<PathBuf<T>> for &'a [u8]where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<PathBuf<T>> for &'a [u8]where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<PathBuf<T>> for &'a Path<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<PathBuf<T>> for &'a Path<T>where
T: for<'enc> Encoding<'enc>,
source§impl<T> PartialEq<PathBuf<T>> for [u8]where
T: for<'enc> Encoding<'enc>,
impl<T> PartialEq<PathBuf<T>> for [u8]where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<PathBuf<T>> for Cow<'a, [u8]>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<PathBuf<T>> for Cow<'a, [u8]>where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialEq<PathBuf<T>> for Cow<'a, Path<T>>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialEq<PathBuf<T>> for Cow<'a, Path<T>>where
T: for<'enc> Encoding<'enc>,
source§impl<T> PartialEq<PathBuf<T>> for Path<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialEq<PathBuf<T>> for Path<T>where
T: for<'enc> Encoding<'enc>,
source§impl<T> PartialEq<PathBuf<T>> for Vec<u8>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialEq<PathBuf<T>> for Vec<u8>where
T: for<'enc> Encoding<'enc>,
source§impl<T> PartialEq<Vec<u8>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialEq<Vec<u8>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<T> PartialEq for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialEq for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§impl<'a, T> PartialOrd<&'a [u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<&'a [u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a, T> PartialOrd<&'a Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<&'a Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd<[u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialOrd<[u8]> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a, T> PartialOrd<Cow<'a, [u8]>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<Cow<'a, [u8]>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a, T> PartialOrd<Cow<'a, Path<T>>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<Cow<'a, Path<T>>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd<Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialOrd<Path<T>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a, T> PartialOrd<PathBuf<T>> for &'a [u8]where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<PathBuf<T>> for &'a [u8]where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a, T> PartialOrd<PathBuf<T>> for &'a Path<T>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<PathBuf<T>> for &'a Path<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd<PathBuf<T>> for [u8]where
T: for<'enc> Encoding<'enc>,
impl<T> PartialOrd<PathBuf<T>> for [u8]where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a, T> PartialOrd<PathBuf<T>> for Cow<'a, [u8]>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<PathBuf<T>> for Cow<'a, [u8]>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a, T> PartialOrd<PathBuf<T>> for Cow<'a, Path<T>>where
T: for<'enc> Encoding<'enc>,
impl<'a, T> PartialOrd<PathBuf<T>> for Cow<'a, Path<T>>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd<PathBuf<T>> for Path<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialOrd<PathBuf<T>> for Path<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd<PathBuf<T>> for Vec<u8>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialOrd<PathBuf<T>> for Vec<u8>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd<Vec<u8>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialOrd<Vec<u8>> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> PartialOrd for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> TryFrom<PathBuf<T>> for PathBufwhere
T: for<'enc> Encoding<'enc>,
impl<T> TryFrom<PathBuf<T>> for PathBufwhere
T: for<'enc> Encoding<'enc>,
source§fn try_from(path: PathBuf<T>) -> Result<Self, Self::Error>
fn try_from(path: PathBuf<T>) -> Result<Self, Self::Error>
Attempts to convert a PathBuf
into a std::path::PathBuf
, returning a result
containing the new path when successful or the original path when failed
§Examples
use std::convert::TryFrom;
use std::path::PathBuf;
use typed_path::UnixPathBuf;
let unix_path_buf = UnixPathBuf::from("/path/to/file.txt");
let std_path_buf: PathBuf = TryFrom::try_from(unix_path_buf).unwrap();
source§impl<T> TryFrom<PathBuf> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
impl<T> TryFrom<PathBuf> for PathBuf<T>where
T: for<'enc> Encoding<'enc>,
source§fn try_from(path: StdPathBuf) -> Result<Self, Self::Error>
fn try_from(path: StdPathBuf) -> Result<Self, Self::Error>
Attempts to convert a std::path::PathBuf
into a PathBuf
, returning a result
containing the new path when successful or the original path when failed
§Examples
use std::convert::TryFrom;
use std::path::PathBuf;
use typed_path::UnixPathBuf;
let std_path_buf = PathBuf::from("/path/to/file.txt");
let unix_path_buf: UnixPathBuf = TryFrom::try_from(std_path_buf).unwrap();