Struct walkdir::WalkDir [−] [src]

pub struct WalkDir { /* fields omitted */ }

A builder to create an iterator for recursively walking a directory.

Results are returned in depth first fashion, with directories yielded before their contents. The order is unspecified. Directory entries . and .. are always omitted.

If an error occurs at any point during iteration, then it is returned in place of its corresponding directory entry and iteration continues as normal. If an error occurs while opening a directory for reading, it is skipped. Iteration may be stopped at any time. When the iterator is destroyed, all resources associated with it are freed.

Usage

This type implements IntoIterator so that it may be used as the subject of a for loop. You may need to call into_iter explicitly if you want to use iterator adapters such as filter_entry.

Idiomatic use of this type should use method chaining to set desired options. For example, this only shows entries with a depth of 1, 2 or 3 (relative to foo):

use walkdir::WalkDir;

for entry in WalkDir::new("foo").min_depth(1).max_depth(3) {
    let entry = entry.unwrap();
    println!("{}", entry.path().display());
}

Note that the iterator by default includes the top-most directory. Since this is the only directory yielded with depth 0, it is easy to ignore it with the min_depth setting:

use walkdir::WalkDir;

for entry in WalkDir::new("foo").min_depth(1) {
    let entry = entry.unwrap();
    println!("{}", entry.path().display());
}

This will only return descendents of the foo directory and not foo itself.

Loops

This iterator (like most/all recursive directory iterators) assumes that no loops can be made with hard links on your file system. In particular, this would require creating a hard link to a directory such that it creates a loop. On most platforms, this operation is illegal.

Note that when following symbolic/soft links, loops are detected and an error is reported.

Methods

impl WalkDir
[src]

Create a builder for a recursive directory iterator starting at the file path root. If root is a directory, then it is the first item yielded by the iterator. If root is a file, then it is the first and only item yielded by the iterator.

Set the minimum depth of entries yielded by the iterator.

The smallest depth is 0 and always corresponds to the path given to the new function on this type. Its direct descendents have depth 1, and their descendents have depth 2, and so on.

Set the maximum depth of entries yield by the iterator.

The smallest depth is 0 and always corresponds to the path given to the new function on this type. Its direct descendents have depth 1, and their descendents have depth 2, and so on.

Note that this will not simply filter the entries of the iterator, but it will actually avoid descending into directories when the depth is exceeded.

Follow symbolic links. By default, this is disabled.

When yes is true, symbolic links are followed as if they were normal directories and files. If a symbolic link is broken or is involved in a loop, an error is yielded.

When enabled, the yielded DirEntry values represent the target of the link while the path corresponds to the link. See the DirEntry type for more details.

Warning: bug with junctions on Window

There is a bug that may affect following symbolic links on Windows when using junctions.

Set the maximum number of simultaneously open file descriptors used by the iterator.

n must be greater than or equal to 1. If n is 0, then it is set to 1 automatically. If this is not set, then it defaults to some reasonably low number.

This setting has no impact on the results yielded by the iterator (even when n is 1). Instead, this setting represents a trade off between scarce resources (file descriptors) and memory. Namely, when the maximum number of file descriptors is reached and a new directory needs to be opened to continue iteration, then a previous directory handle is closed and has its unyielded entries stored in memory. In practice, this is a satisfying trade off because it scales with respect to the depth of your file tree. Therefore, low values (even 1) are acceptable.

Note that this value does not impact the number of system calls made by an exhausted iterator.

Set a function for sorting directory entries.

If a compare function is set, the resulting iterator will return all paths in sorted order. The compare function will be called to compare names from entries from the same directory using only the name of the entry.

use std::cmp;
use std::ffi::OsString;
use walkdir::WalkDir;

WalkDir::new("foo").sort_by(|a,b| a.cmp(b));

Trait Implementations

impl IntoIterator for WalkDir
[src]

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more