A path component iterator that can move forwards and backwards.
The 'root' of the path (/ for POSIX, things like C:\, \\server\share\, etc
for Windows) is treated specially and will never be returned by any of the
first, last, next, or previous functions.
Multiple consecutive path separators are skipped (treated as a single separator)
when iterating.
All returned component names/paths are slices of the original path.
There is no normalization of paths performed while iterating.
pub fn ComponentIterator(comptime path_type: PathType, comptime T: type) typepub fn ComponentIterator(comptime path_type: PathType, comptime T: type) type {
return struct {
path: []const T,
/// Length of the root with at most one trailing path separator included (e.g. `C:/`).
root_len: usize,
/// Length of the root with all trailing path separators included (e.g. `C://///`).
root_end_index: usize,
start_index: usize = 0,
end_index: usize = 0,
const Self = @This();
pub const Component = struct {
/// The current component's path name, e.g. 'b'.
/// This will never contain path separators.
name: []const T,
/// The full path up to and including the current component, e.g. '/a/b'
/// This will never contain trailing path separators.
path: []const T,
};
/// After `init`, `next` will return the first component after the root
/// (there is no need to call `first` after `init`).
/// To iterate backwards (from the end of the path to the beginning), call `last`
/// after `init` and then iterate via `previous` calls.
/// For Windows paths, paths are assumed to be in the Win32 namespace.
pub fn init(path: []const T) Self {
const root_len: usize = switch (path_type) {
.posix, .uefi => posix: {
// Root on UEFI and POSIX only differs by the path separator
break :posix if (path.len > 0 and path_type.isSep(T, path[0])) 1 else 0;
},
.windows => windows: {
break :windows parsePathWindows(T, path).root.len;
},
};
// If there are repeated path separators directly after the root,
// keep track of that info so that they don't have to be dealt with when
// iterating components.
var root_end_index = root_len;
for (path[root_len..]) |c| {
if (!path_type.isSep(T, c)) break;
root_end_index += 1;
}
return .{
.path = path,
.root_len = root_len,
.root_end_index = root_end_index,
.start_index = root_end_index,
.end_index = root_end_index,
};
}
/// Returns the root of the path if it is not a relative path, or null otherwise.
/// For POSIX paths, this will be `/`.
/// For Windows paths, this will be something like `C:\`, `\\server\share\`, etc.
/// For UEFI paths, this will be `\`.
pub fn root(self: Self) ?[]const T {
if (self.root_end_index == 0) return null;
return self.path[0..self.root_len];
}
/// Returns the first component (from the beginning of the path).
/// For example, if the path is `/a/b/c` then this will return the `a` component.
/// After calling `first`, `previous` will always return `null`, and `next` will return
/// the component to the right of the one returned by `first`, if any exist.
pub fn first(self: *Self) ?Component {
self.start_index = self.root_end_index;
self.end_index = self.start_index;
while (self.end_index < self.path.len and !path_type.isSep(T, self.path[self.end_index])) {
self.end_index += 1;
}
if (self.end_index == self.start_index) return null;
return .{
.name = self.path[self.start_index..self.end_index],
.path = self.path[0..self.end_index],
};
}
/// Returns the last component (from the end of the path).
/// For example, if the path is `/a/b/c` then this will return the `c` component.
/// After calling `last`, `next` will always return `null`, and `previous` will return
/// the component to the left of the one returned by `last`, if any exist.
pub fn last(self: *Self) ?Component {
self.end_index = self.path.len;
while (true) {
if (self.end_index == self.root_end_index) {
self.start_index = self.end_index;
return null;
}
if (!path_type.isSep(T, self.path[self.end_index - 1])) break;
self.end_index -= 1;
}
self.start_index = self.end_index;
while (true) {
if (self.start_index == self.root_end_index) break;
if (path_type.isSep(T, self.path[self.start_index - 1])) break;
self.start_index -= 1;
}
if (self.start_index == self.end_index) return null;
return .{
.name = self.path[self.start_index..self.end_index],
.path = self.path[0..self.end_index],
};
}
/// Returns the next component (the component to the right of the most recently
/// returned component), or null if no such component exists.
/// For example, if the path is `/a/b/c` and the most recently returned component
/// is `b`, then this will return the `c` component.
pub fn next(self: *Self) ?Component {
const peek_result = self.peekNext() orelse return null;
self.start_index = peek_result.path.len - peek_result.name.len;
self.end_index = peek_result.path.len;
return peek_result;
}
/// Like `next`, but does not modify the iterator state.
pub fn peekNext(self: Self) ?Component {
var start_index = self.end_index;
while (start_index < self.path.len and path_type.isSep(T, self.path[start_index])) {
start_index += 1;
}
var end_index = start_index;
while (end_index < self.path.len and !path_type.isSep(T, self.path[end_index])) {
end_index += 1;
}
if (start_index == end_index) return null;
return .{
.name = self.path[start_index..end_index],
.path = self.path[0..end_index],
};
}
/// Returns the previous component (the component to the left of the most recently
/// returned component), or null if no such component exists.
/// For example, if the path is `/a/b/c` and the most recently returned component
/// is `b`, then this will return the `a` component.
pub fn previous(self: *Self) ?Component {
const peek_result = self.peekPrevious() orelse return null;
self.start_index = peek_result.path.len - peek_result.name.len;
self.end_index = peek_result.path.len;
return peek_result;
}
/// Like `previous`, but does not modify the iterator state.
pub fn peekPrevious(self: Self) ?Component {
var end_index = self.start_index;
while (true) {
if (end_index == self.root_end_index) return null;
if (!path_type.isSep(T, self.path[end_index - 1])) break;
end_index -= 1;
}
var start_index = end_index;
while (true) {
if (start_index == self.root_end_index) break;
if (path_type.isSep(T, self.path[start_index - 1])) break;
start_index -= 1;
}
if (start_index == end_index) return null;
return .{
.name = self.path[start_index..end_index],
.path = self.path[0..end_index],
};
}
};
}