DirTree Zig 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

// Add the package once:
//     zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz
// and in build.zig:
//     const chilkat = b.dependency("chilkat", .{ .target = target, .optimize = optimize });
//     exe.root_module.addImport("chilkat", chilkat.module("chilkat"));
const chilkat = @import("chilkat");

// Once per process, before any other Chilkat call:
try chilkat.unlockBundle("Anything for 30-day trial");

const dir_tree = try chilkat.DirTree.init();
defer dir_tree.deinit();

pub fn init() Allocator.Error!DirTree

Creates the underlying native Chilkat object. DirTree is a one-pointer struct passed by value; copying it copies the handle (two names for one object). Returns error.OutOfMemory if the library could not allocate the object. Use an object from one thread at a time; it may be handed from one thread to another.

pub fn deinit(self: DirTree) void

Releases the native object. Call it exactly once per object (usually with defer); the handle is invalid afterwards. Objects returned by methods are owned by the caller too and are released the same way.

pub fn fromHandle(h: *chilkat.c.CkDirTree.HCkDirTree) DirTree

Wraps a handle obtained from the C API (chilkat.c.CkDirTree), taking ownership of it. The struct's handle field goes the other way, for anything the Zig API does not cover.

Errors and memory

Methods that can fail return an error union: a method whose only outcome is success or failure returns Error!void; a method producing a string returns (Error || Allocator.Error)![:0]u8; a method producing an object returns Error!T. chilkat.Error is error{ChilkatFailed}; the reason for a failure is in getLastErrorText, and the object remains usable. Properties never fail, and methods that answer a question (hasMember, isUnlocked, ...) return a plain bool.

String arguments are [:0]const u8 (UTF-8; string literals can be passed as is). String results are copies allocated with the allocator argument and owned by the caller, so they stay valid across later calls on the same object.

const text = dir_tree.someMethod(allocator, ...) catch |err| {
    const why = try dir_tree.getLastErrorText(allocator);
    defer allocator.free(why);
    std.debug.print("{s}\n", .{why});
    return err;
};
defer allocator.free(text);

Properties

BaseDir

// read/write
pub fn getBaseDir(self: DirTree, allocator: Allocator) Allocator.Error![:0]u8
pub fn setBaseDir(self: DirTree, value: [:0]const u8) void

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 Zig 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 and memory

Properties

BaseDir

DebugLogFilePath

DoneIterating

FileSize32

FileSize64

FileSizeStr

FullPath

FullUncPath

IsDirectory

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

Recurse

RelativePath

UncommonOptions

VerboseLogging

Version

Methods

AdvancePosition

BeginIterate