What the Class Is Used For

Use Chilkat.DirTree when an application needs to scan a directory tree and process each file or sub-directory one at a time. The class is useful for building file lists, walking folder structures, finding files, calculating sizes, copying or synchronizing directory trees, or feeding each path into another Chilkat class.

Iterate a Directory Tree Start at BaseDir and visit each file or sub-directory.

Recursive or Flat Traversal Use Recurse to choose whether sub-directories are traversed.

Read Current Item Details Access full paths, relative paths, UNC paths, file size, and whether the current item is a directory.

Handle End-of-Iteration Clearly Use DoneIterating to distinguish normal completion from an error.

Typical Workflow

Create a DirTree object.
Set BaseDir to the directory where iteration should begin.
Set Recurse to true for recursive traversal, or false for only the immediate contents of BaseDir.
Optionally set UncommonOptions, such as Q_EncodePaths, for special path handling.
Call BeginIterate to position the iterator at the first file or sub-directory.
Read properties such as FullPath, RelativePath, IsDirectory, and FileSize64 for the current item.
Call AdvancePosition to move to the next item.
When BeginIterate or AdvancePosition returns false, check DoneIterating to determine whether iteration completed normally or an error occurred.
Check LastErrorText after errors or unexpected behavior.

Core Concepts

Concept	Meaning	Important Members
Base Directory	The starting directory for traversal.	BaseDir
Recursive Traversal	When enabled, iteration descends into sub-directories. When disabled, only immediate children are visited.	Recurse
Current Position	The current file or sub-directory being visited by the iterator.	BeginIterate, AdvancePosition
Current Item Paths	The current item can be retrieved as an absolute path, UNC path, or path relative to BaseDir.	FullPath, FullUncPath, RelativePath
File vs Directory	The iterator can tell whether the current item is a file or sub-directory.	IsDirectory
Normal Completion vs Error	A false return from an iteration method can mean either normal completion or an error. DoneIterating distinguishes the two.	BeginIterate, AdvancePosition, DoneIterating

Core Properties

Property	Purpose	Guidance
BaseDir	The directory where iteration begins.	Set this before calling BeginIterate.
Recurse	Controls whether iteration is recursive.	Default is true. Set to false for non-recursive traversal.
DoneIterating	Indicates that the last file or sub-directory has been iterated.	Check this when BeginIterate or AdvancePosition returns false.
IsDirectory	Indicates whether the current item is a directory.	true means the current item is a sub-directory; false means it is a file.
FullPath	Absolute directory path of the current file or sub-directory.	Use when an absolute path is needed for file operations.
FullUncPath	Absolute UNC directory path of the current file or sub-directory.	Useful on Windows when UNC-style path representation is needed.
RelativePath	Relative directory path of the current file or sub-directory.	The path is relative to BaseDir. Useful when recreating directory structures elsewhere.
FileSize32	File size of the current file as a 32-bit integer.	Returns 0 when the current item is a directory. Prefer FileSize64 for large files.
FileSize64	File size of the current file as a 64-bit integer.	Returns 0 when the current item is a directory. Best choice for files larger than 2 GB.
FileSizeStr	File size of the current file as a decimal string.	Returns 0 when the current item is a directory. Useful in languages or environments where large integer handling is limited.
UncommonOptions	Catch-all property for uncommon needs.	Defaults to the empty string and should typically remain empty. Supports Q_EncodePaths to return file paths Q-encoded.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Iteration Methods

Method	Purpose	Important Return-Value Rule
BeginIterate	Begins traversal and positions the iterator at the first file or sub-directory.	If it returns false, check DoneIterating. If DoneIterating is true, there were simply 0 files/directories. Otherwise, the false value indicates an error.
AdvancePosition	Advances the iterator to the next file or sub-directory.	If it returns false, check DoneIterating. If DoneIterating is true, traversal reached the end normally. Otherwise, the false value indicates an error.

Key pattern: Treat false from BeginIterate or AdvancePosition as ambiguous until DoneIterating is checked.

Iteration State

State	What It Means	How to Handle It
BeginIterate returns true	The iterator is positioned at the first item.	Read current-item properties, then continue with AdvancePosition.
BeginIterate returns false and DoneIterating is true	The directory contains no files or sub-directories to iterate.	Treat this as normal completion, not an error.
BeginIterate returns false and DoneIterating is false	An error occurred while starting traversal.	Check LastErrorText.
AdvancePosition returns true	The iterator moved to the next item.	Read the current-item properties again.
AdvancePosition returns false and DoneIterating is true	The end of traversal was reached.	Stop iterating normally.
AdvancePosition returns false and DoneIterating is false	An error occurred while advancing.	Stop and check LastErrorText.

Path Properties

Property	Path Type	Typical Use
FullPath	Absolute path	Use for opening, reading, copying, deleting, or processing the current file or directory.
FullUncPath	Absolute UNC path	Use when Windows UNC-style path representation is required.
RelativePath	Path relative to BaseDir	Use when preserving directory layout during copy, backup, upload, or synchronization workflows.

Special path encoding: Set UncommonOptions to Q_EncodePaths when file paths should be returned Q-encoded.

File Size Properties

Property	Return Type	Best Use
FileSize32	int	Use for smaller files when a 32-bit integer is sufficient.
FileSize64	long	Preferred for general use because it supports large files.
FileSizeStr	string	Useful where large integers are inconvenient or where a decimal string is easier to display or pass along.

Directory size rule: All file-size properties return 0 when the current item is a directory.

Method Summary

Method	Purpose	When to Call
BeginIterate	Starts the directory traversal and positions the iterator at the first item.	Call once after setting BaseDir and Recurse.
AdvancePosition	Moves the iterator to the next file or sub-directory.	Call repeatedly after processing the current item.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Iteration does not start	BaseDir, BeginIterate, DoneIterating, LastErrorText	Confirm BaseDir is set. If BeginIterate returns false, check DoneIterating to distinguish an empty directory from an error.
Iteration stops unexpectedly	AdvancePosition, DoneIterating, LastErrorText	If AdvancePosition returns false and DoneIterating is false, check LastErrorText for the error.
Sub-directories are not being traversed	Recurse	Confirm Recurse is true. It defaults to true, but may have been set to false.
Only immediate children are desired	Recurse	Set Recurse to false before calling BeginIterate.
Large file sizes appear incorrect	FileSize32, FileSize64, FileSizeStr	Prefer FileSize64 or FileSizeStr for large files.
Paths contain characters that need encoded representation	UncommonOptions	Use Q_EncodePaths if paths should be returned Q-encoded.

Common Pitfalls

Pitfall	Better Approach
Treating every false return from BeginIterate as an error.	Check DoneIterating. A false return may simply mean there are zero files or directories.
Treating every false return from AdvancePosition as an error.	Check DoneIterating. A false return may simply mean traversal reached the end.
Reading current-item properties before calling BeginIterate.	Call BeginIterate first. On success, the iterator is positioned at the first item.
Using FileSize32 for large files.	Use FileSize64 or FileSizeStr for large-file-safe size handling.
Expecting directories to report accumulated directory size.	File-size properties return 0 for directories. Accumulated directory size must be calculated by summing file entries.
Forgetting that RelativePath is relative to BaseDir.	Use RelativePath for preserving layout, and FullPath for direct filesystem access.

Best Practices

Recommendation	Reason
Set BaseDir and Recurse before starting.	These properties define the scope and depth of the traversal.
Always check DoneIterating after a false iteration return.	It distinguishes normal completion or empty traversal from actual errors.
Use IsDirectory before processing file-specific metadata.	Directories return 0 for file-size properties and may need different handling.
Prefer FileSize64 for file sizes.	It avoids 32-bit limitations and works better for large files.
Use RelativePath for copy, backup, and sync workflows.	It makes it easy to recreate the same structure under a different root.
Leave UncommonOptions empty unless special path handling is required.	The only documented option here is Q_EncodePaths, added for uncommon path-encoding needs.
Check LastErrorText after errors.	It provides the most useful diagnostic detail for traversal startup, advancement, permissions, path, or filesystem-related problems.

Summary

Chilkat.DirTree is a lightweight iterator for traversing files and sub-directories under a base directory. It exposes useful current-item information such as absolute path, UNC path, relative path, file size, and whether the item is a directory. The class supports recursive and non-recursive traversal and uses DoneIterating to distinguish normal completion from errors when iteration methods return false.

The most important practical guidance is to set BaseDir first, choose Recurse intentionally, call BeginIterate before reading current-item properties, use AdvancePosition to move through the tree, and always check DoneIterating after a false return.

Chilkat.DirTree Class Overview