Struct fs_more::directory::DirectoryScan

pub struct DirectoryScan { /* private fields */ }

A directory scanner with configurable scan depth and symlink behaviour.

This scanner is able to recursively iterate over the directory as well as optionally follow symbolic links. If, however, you’re looking for something with a bit more features, such as lazy iteration and sorting, consider the walkdir crate.

Implementations

impl DirectoryScan

pub fn scan_with_options<P>( directory_path: P, options: DirectoryScanOptions, ) -> Result<Self, DirectoryScanError>

where P: Into<PathBuf>,

Perform a directory scan.

Scan depth

Maximum scanning depth can be configured by setting options.maximum_scan_depth.

Symbolic links

This scanner can follow symbolic links, see options.follow_symbolic_links for more information.

directory_path symlink behaviour

Regardless of the symbolic link option described above: if directory_path itself is a symbolic link to a directory, the link destination will be resolved before beginning the scan.

pub fn files(&self) -> &[PathBuf]

Returns a slice of all scanned files (paths are absolute).

pub fn into_files(self) -> Vec<PathBuf>

Consumes self and returns a Vec containing all scanned files (paths are absolute).

If you are also interested in directories, look at Self::files + Self::directories or Self::into_scanned_files_and_directories instead.

pub fn directories(&self) -> &[PathBuf]

Returns a slice of all scanned directories (paths are absolute).

pub fn into_directories(self) -> Vec<PathBuf>

Consumes self and returns a Vec containing all scanned directories (paths are absolute).

If you are also interested in files, look at Self::files + Self::directories or Self::into_scanned_files_and_directories instead.

pub fn into_scanned_files_and_directories(self) -> ScannedFilesAndDirectories

Consumes self and returns a small struct containing two fields: files and directories.

Use this method when you wish to consume the scanner and are interested in both scanned files and directories. Alternatives that don’t consume the scanner are Self::files and Self::directories.

pub fn total_size_in_bytes(&self) -> Result<u64, DirectorySizeScanError>

Returns the total size in bytes of all scanned files and directories.

Potential file system race conditions

Careful: this method iterates over the scanned files and directories and queries their size at call time. This means the caller will get an up-to-date directory size if they happen to call the method multiple times, potentially after modifying the one of the scanned files.

However, it also means that it this method can return, among other things, an Err(DirectorySizeScanError::ScanEntryNoLongerExists) if any file or directory that was scanned at initialization has been removed since. The same applies for files changing their read permissions, with that usually resulting in Err(DirectorySizeScanError::UnableToAccessFile).

This is very much the same thing as the relatively well-known file system race condition inherent in if file_exists(): then open_file() (time-of-check, time-of-use), just on a bigger scale.

The impact of this is—in most cases—relatively low, but it is worth noting.

Impacts of scan depth limits

Careful: if you initialized DirectoryScan with a scan depth limit that is smaller than the actual depth of the directory tree you’re scanning, the value returned by this function will be smaller than the “real” contents of that directory.

It is up to the user to decide whether that is desired behavior or not. To find out whether the returned number of bytes will not reflect the full depth of the directory structure, see Self::covers_entire_directory_tree.

pub fn covers_entire_directory_tree(&self) -> bool

Returns a bool indicating whether this scan covered the entire directory tree.

For example, this can be false when the user limits the scan depth to e.g. DirectoryScanDepthLimit::Limited{ maximum_depth: 1 }, but the actual directory structure has e.g. three layers of subdirectories and files.

If maximum_scan_depth is set to DirectoryScanDepthLimit::Unlimited in the constructor for this scan, this method will always return true.

Trait Implementations

impl Clone for DirectoryScan

fn clone(&self) -> DirectoryScan

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DirectoryScan

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

Formats the value using the given formatter.

impl PartialEq for DirectoryScan

fn eq(&self, other: &DirectoryScan) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for DirectoryScan

impl StructuralPartialEq for DirectoryScan