pub struct Root { /* private fields */ }
Expand description
An open root directory from which relative paths can be opened.
In contrast to using APIs such as RelativePath::to_path
, this does not
require allocations to open a path.
This is achieved by keeping an open handle to the directory and using
platform-specific APIs to open a relative path, such as openat
on unix
.
Implementations§
Source§impl Root
impl Root
Sourcepub fn open_options(&self) -> OpenOptions<'_>
pub fn open_options(&self) -> OpenOptions<'_>
Construct an open options associated with this root.
§Examples
use relative_path_utils::Root;
let root = Root::new(".")?;
let file = root.open_options().read(true).open("foo.txt");
Sourcepub fn create<P>(&self, path: P) -> Result<File>where
P: AsRef<RelativePath>,
pub fn create<P>(&self, path: P) -> Result<File>where
P: AsRef<RelativePath>,
Opens a file in write-only mode.
This function will create a file if it does not exist, and will truncate it if it does.
Depending on the platform, this function may fail if the full directory
path does not exist. See the OpenOptions::open
function for more
details.
See also Root::write()
for a simple function to create a file with a
given data.
§Errors
Errors if the underlying I/O operation fails.
§Examples
use std::io::Write;
use relative_path_utils::Root;
let root = Root::new(".")?;
let mut f = root.create("foo.txt")?;
f.write_all(&1234_u32.to_be_bytes())?;
Sourcepub fn open<P>(&self, path: P) -> Result<File>where
P: AsRef<RelativePath>,
pub fn open<P>(&self, path: P) -> Result<File>where
P: AsRef<RelativePath>,
Attempts to open a file in read-only mode.
See the OpenOptions::open
method for more details.
If you only need to read the entire file contents, consider
std::fs::read()
or
std::fs::read_to_string()
instead.
§Errors
This function will return an error if path
does not already exist.
Other errors may also be returned according to OpenOptions::open
.
§Examples
use std::io::Read;
use relative_path_utils::Root;
let root = Root::new(".")?;
let mut f = root.open("foo.txt")?;
let mut data = vec![];
f.read_to_end(&mut data)?;
Sourcepub fn read<P>(&self, path: P) -> Result<Vec<u8>>where
P: AsRef<RelativePath>,
pub fn read<P>(&self, path: P) -> Result<Vec<u8>>where
P: AsRef<RelativePath>,
Read the entire contents of a file into a bytes vector.
This is a convenience function for using File::open
and
read_to_end
with fewer imports and without an intermediate variable.
§Errors
This function will return an error if path
does not already exist.
Other errors may also be returned according to OpenOptions::open
.
While reading from the file, this function handles
io::ErrorKind::Interrupted
with automatic retries. See io::Read
documentation for details.
§Examples
use std::net::SocketAddr;
use relative_path_utils::Root;
let root = Root::new(".")?;
let foo: SocketAddr = String::from_utf8_lossy(&root.read("address.txt")?).parse()?;
Sourcepub fn read_to_string<P>(&self, path: P) -> Result<String>where
P: AsRef<RelativePath>,
pub fn read_to_string<P>(&self, path: P) -> Result<String>where
P: AsRef<RelativePath>,
Read the entire contents of a file into a string.
This is a convenience function for using File::open
and
read_to_string
with fewer imports and without an intermediate
variable.
§Errors
This function will return an error if path
does not already exist.
Other errors may also be returned according to OpenOptions::open
.
If the contents of the file are not valid UTF-8, then an error will also be returned.
§Examples
use std::net::SocketAddr;
use relative_path_utils::Root;
let root = Root::new(".")?;
let foo: SocketAddr = root.read_to_string("address.txt")?.parse()?;
Sourcepub fn write<P, C>(&self, path: P, contents: C) -> Result<()>
pub fn write<P, C>(&self, path: P, contents: C) -> Result<()>
Write a slice as the entire contents of a file.
This function will create a file if it does not exist, and will entirely replace its contents if it does.
Depending on the platform, this function may fail if the full directory path does not exist.
This is a convenience function for using File::create
and
write_all
with fewer imports.
§Errors
Fails if an underlying I/O operation fails.
§Examples
use relative_path_utils::Root;
let root = Root::new(".")?;
root.write("foo.txt", b"Lorem ipsum")?;
root.write("bar.txt", "dolor sit")?;
Sourcepub fn metadata<P>(&self, path: P) -> Result<Metadata>where
P: AsRef<RelativePath>,
pub fn metadata<P>(&self, path: P) -> Result<Metadata>where
P: AsRef<RelativePath>,
Given a path, query the file system to get information about a file, directory, etc.
This function will traverse symbolic links to query information about the destination file.
§Platform-specific behavior
This function currently corresponds to the stat
function on Unix and
the GetFileInformationByHandle
function on Windows. Note that, this
may change in the future.
§Errors
This function will return an error in the following situations, but is not limited to just these cases:
- The user lacks permissions to perform
metadata
call onpath
. path
does not exist.
§Examples
use relative_path_utils::Root;
let root = Root::new(".")?;
let attr = root.metadata("file/path.txt")?;
Sourcepub fn is_dir<P>(&self, path: P) -> boolwhere
P: AsRef<RelativePath>,
pub fn is_dir<P>(&self, path: P) -> boolwhere
P: AsRef<RelativePath>,
Returns true
if the path exists on disk and is pointing at a
directory.
This function will traverse symbolic links to query information about the destination file.
If you cannot access the metadata of the file, e.g. because of a
permission error or broken symbolic links, this will return false
.
§Examples
use relative_path_utils::Root;
let root = Root::new(".")?;
assert_eq!(root.is_dir("./is_a_directory/"), true);
assert_eq!(root.is_dir("a_file.txt"), false);
§See Also
This is a convenience function that coerces errors to false. If you want
to check errors, call Root::metadata
and handle its Result
. Then
call Metadata::is_dir
if it was Ok
.
Sourcepub fn read_dir<P>(&self, path: P) -> Result<ReadDir>where
P: AsRef<RelativePath>,
pub fn read_dir<P>(&self, path: P) -> Result<ReadDir>where
P: AsRef<RelativePath>,
Returns an iterator over the entries within a directory.
The iterator will yield instances of
. New errors may be encountered
after an iterator is initially constructed. Entries for the current and
parent directories (typically io::Result
<DirEntry
>.
and ..
) are skipped.
§Platform-specific behavior
This function currently corresponds to the opendir
function on Unix
and the FindFirstFile
function on Windows. Advancing the iterator
currently corresponds to readdir
on Unix and FindNextFile
on Windows.
Note that, this may change in the future.
The order in which this iterator returns entries is platform and filesystem dependent.
§Errors
This function will return an error in the following situations, but is not limited to just these cases:
- The provided
path
doesn’t exist. - The process lacks permissions to view the contents.
- The
path
points at a non-directory file.
§Examples
use std::io;
use relative_path_utils::{Root, DirEntry};
use relative_path::RelativePath;
// one possible implementation of walking a directory only visiting files
fn visit_dirs(root: &Root, dir: &RelativePath, cb: &dyn Fn(&DirEntry)) -> io::Result<()> {
if root.is_dir(dir) {
for entry in root.read_dir(dir)? {
let entry = entry?;
let file_name = entry.file_name();
let path = dir.join(file_name.to_string_lossy().as_ref());
if root.is_dir(&path) {
visit_dirs(root, &path, cb)?;
} else {
cb(&entry);
}
}
}
Ok(())
}
Sourcepub fn glob<'a, P>(&'a self, path: &'a P) -> Glob<'a>
pub fn glob<'a, P>(&'a self, path: &'a P) -> Glob<'a>
Parse a glob over the specified path.
To perform the globbing, use Glob::matcher
.
§Examples
use relative_path_utils::Root;
let root = Root::new("src")?;
let glob = root.glob("**/*.rs");
let mut results = Vec::new();
for e in glob.matcher() {
results.push(e?);
}
results.sort();
assert_eq!(results, vec!["lib.rs", "main.rs"]);