Iterates, non-recursively, through a directory.

This is a thin abstraction over the standard libraries IterableDir.iterate() behavior. The main benefit of zul.fs.readDir is the ability collect all entries, sorted or not, in a slice.

// Parameters:
// 1- Absolute or relative directory path
var it = try zul.fs.readDir("/tmp/dir");
defer it.deinit();

// can iterate through the files
while (try it.next()) |entry| {
	std.debug.print("{s} {any}\n", .{entry.name, entry.kind});
}

// reset the iterator
it.reset();

// or can collect them into a slice, optionally sorted:
const sorted_entries = try it.all(allocator, .dir_first);
for (sorted_entries) |entry| {
	std.debug.print("{s} {any}\n", .{entry.name, entry.kind});
}

path: []const u8

Absolute or relative path to the directory.

On success, readDir returns an Iterator.

Releases the underlying operating system resources. Frees memory allocated by all.

Gets all remaining directory entries. sort can be one of four values:

  • none - no sorting.
  • alphabetic - sorted alphabetically.
  • dir_first - sorted alphabetically with directories first.
  • dir_last - sorted alphabetically with directories last.

Normally, the entry.name is only valid up until the next iteration. In order to collect all entries, this function clones the names. Internally this, along with the std.ArrayList used to collect the entries, are managed by an ArenaAllocator, which is cleared on deinit. Compared to simply iterating through the entries one at a time, this adds considerable overhead. But, if you need all entries, sorted or otherwise, this cloning is necessary. If you don't, prefer using the standard libraries std.fs.IterableDir directly.

Returns the next directory entry, or null if there are no more entries.

The returned entry is only valid until the next call to next, deinit or reset.

The order of iteration depends on the file system, but generally no guarantee is made. Whether or not entries added/removed during iteration are seen by the iterator depends also depends on the file system.

Resets the iterator. Once reset, the iterator can be iterated again from the start.

Entry is an std.fs.IterableDir.Entry which has two fields: name: []const u8 and kind: std.fs.File.Kind.