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

Available on crate feature walk only.

Expand description

An Iterator over WalkEntrys that can filter directory trees.

A FileIterator is a TreeIterator that yields WalkEntrys. 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 Globs against directory trees.

Required Methods§

source

fn filter_tree<F>(self, f: F) -> FilterTree<Self, F> ⓘwhere F: FnMut(&WalkEntry<'static>) -> Option<FilterTarget>,

Filters WalkEntrys and controls the traversal of directory trees.

This function creates an adaptor that filters WalkEntrys 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());
}

Object Safety§

This trait is not object safe.

Implementors§