Struct relative_path::RelativePathBuf

pub struct RelativePathBuf { /* fields omitted */ }

An owned, mutable relative path.

This type provides methods to manipulate relative path objects.

Methods

impl RelativePathBuf

fn new() -> RelativePathBuf

Create a new relative path buffer.

fn push<P: AsRef<RelativePath>>(&mut self, path: P)

Extends self with path.

If path is absolute, it replaces the current path.

Examples

use relative_path::{RelativePathBuf, RelativePath};

let mut path = RelativePathBuf::new();
path.push("foo");
path.push("bar");

assert_eq!("foo/bar", path);

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 relative_path::RelativePathBuf;

let mut buf = RelativePathBuf::from("");
assert!(buf.file_name() == None);
buf.set_file_name("bar");
assert_eq!(RelativePathBuf::from("bar"), buf);

assert!(buf.file_name().is_some());
buf.set_file_name("baz.txt");
assert_eq!(RelativePathBuf::from("baz.txt"), buf);

buf.push("bar");
assert!(buf.file_name().is_some());
buf.set_file_name("bar.txt");
assert_eq!(RelativePathBuf::from("baz.txt/bar.txt"), buf);

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 relative_path::{RelativePath, RelativePathBuf};

let mut p = RelativePathBuf::from("feel/the");

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

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

assert!(p.pop());
p.set_extension("nothing");
assert_eq!(RelativePath::new("feel.nothing"), p);

fn pop(&mut self) -> bool

Truncates self to self.parent.

Returns false and does nothing if self.file_name is None. Otherwise, returns true.

Examples

use relative_path::{RelativePath, RelativePathBuf};

let mut p = RelativePathBuf::from("test/test.rs");

assert_eq!(true, p.pop());
assert_eq!(RelativePath::new("test"), p);
assert_eq!(false, p.pop());
assert_eq!(RelativePath::new("test"), p);

fn as_relative_path(&self) -> &RelativePath

Coerce to a RelativePath slice.

Methods from Deref<Target = RelativePath>

fn as_str(&self) -> &str

Yields the underlying str slice.

Examples

use relative_path::RelativePath;

assert_eq!(RelativePath::new("foo.txt").as_str(), "foo.txt");

fn display(&self) -> Display

Returns an object that implements [Display].

Examples

use relative_path::RelativePath;

let path = RelativePath::new("tmp/foo.rs");

println!("{}", path.display());

fn join<P: AsRef<RelativePath>>(&self, path: P) -> RelativePathBuf

Creates an owned RelativePathBuf with path adjoined to self.

Examples

use relative_path::RelativePath;

let path = RelativePath::new("foo/bar");
assert_eq!("foo/bar/baz", path.join("baz"));

fn components(&self) -> Components

Iterate over all components in this relative path.

Examples

use relative_path::{Component, RelativePath};

let path = RelativePath::new("foo/bar/baz");
let mut it = path.components();

assert_eq!(Some(Component::Normal("foo")), it.next());
assert_eq!(Some(Component::Normal("bar")), it.next());
assert_eq!(Some(Component::Normal("baz")), it.next());
assert_eq!(None, it.next());

fn iter(&self) -> Iter

Produces an iterator over the path's components viewed as str slices.

For more information about the particulars of how the path is separated into components, see components.

Examples

use relative_path::RelativePath;

let mut it = RelativePath::new("/tmp/foo.txt").iter();
assert_eq!(it.next(), Some("tmp"));
assert_eq!(it.next(), Some("foo.txt"));
assert_eq!(it.next(), None)

fn to_relative_path_buf(&self) -> RelativePathBuf

Convert to an owned RelativePathBuf.

fn to_path<P: AsRef<Path>>(&self, relative_to: P) -> PathBuf

Build an owned PathBuf relative to path for the current relative path.

Examples

use relative_path::RelativePath;
use std::path::Path;

let path = RelativePath::new("foo/bar").to_path(Path::new("."));
assert_eq!(Path::new("./foo/bar"), path);

fn parent(&self) -> Option<&RelativePath>

Returns a relative path, without its final component if there is one.

Examples

use relative_path::RelativePath;

assert_eq!(Some(RelativePath::new("foo")), RelativePath::new("foo/bar").parent());
assert_eq!(None, RelativePath::new("foo").parent());
assert_eq!(None, RelativePath::new("").parent());

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

Returns the final component of the RelativePath, 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 relative_path::RelativePath;

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

fn strip_prefix<'a, P: ?Sized>(
    &'a self,
    base: &'a P
) -> Result<&'a RelativePath, StripPrefixError> where
    P: AsRef<RelativePath>, 

Returns a relative 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 relative_path::RelativePath;

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

assert_eq!(path.strip_prefix("test"), Ok(RelativePath::new("haha/foo.txt")));
assert_eq!(path.strip_prefix("test").is_ok(), true);
assert_eq!(path.strip_prefix("haha").is_ok(), false);

fn starts_with<P: AsRef<RelativePath>>(&self, base: P) -> bool

Determines whether base is a prefix of self.

Only considers whole path components to match.

Examples

use relative_path::RelativePath;

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

assert!(path.starts_with("etc"));

assert!(!path.starts_with("e"));

fn ends_with<P: AsRef<RelativePath>>(&self, child: P) -> bool

Determines whether child is a suffix of self.

Only considers whole path components to match.

Examples

use relative_path::RelativePath;

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

assert!(path.ends_with("passwd"));

fn with_file_name<S: AsRef<str>>(&self, file_name: S) -> RelativePathBuf

Creates an owned RelativePathBuf like self but with the given file name.

See RelativePathBuf::set_file_name for more details.

Examples

use relative_path::{RelativePath, RelativePathBuf};

let path = RelativePath::new("tmp/foo.txt");
assert_eq!(path.with_file_name("bar.txt"), RelativePathBuf::from("tmp/bar.txt"));

let path = RelativePath::new("tmp");
assert_eq!(path.with_file_name("var"), RelativePathBuf::from("var"));

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 relative_path::RelativePath;

let path = RelativePath::new("foo.rs");

assert_eq!("foo", path.file_stem().unwrap());

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

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 relative_path::RelativePath;

assert_eq!(Some("rs"), RelativePath::new("foo.rs").extension());
assert_eq!(None, RelativePath::new(".rs").extension());
assert_eq!(Some("rs"), RelativePath::new("foo.rs/.").extension());

fn with_extension<S: AsRef<str>>(&self, extension: S) -> RelativePathBuf

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

See RelativePathBuf::set_extension for more details.

Examples

use relative_path::{RelativePath, RelativePathBuf};

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

fn join_normalized<P: AsRef<RelativePath>>(&self, path: P) -> RelativePathBuf

Build an owned RelativePathBuf, joined with the given path and normalized.

Examples

use relative_path::RelativePath;

assert_eq!(
    RelativePath::new("foo/baz.txt"),
    RelativePath::new("foo/bar").join_normalized("../baz.txt").as_relative_path()
);

assert_eq!(
    RelativePath::new("../foo/baz.txt"),
    RelativePath::new("../foo/bar").join_normalized("../baz.txt").as_relative_path()
);

fn normalize(&self) -> RelativePathBuf

Return an owned RelativePathBuf, with all non-normal components moved to the beginning of the path.

This permits for a normalized representation of different relative components.

Normalization is a destructive operation if the path references an actual filesystem path. An example of this is symlinks under unix, a path like foo/../bar might reference a different location other than ./bar.

Normalization is a logical operation that is only valid if the relative path is part of some context which doesn't have semantics that causes it to break, like symbolic links.

Examples

use relative_path::RelativePath;

assert_eq!(
    RelativePath::new("../foo/baz.txt"),
    RelativePath::new("../foo/./bar/../baz.txt").normalize().as_relative_path()
);

Trait Implementations

impl Clone for RelativePathBuf

fn clone(&self) -> RelativePathBuf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for RelativePathBuf

fn default() -> Self

Returns the "default value" for a type.

impl Debug for RelativePathBuf

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.

impl AsRef<RelativePath> for RelativePathBuf

fn as_ref(&self) -> &RelativePath

Performs the conversion.

impl Borrow<RelativePath> for RelativePathBuf

fn borrow(&self) -> &RelativePath

Immutably borrows from an owned value.

impl<'a, T: ?Sized + AsRef<str>> From<&'a T> for RelativePathBuf

fn from(path: &'a T) -> RelativePathBuf

Performs the conversion.

impl From<String> for RelativePathBuf

fn from(path: String) -> RelativePathBuf

Performs the conversion.

impl Deref for RelativePathBuf

type Target = RelativePath

The resulting type after dereferencing.

fn deref(&self) -> &RelativePath

Dereferences the value.

impl PartialEq for RelativePathBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl Eq for RelativePathBuf

impl PartialOrd for RelativePathBuf

fn partial_cmp(&self, other: &RelativePathBuf) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Ord for RelativePathBuf

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

impl Hash for RelativePathBuf

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, 

Feeds a slice of this type into the given [Hasher].

impl AsRef<str> for RelativePathBuf

fn as_ref(&self) -> &str

Performs the conversion.

impl<'a, 'b> PartialEq<RelativePath> for RelativePathBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, 'b> PartialOrd<RelativePath> for RelativePathBuf

fn partial_cmp(&self, other: &RelativePath) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialEq<&'a RelativePath> for RelativePathBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, 'b> PartialOrd<&'a RelativePath> for RelativePathBuf

fn partial_cmp(&self, other: &&'a RelativePath) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialEq<Cow<'a, RelativePath>> for RelativePathBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, 'b> PartialOrd<Cow<'a, RelativePath>> for RelativePathBuf

fn partial_cmp(&self, other: &Cow<'a, RelativePath>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialEq<str> for RelativePathBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, 'b> PartialOrd<str> for RelativePathBuf

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialEq<&'a str> for RelativePathBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, 'b> PartialOrd<&'a str> for RelativePathBuf

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialEq<String> for RelativePathBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, 'b> PartialOrd<String> for RelativePathBuf

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.