Struct Error

pub struct Error { /* private fields */ }

An error produced by recursively walking a directory.

This error type is a light wrapper around std::io::Error. In particular, it adds the following information:

• The depth at which the error occurred in the file tree, relative to the root.
• The path, if any, associated with the IO error.
• An indication that a loop occurred when following symbolic links. In this case, there is no underlying IO error.

To maintain good ergonomics, this type has a impl From<Error> for std::io::Error defined which preserves the original context. This allows you to use an io::Result with methods in this crate if you don’t care about accessing the underlying error data in a structured form.

Implementations

impl Error

pub fn path(&self) -> Option<&Path>

Returns the path associated with this error if one exists.

For example, if an error occurred while opening a directory handle, the error will include the path passed to std::fs::read_dir.

pub fn loop_ancestor(&self) -> Option<&Path>

Returns the path at which a cycle was detected.

If no cycle was detected, None is returned.

A cycle is detected when a directory entry is equivalent to one of its ancestors.

To get the path to the child directory entry in the cycle, use the path method.

pub fn depth(&self) -> usize

Returns the depth at which this error occurred relative to the root.

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

pub fn io_error(&self) -> Option<&Error>

Inspect the original io::Error if there is one.

None is returned if the Error doesn’t correspond to an io::Error. This might happen, for example, when the error was produced because a cycle was found in the directory tree while following symbolic links.

This method returns a borrowed value that is bound to the lifetime of the Error. To obtain an owned value, the into_io_error can be used instead.

This is the original io::Error and is not the same as impl From<Error> for std::io::Error which contains additional context about the error.

Example

use std::io;
use std::path::Path;

use walkdir::WalkDir;

for entry in WalkDir::new("foo") {
    match entry {
        Ok(entry) => println!("{}", entry.path().display()),
        Err(err) => {
            let path = err.path().unwrap_or(Path::new("")).display();
            println!("failed to access entry {}", path);
            if let Some(inner) = err.io_error() {
                match inner.kind() {
                    io::ErrorKind::InvalidData => {
                        println!(
                            "entry contains invalid data: {}",
                            inner)
                    }
                    io::ErrorKind::PermissionDenied => {
                        println!(
                            "Missing permission to read entry: {}",
                            inner)
                    }
                    _ => {
                        println!(
                            "Unexpected error occurred: {}",
                            inner)
                    }
                }
            }
        }
    }
}

pub fn into_io_error(self) -> Option<Error>

Similar to io_error except consumes self to convert to the original io::Error if one exists.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(walk_err: Error) -> Error

Convert the Error to an io::Error, preserving the original Error as the “inner error”. Note that this also makes the display of the error include the context.

This is different from into_io_error which returns the original io::Error.