[−][src]Struct relative_path::RelativePathBuf

pub struct RelativePathBuf { /* fields omitted */ }

An owned, mutable relative path.

This type provides methods to manipulate relative path objects.

Implementations

`impl RelativePathBuf`[src]

`pub fn new() -> RelativePathBuf`[src]

Create a new relative path buffer.

`pub fn from_path<P: AsRef<Path>>( path: P ) -> Result<RelativePathBuf, FromPathError>`[src]

Try to convert a Path to a RelativePathBuf.

Examples

use relative_path::{RelativePath, RelativePathBuf, FromPathErrorKind};
use std::path::Path;
use std::ffi::OsStr;

assert_eq!(
    Ok(RelativePath::new("foo/bar").to_owned()),
    RelativePathBuf::from_path(Path::new("foo/bar"))
);

`pub fn push<P: AsRef<RelativePath>>(&mut self, path: P)`[src]

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

`pub fn set_file_name<S: AsRef<str>>(&mut self, file_name: S)`[src]

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

`pub fn set_extension<S: AsRef<str>>(&mut self, extension: S) -> bool`[src]

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

`pub fn pop(&mut self) -> bool`[src]

Truncates self to self.parent.

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!(true, p.pop());
assert_eq!(RelativePath::new(""), p);
assert_eq!(false, p.pop());
assert_eq!(RelativePath::new(""), p);

`pub fn as_relative_path(&self) -> &RelativePath`[src]

Coerce to a RelativePath slice.

Methods from Deref<Target = RelativePath>

`pub fn as_str(&self) -> &str`[src]

Yields the underlying str slice.

Examples

use relative_path::RelativePath;

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

`pub fn display(&self) -> Display`[src]

👎 Deprecated:

RelativePath implements std::fmt::Display directly

Returns an object that implements Display.

Examples

use relative_path::RelativePath;

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

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

`pub fn join<P: AsRef<RelativePath>>(&self, path: P) -> RelativePathBuf`[src]

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

`pub fn components(&self) -> Components`[src]

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

`pub fn iter(&self) -> Iter`[src]

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)

`pub fn to_relative_path_buf(&self) -> RelativePathBuf`[src]

Convert to an owned RelativePathBuf.

`pub fn to_path<P: AsRef<Path>>(&self, relative_to: P) -> PathBuf`[src]

Build an owned PathBuf relative to relative_to 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);

Encoding an absolute path

Absolute paths are, in contrast to when using [PathBuf::push] ignored and will be added unchanged to the buffer.

This is to preserve the probability of a path conversion failing if the relative path contains platform-specific absolute path components.

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

if cfg!(windows) {
    assert_eq!(
        Path::new("foo\\bar\\baz"),
        RelativePath::new("/bar/baz").to_path("foo")
    );

    assert_eq!(
        Path::new("foo\\c:\\bar\\baz"),
        RelativePath::new("c:\\bar\\baz").to_path("foo")
    );
}

if cfg!(unix) {
    assert_eq!(
        Path::new("foo/bar/baz"),
        RelativePath::new("/bar/baz").to_path("foo")
    );

    assert_eq!(
        Path::new("foo/c:\\bar\\baz"),
        RelativePath::new("c:\\bar\\baz").to_path("foo")
    );
}

`pub fn parent(&self) -> Option<&RelativePath>`[src]

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!(Some(RelativePath::new("")), RelativePath::new("foo").parent());
assert_eq!(None, RelativePath::new("").parent());

`pub fn file_name(&self) -> Option<&str>`[src]

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

`pub fn strip_prefix<P: AsRef<RelativePath>>( &self, base: P ) -> Result<&RelativePath, StripPrefixError>`[src]

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

`pub fn starts_with<P: AsRef<RelativePath>>(&self, base: P) -> bool`[src]

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

`pub fn ends_with<P: AsRef<RelativePath>>(&self, child: P) -> bool`[src]

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

`pub fn with_file_name<S: AsRef<str>>(&self, file_name: S) -> RelativePathBuf`[src]

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

`pub fn file_stem(&self) -> Option<&str>`[src]

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

`pub fn extension(&self) -> Option<&str>`[src]

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

`pub fn with_extension<S: AsRef<str>>(&self, extension: S) -> RelativePathBuf`[src]

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

`pub fn join_normalized<P: AsRef<RelativePath>>( &self, path: P ) -> RelativePathBuf`[src]

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

`pub fn normalize(&self) -> RelativePathBuf`[src]

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

`pub fn relative<P: AsRef<RelativePath>>(&self, path: P) -> RelativePathBuf`[src]

Constructs a relative path from the current path, to path.

Examples

use relative_path::RelativePath;

assert_eq!(
    "../../e/f",
    RelativePath::new("a/b/c/d").relative(RelativePath::new("a/b/e/f"))
);

assert_eq!(
    "../bbb",
    RelativePath::new("a/../aaa").relative(RelativePath::new("b/../bbb"))
);

let p = RelativePath::new("git/relative-path");
let r = RelativePath::new("git");
assert_eq!("relative-path", r.relative(p));
assert_eq!("..", p.relative(r));

let p = RelativePath::new("../../git/relative-path");
let r = RelativePath::new("git");
assert_eq!("../../../git/relative-path", r.relative(p));
assert_eq!("", p.relative(r));

let a = RelativePath::new("foo/bar/bap/foo.h");
let b = RelativePath::new("../arch/foo.h");
assert_eq!("../../../../../arch/foo.h", a.relative(b));
assert_eq!("", b.relative(a));