Trait wax::FileIterator
source · pub trait FileIterator: Sized + TreeIterator<Item = Result<WalkEntry<'static>, WalkError>> {
// Required method
fn filter_tree<F>(self, f: F) -> FilterTree<Self, F> ⓘ
where F: FnMut(&WalkEntry<'static>) -> Option<FilterTarget>;
}
walk
only.Expand description
An Iterator
over WalkEntry
s that can filter directory trees.
A FileIterator
is a TreeIterator
that yields WalkEntry
s. This trait is implemented by
Walk
and adaptors like FilterTree
. A TreeIterator
is an iterator that reads its items
from a tree and therefore can meaningfully filter not only items but their corresponding
sub-trees to avoid unnecessary work. To that end, this trait provides the filter_tree
function, which allows directory trees to be discarded (not read from the file system) when
matching Glob
s against directory trees.
Required Methods§
sourcefn filter_tree<F>(self, f: F) -> FilterTree<Self, F> ⓘwhere
F: FnMut(&WalkEntry<'static>) -> Option<FilterTarget>,
fn filter_tree<F>(self, f: F) -> FilterTree<Self, F> ⓘwhere F: FnMut(&WalkEntry<'static>) -> Option<FilterTarget>,
Filters WalkEntry
s and controls the traversal of directory trees.
This function creates an adaptor that filters WalkEntry
s and furthermore specifies how
iteration proceeds to traverse directory trees. The adaptor accepts a function that, when
discarding a WalkEntry
, yields a FilterTarget
. If the entry refers to a directory
and FilterTarget::Tree
is returned by the function, then iteration will not descend
into that directory and the tree will not be read from the file system. Therefore, this
adaptor should be preferred over functions like Iterator::filter
when discarded
directories do not need to be read.
Errors are not filtered, so if an error occurs reading a file at a path that would have been discarded, then that error is still yielded by the iterator.
Examples
The FilterTree
adaptor can be used to apply additional custom filtering that avoids
unnecessary directory reads. The following example filters out hidden files on Unix and
Windows. On Unix, hidden files are filtered out nominally via not
. On Windows,
filter_tree
is used to detect the hidden attribute. In both cases, the
adaptor does not read conventionally hidden directory trees.
use wax::Glob;
#[cfg(windows)]
use wax::{FileIterator, FilterTarget};
let glob = Glob::new("**/*.(?i){jpg,jpeg}").unwrap();
let walk = glob.walk("./Pictures");
// Filter out nominally hidden files on Unix. Like `filter_tree`, `not` does not perform
// unnecessary reads of directory trees.
#[cfg(unix)]
let walk = walk.not(["**/.*/**"]).unwrap();
// Filter out files with the hidden attribute on Windows.
#[cfg(windows)]
let walk = walk.filter_tree(|entry| {
use std::os::windows::fs::MetadataExt as _;
const ATTRIBUTE_HIDDEN: u32 = 0x2;
let attributes = entry.metadata().unwrap().file_attributes();
if (attributes & ATTRIBUTE_HIDDEN) == ATTRIBUTE_HIDDEN {
// Do not read hidden directory trees.
Some(FilterTarget::Tree)
}
else {
None
}
});
for entry in walk {
let entry = entry.unwrap();
println!("JPEG: {:?}", entry.path());
}