DirTree Rust Reference Documentation

DirTree

Current Version: 11.6.1

Chilkat.DirTree

Iterate through files and subdirectories under a base directory.

Chilkat.DirTree is a lightweight directory-tree iterator for traversing files and subdirectories under a selected base directory. It supports recursive and non-recursive traversal and exposes useful information about the current item, including absolute path, UNC path, relative path, file size, and whether the current item is a directory.

Directory traversal

Iterate through the contents of a base directory, either recursively or one level at a time.

Current-item details

Get the current item's full path, relative path, UNC path, size, and directory/file status.

Recursive scanning

Traverse entire directory trees when an application needs to process all nested files and folders.

Non-recursive listing

Limit iteration to the immediate contents of the base directory when deeper traversal is not needed.

Path-friendly output

Use absolute or relative paths depending on whether the application needs filesystem access or archive-style relative names.

Error-aware iteration

Use DoneIterating to distinguish normal completion from an error when an iteration method returns false.

Common pattern: Set the base directory and recursion behavior, begin iterating, process each current item using the path and metadata properties, then check DoneIterating when iteration stops to determine whether traversal completed normally or ended because of an error.

For an extended overview, see DirTree Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::DirTree;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let dir_tree = DirTree::new();
// ... the native object is freed when `dir_tree` goes out of scope.

pub fn new() -> DirTree

Creates the underlying native Chilkat object (DirTree also implements Default). Every method takes &self, so the object never needs to be declared mut. A DirTree is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for DirTree

The native object is freed when the DirTree is dropped — when it goes out of scope, or explicitly with drop(dir_tree). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<DirTree>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match dir_tree.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

BaseDir

// read/write
pub fn base_dir(&self) -> String
pub fn set_base_dir(&self, value: &str)

Specifies the root directory whose contents are traversed. Set this property before calling BeginIterate.

The value may be an absolute filesystem path or a relative path. A relative path is resolved from the calling process's current working directory.

Iteration scope: The iterator visits the files and subdirectories contained under this directory. The Recurse property determines whether nested levels are included.

More Information and Examples

Iterate over Files and Directories in Filesystem Directory Tree

Method result	`DoneIterating`	Meaning
`false`	`true`	The directory was empty, or the last item has been passed. This is normal completion.
`false`	`false`	An error occurred. Examine `LastErrorText`.

`true`	Visit files and directories throughout the complete tree rooted at `BaseDir`.
`false`	Visit only the immediate contents of `BaseDir`.

Return value	`DoneIterating`	Meaning
`true`	`false`	The iterator advanced successfully and a current item is available.
`false`	`true`	The last item has been passed; traversal completed normally.
`false`	`false`	An error occurred. Examine `LastErrorText`.

Return value	`DoneIterating`	Meaning
`true`	`false`	The first item is available.
`false`	`true`	The directory contains no items in the selected traversal scope. This is not an error.
`false`	`false`	Initialization failed. Examine `LastErrorText`.

DirTree Rust Reference Documentation

DirTree

Current Version: 11.6.1

Iterate through files and subdirectories under a base directory.

Directory traversal

Current-item details

Recursive scanning

Non-recursive listing

Path-friendly output

Error-aware iteration

Object Creation

Errors

Properties

BaseDir

DebugLogFilePath

DoneIterating

FileSize32

FileSize64

FileSizeStr

FullPath

FullUncPath

IsDirectory

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

Recurse

RelativePath

UncommonOptions

VerboseLogging

Version

Methods

AdvancePosition

BeginIterate