Type Alias Utf8UnixPathBuf

pub type Utf8UnixPathBuf = Utf8PathBuf<Utf8UnixEncoding>;

Represents a Unix-specific Utf8PathBuf

Aliased Type

pub struct Utf8UnixPathBuf { /* private fields */ }

Implementations

impl<T> Utf8PathBuf<T>

where T: Utf8Encoding,

pub fn new() -> Self

Allocates an empty Utf8PathBuf.

Examples

use typed_path::{Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let path = Utf8PathBuf::<Utf8UnixEncoding>::new();

pub fn with_capacity(capacity: usize) -> Self

Creates a new PathBuf with a given capacity used to create the internal String. See with_capacity defined on String.

Examples

use typed_path::{Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = Utf8PathBuf::<Utf8UnixEncoding>::with_capacity(10);
let capacity = path.capacity();

// This push is done without reallocating
path.push(r"C:\");

assert_eq!(capacity, path.capacity());

pub fn as_path(&self) -> &Utf8Path<T>

Coerces to a Utf8Path slice.

Examples

use typed_path::{Utf8Path, Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let p = Utf8PathBuf::<Utf8UnixEncoding>::from("/test");
assert_eq!(Utf8Path::new("/test"), p.as_path());

pub fn push<P: AsRef<Utf8Path<T>>>(&mut self, path: P)

Extends self with path.

If path is absolute, it replaces the current path.

With Utf8WindowsPathBuf:

• 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.
• if self has a verbatim prefix (e.g. \\?\C:\windows) and path 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::{Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = Utf8PathBuf::<Utf8UnixEncoding>::from("/tmp");
path.push("file.bk");
assert_eq!(path, Utf8PathBuf::from("/tmp/file.bk"));

Pushing an absolute path replaces the existing path:

use typed_path::{Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = Utf8PathBuf::<Utf8UnixEncoding>::from("/tmp");
path.push("/etc");
assert_eq!(path, Utf8PathBuf::from("/etc"));

pub fn push_checked<P: AsRef<Utf8Path<T>>>( &mut self, path: P, ) -> Result<(), CheckedPathError>

Like Utf8PathBuf::push, extends self with path, but also checks to ensure that path abides by a set of rules.

Rules

1. path cannot contain a prefix component.
2. path cannot contain a root component.
3. path cannot contain invalid filename bytes.
4. 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::{Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = Utf8PathBuf::<Utf8UnixEncoding>::from("/tmp");

// Pushing a relative path works like normal
assert!(path.push_checked("file.bk").is_ok());
assert_eq!(path, Utf8PathBuf::from("/tmp/file.bk"));

Pushing a relative path that contains unresolved parent directory references fails with an error:

use typed_path::{CheckedPathError, Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = Utf8PathBuf::<Utf8UnixEncoding>::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, Utf8PathBuf::from("/tmp"));

Pushing an absolute path fails with an error:

use typed_path::{CheckedPathError, Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut path = Utf8PathBuf::<Utf8UnixEncoding>::from("/tmp");

// Pushing an absolute path will fail with an error
assert_eq!(path.push_checked("/etc"), Err(CheckedPathError::UnexpectedRoot));
assert_eq!(path, Utf8PathBuf::from("/tmp"));

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::{Utf8Path, Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut p = Utf8PathBuf::<Utf8UnixEncoding>::from("/spirited/away.rs");

p.pop();
assert_eq!(Utf8Path::new("/spirited"), p);
p.pop();
assert_eq!(Utf8Path::new("/"), p);

pub fn set_file_name<S: AsRef<str>>(&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::{Utf8PathBuf, Utf8UnixEncoding};

// NOTE: A pathbuf cannot be created on its own without a defined encoding
let mut buf = Utf8PathBuf::<Utf8UnixEncoding>::from("/");
assert!(buf.file_name() == None);
buf.set_file_name("bar");
assert!(buf == Utf8PathBuf::from("/bar"));
assert!(buf.file_name().is_some());
buf.set_file_name("baz.txt");
assert!(buf == Utf8PathBuf::from("/baz.txt"));

pub fn set_extension<S: AsRef<str>>(&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::{Utf8Path, Utf8PathBuf, Utf8UnixEncoding};

let mut p = Utf8PathBuf::<Utf8UnixEncoding>::from("/feel/the");

p.set_extension("force");
assert_eq!(Utf8Path::new("/feel/the.force"), p.as_path());

p.set_extension("dark_side");
assert_eq!(Utf8Path::new("/feel/the.dark_side"), p.as_path());

pub fn into_string(self) -> String

Consumes the PathBuf, yielding its internal String storage.

Examples

use typed_path::{Utf8PathBuf, Utf8UnixEncoding};

let p = Utf8PathBuf::<Utf8UnixEncoding>::from("/the/head");
let s = p.into_string();

pub fn into_boxed_path(self) -> Box<Utf8Path<T>>

Converts this Utf8PathBuf into a boxed Utf8Path.

pub fn capacity(&self) -> usize

Invokes capacity on the underlying instance of String.

pub fn clear(&mut self)

Invokes clear on the underlying instance of String.

pub fn reserve(&mut self, additional: usize)

Invokes reserve on the underlying instance of String.

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

Invokes try_reserve on the underlying instance of String.

pub fn reserve_exact(&mut self, additional: usize)

Invokes reserve_exact on the underlying instance of String.

pub fn try_reserve_exact( &mut self, additional: usize, ) -> Result<(), TryReserveError>

Invokes try_reserve_exact on the underlying instance of String.

pub fn shrink_to_fit(&mut self)

Invokes shrink_to_fit on the underlying instance of String.

pub fn shrink_to(&mut self, min_capacity: usize)

Invokes shrink_to on the underlying instance of String.

pub fn from_bytes_path_buf<U>( path_buf: PathBuf<U>, ) -> Result<Self, FromUtf8Error>

where U: Encoding,

Consumes PathBuf and returns a new Utf8PathBuf by checking that the path contains valid UTF-8.

Errors

Returns Err if the path is not UTF-8 with a description as to why the provided component is not UTF-8.

Examples

use typed_path::{PathBuf, Utf8PathBuf, UnixEncoding, Utf8UnixEncoding};

let path_buf = PathBuf::<UnixEncoding>::from(&[0xf0, 0x9f, 0x92, 0x96]);
let utf8_path_buf = Utf8PathBuf::<Utf8UnixEncoding>::from_bytes_path_buf(path_buf).unwrap();
assert_eq!(utf8_path_buf.as_str(), "💖");

pub unsafe fn from_bytes_path_buf_unchecked<U>(path_buf: PathBuf<U>) -> Self

where U: Encoding,

Consumes PathBuf and returns a new Utf8PathBuf by checking that the path contains valid UTF-8.

Errors

Returns Err if the path is not UTF-8 with a description as to why the provided component is not UTF-8.

Safety

The path passed in must be valid UTF-8.

Examples

use typed_path::{PathBuf, Utf8PathBuf, UnixEncoding, Utf8UnixEncoding};

let path_buf = PathBuf::<UnixEncoding>::from(&[0xf0, 0x9f, 0x92, 0x96]);
let utf8_path_buf = unsafe {
    Utf8PathBuf::<Utf8UnixEncoding>::from_bytes_path_buf_unchecked(path_buf)
};
assert_eq!(utf8_path_buf.as_str(), "💖");

pub fn into_bytes_path_buf<U>(self) -> PathBuf<U>

where U: Encoding,

Consumes Utf8PathBuf and returns a new PathBuf

Examples

use typed_path::{PathBuf, Utf8PathBuf, UnixEncoding, Utf8UnixEncoding};

let utf8_path_buf = Utf8PathBuf::<Utf8UnixEncoding>::from("💖");
let path_buf = utf8_path_buf.into_bytes_path_buf::<UnixEncoding>();
assert_eq!(path_buf.as_bytes(), &[0xf0, 0x9f, 0x92, 0x96]);

Trait Implementations

impl TryFrom<Utf8TypedPathBuf> for Utf8UnixPathBuf

type Error = Utf8TypedPathBuf

The type returned in the event of a conversion error.

fn try_from(path: Utf8TypedPathBuf) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> AsRef<[u8]> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn as_ref(&self) -> &[u8]

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

impl<T> AsRef<OsStr> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn as_ref(&self) -> &OsStr

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

impl<T> AsRef<Utf8Path<T>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn as_ref(&self) -> &Utf8Path<T>

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

impl<T> AsRef<str> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn as_ref(&self) -> &str

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

impl<T> Borrow<Utf8Path<T>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn borrow(&self) -> &Utf8Path<T>

Immutably borrows from an owned value.

impl<T> Clone for Utf8PathBuf<T>

where T: Utf8Encoding,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Utf8PathBuf<T>

where T: Utf8Encoding,

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

Formats the value using the given formatter.

impl<T> Default for Utf8PathBuf<T>

where T: Utf8Encoding,

fn default() -> Utf8PathBuf<T>

Returns the “default value” for a type.

impl<T> Deref for Utf8PathBuf<T>

where T: Utf8Encoding,

type Target = Utf8Path<T>

The resulting type after dereferencing.

fn deref(&self) -> &Utf8Path<T>

Dereferences the value.

impl<T> Display for Utf8PathBuf<T>

where T: Utf8Encoding,

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

Formats the value using the given formatter.

impl<T, P> Extend<P> for Utf8PathBuf<T>

where T: Utf8Encoding, P: AsRef<Utf8Path<T>>,

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: A)

🔬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<T, V> From<&V> for Utf8PathBuf<T>

where T: Utf8Encoding, V: ?Sized + AsRef<str>,

fn from(s: &V) -> Self

Converts a borrowed str to a Utf8PathBuf.

Allocates a Utf8PathBuf and copies the data into it.

impl<T> From<Box<Utf8Path<T>>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn from(boxed: Box<Utf8Path<T>>) -> Self

Converts to this type from the input type.

impl<'a, T> From<Cow<'a, Utf8Path<T>>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn from(p: Cow<'a, Utf8Path<T>>) -> Self

Converts a clone-on-write pointer to an owned path.

Converting from a Cow::Owned does not clone or allocate.

impl<T> From<String> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn from(inner: String) -> Self

Converts a String into a Utf8PathBuf

This conversion does not allocate or copy memory.

impl<T, P> FromIterator<P> for Utf8PathBuf<T>

where T: Utf8Encoding, P: AsRef<Utf8Path<T>>,

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

Creates a value from an iterator.

impl<T> FromStr for Utf8PathBuf<T>

where T: Utf8Encoding,

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<T> Hash for Utf8PathBuf<T>

where T: Utf8Encoding,

fn hash<H: Hasher>(&self, h: &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<T> Ord for Utf8PathBuf<T>

where T: Utf8Encoding,

fn cmp(&self, other: &Self) -> 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.

impl<'a, T> PartialEq<&'a Utf8Path<T>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn eq(&self, other: &&'a Utf8Path<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T> PartialEq<&'a str> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn eq(&self, other: &&'a str) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T> PartialEq<Cow<'a, Utf8Path<T>>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn eq(&self, other: &Cow<'a, Utf8Path<T>>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T> PartialEq<Cow<'a, str>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn eq(&self, other: &Cow<'a, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<String> for Utf8PathBuf<T>

where T: Utf8Encoding,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<Utf8Path<T>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn eq(&self, other: &Utf8Path<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<str> for Utf8PathBuf<T>

where T: Utf8Encoding,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq for Utf8PathBuf<T>

where T: Utf8Encoding,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T> PartialOrd<&'a Utf8Path<T>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &&'a Utf8Path<T>) -> 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<'a, T> PartialOrd<&'a str> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &&'a str) -> 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<'a, T> PartialOrd<Cow<'a, Utf8Path<T>>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &Cow<'a, Utf8Path<T>>) -> 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<'a, T> PartialOrd<Cow<'a, str>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &Cow<'a, str>) -> 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<T> PartialOrd<String> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &String) -> 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<T> PartialOrd<Utf8Path<T>> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &Utf8Path<T>) -> 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<T> PartialOrd<str> for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &str) -> 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<T> PartialOrd for Utf8PathBuf<T>

where T: Utf8Encoding,

fn partial_cmp(&self, other: &Self) -> 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<T> Eq for Utf8PathBuf<T>

where T: Utf8Encoding,