This is a library for extending Path
and PathBuf
in order to get an absolute path and remove the containing dots.
The difference between absolutize
and canonicalize
methods is that absolutize
does not care about whether the file exists and what the file really is.
Please read the following examples to know the parsing rules.
There are two methods you can use.
Get an absolute path.
The dots in a path will be parsed even if it is already an absolute path (which means the path starts with a MAIN_SEPARATOR
on Unix-like systems).
```rust extern crate path_absolutize;
use std::path::Path;
use path_absolutize::*;
let p = Path::new("/path/to/123/456");
asserteq!("/path/to/123/456", p.absolutize().unwrap().tostr().unwrap()); ```
```rust extern crate path_absolutize;
use std::path::Path;
use path_absolutize::*;
let p = Path::new("/path/to/./123/../456");
asserteq!("/path/to/456", p.absolutize().unwrap().tostr().unwrap()); ```
If a path starts with a single dot, the dot means your program's current working directory (CWD).
```rust extern crate path_absolutize;
use std::path::Path; use std::env;
use path_absolutize::*;
let p = Path::new("./path/to/123/456");
asserteq!(Path::join(env::currentdir().unwrap().aspath(), Path::new("path/to/123/456")).tostr().unwrap(), p.absolutize().unwrap().to_str().unwrap()); ```
If a path starts with a pair of dots, the dots means the parent of the CWD. If the CWD is root, the parent is still root.
```rust extern crate path_absolutize;
use std::path::Path; use std::env;
use path_absolutize::*;
let p = Path::new("../path/to/123/456");
let cwd = env::current_dir().unwrap();
let cwd_parent = cwd.parent();
match cwdparent { Some(cwdparent) => { asserteq!(Path::join(&cwdparent, Path::new("path/to/123/456")).tostr().unwrap(), p.absolutize().unwrap().tostr().unwrap()); } None => { asserteq!(Path::join(Path::new("/"), Path::new("path/to/123/456")).tostr().unwrap(), p.absolutize().unwrap().to_str().unwrap()); } } ```
A path which does not start with a MAIN_SEPARATOR
, Single Dot and Double Dots, will act like having a single dot at the start when absolutize
method is used.
```rust extern crate path_absolutize;
use std::path::Path; use std::env;
use path_absolutize::*;
let p = Path::new("path/to/123/456");
asserteq!(Path::join(env::currentdir().unwrap().aspath(), Path::new("path/to/123/456")).tostr().unwrap(), p.absolutize().unwrap().to_str().unwrap()); ```
```rust extern crate path_absolutize;
use std::path::Path; use std::env;
use path_absolutize::*;
let p = Path::new("path/../../to/123/456");
let cwd = env::current_dir().unwrap();
let cwd_parent = cwd.parent();
match cwdparent { Some(cwdparent) => { asserteq!(Path::join(&cwdparent, Path::new("to/123/456")).tostr().unwrap(), p.absolutize().unwrap().tostr().unwrap()); } None => { asserteq!(Path::join(Path::new("/"), Path::new("to/123/456")).tostr().unwrap(), p.absolutize().unwrap().to_str().unwrap()); } } ```
Get an absolute path only under a specific directory.
The dots in a path will be parsed even if it is already an absolute path (which means the path starts with a MAIN_SEPARATOR
on Unix-like systems).
```rust extern crate path_absolutize;
use std::path::Path;
use path_absolutize::*;
let p = Path::new("/path/to/123/456");
asserteq!("/path/to/123/456", p.absolutizevirtually("/").unwrap().to_str().unwrap()); ```
```rust extern crate path_absolutize;
use std::path::Path;
use path_absolutize::*;
let p = Path::new("/path/to/./123/../456");
asserteq!("/path/to/456", p.absolutizevirtually("/").unwrap().to_str().unwrap()); ```
Every absolute path should under the virtual root.
```rust extern crate path_absolutize;
use std::path::Path;
use std::io::ErrorKind;
use path_absolutize::*;
let p = Path::new("/path/to/123/456");
asserteq!(ErrorKind::InvalidInput, p.absolutizevirtually("/virtual/root").unwrap_err().kind()); ```
Every relative path should under the virtual root.
```rust extern crate path_absolutize;
use std::path::Path;
use std::io::ErrorKind;
use path_absolutize::*;
let p = Path::new("./path/to/123/456");
asserteq!(ErrorKind::InvalidInput, p.absolutizevirtually("/virtual/root").unwrap_err().kind()); ```
```rust extern crate path_absolutize;
use std::path::Path;
use std::io::ErrorKind;
use path_absolutize::*;
let p = Path::new("../path/to/123/456");
asserteq!(ErrorKind::InvalidInput, p.absolutizevirtually("/virtual/root").unwrap_err().kind()); ```
A path which does not start with a MAIN_SEPARATOR
, Single Dot and Double Dots, will be located in the virtual root after the absolutize_virtually
method is used.
```rust extern crate path_absolutize;
use std::path::Path;
use path_absolutize::*;
let p = Path::new("path/to/123/456");
asserteq!("/virtual/root/path/to/123/456", p.absolutizevirtually("/virtual/root").unwrap().to_str().unwrap()); ```
```rust extern crate path_absolutize;
use std::path::Path;
use path_absolutize::*;
let p = Path::new("path/to/../../../../123/456");
asserteq!("/virtual/root/123/456", p.absolutizevirtually("/virtual/root").unwrap().to_str().unwrap()); ```
By default, the absolutize
method creates a new PathBuf
instance of the CWD every time in its operation. The overhead is obvious. Although it allows us to safely change the CWD at runtime by the program itself (e.g. using the std::env::set_current_dir
function) or outside controls (e.g. using gdb to call chdir
), we don't need that in most cases.
In order to parse paths with better performance, this crate provides two ways to cache the CWD.
Enabling the lazy_static_cache
feature can let this crate use lazy_static
to cache the CWD. It's thread-safe and does not need to modify any code, but once the CWD is cached, it cannot be changed anymore at runtime.
toml
[dependencies.path-absolutize]
version = "*"
default-features = false
features = ["lazy_static_cache"]
Enabling the unsafe_cache
feature can let this crate use a mutable static variable to cache the CWD. It allows the program to change the CWD at runtime by the program itself, but it's not thread-safe.
You need to use the update_cwd
function to initialize the CWD first. The function should also be used to update the CWD after the CWD is changed.
toml
[dependencies.path-absolutize]
version = "*"
default-features = false
features = ["unsafe_cache"]
```rust extern crate path_absolutize;
use std::path::Path;
use path_absolutize::*;
unsafe { update_cwd(); }
let p = Path::new("./path/to/123/456");
println!("{}", p.absolutize().unwrap().to_str().unwrap());
std::env::setcurrentdir("/").unwrap();
unsafe { update_cwd(); }
println!("{}", p.absolutize().unwrap().to_str().unwrap()); ```
bash
cargo bench
bash
cargo bench --no-default-features --features lazy_static_cache
bash
cargo bench --no-default-features --features unsafe_cache
https://crates.io/crates/path-absolutize
https://docs.rs/path-absolutize