# dirscent — directory descent

`dirscent` provides a simple and efficient iterator over the entries of
a directory, and, recursively, over the entries of all subdirectories.

## Install

Add the dependency to your `Cargo.toml`

```toml
[dependencies]
dirscent = "0.1"
```

Or from the command line

```
% cargo add dirscent@0.1
```

## Usage

Iterate down the hierarchy skipping the entries for which the process
does not have permissions

```rust
use dirscent::dirscent;

fn main() {
    for it in dirscent("/usr")
        .unwrap()
        .postorder()
        .skip_permission_denied()
    {
        match it {
            Ok(entry) => println!("{}", entry.path().display()),
            Err(err) => eprintln!("{err:?}"),
        }
    }
}
```

## Performance

On my system, `dirscent` is 1.5× faster than [`fts(3)`] and 2× faster than
[`find(1)`]. Run `benches/b.sh` and see for yourself.

[`find(1)`]: https://man7.org/linux/man-pages/man1/find.1.html
[`fts(3)`]: https://man7.org/linux/man-pages/man3/fts.3.html