项目

const std = @import("std");

/// Tiny, allocator-friendly path utilities for didactic purposes.
/// Note: These do not attempt full platform semantics; they aim to be predictable
/// and portable for teaching. Prefer std.fs.path for production code.
/// 微型、分配器友好的路径工具，用于教学目的。
/// 注意：这些不尝试完整的平台语义；它们旨在为教学提供可预测和可移植性。
/// 生产代码请使用 std.fs.path。
pub const pathutil = struct {
    /// Join parts with exactly one separator between components.
    /// - Collapses duplicate separators at boundaries
    /// - Preserves a leading root (e.g. "/" on POSIX) if the first non-empty part starts with a separator
    /// - Does not resolve dot segments or drive letters
    /// 使用组件之间恰好一个分隔符连接部分。
    /// - 在边界处折叠重复的分隔符
    /// - 如果第一个非空部分以分隔符开头，则保留前导根（例如 POSIX 上的 "/"）
    /// - 不解析点段或驱动器字母
    pub fn joinAlloc(allocator: std.mem.Allocator, parts: []const []const u8) ![]u8 {
        var list: std.ArrayListUnmanaged(u8) = .{};
        defer list.deinit(allocator);

        const sep: u8 = std.fs.path.sep;
        var has_any: bool = false;

        for (parts) |raw| {
            if (raw.len == 0) continue;

            // Trim leading/trailing separators from this component
            // 从此组件中修剪前导/尾随分隔符
            var start: usize = 0;
            var end: usize = raw.len;
            while (start < end and isSep(raw[start])) start += 1;
            while (end > start and isSep(raw[end - 1])) end -= 1;

            const had_leading_sep = start > 0;
            const core = raw[start..end];

            if (!has_any) {
                if (had_leading_sep) {
                    // Preserve absolute root
                    // 保留绝对根
                    try list.append(allocator, sep);
                    has_any = true;
                }
            } else {
                // Ensure exactly one separator between components if we have content already
                // 如果我们已有内容，确保组件之间恰好一个分隔符
                if (list.items.len == 0 or list.items[list.items.len - 1] != sep) {
                    try list.append(allocator, sep);
                }
            }

            if (core.len != 0) {
                try list.appendSlice(allocator, core);
                has_any = true;
            }
        }

        return list.toOwnedSlice(allocator);
    }

    /// Return the last path component. Trailing separators are ignored.
    /// Examples: "a/b/c" -> "c", "/a/b/" -> "b", "/" -> "/", "" -> "".
    /// 返回最后一个路径组件。忽略尾随分隔符。
    /// 示例："a/b/c" -> "c", "/a/b/" -> "b", "/" -> "/", "" -> ""。
    pub fn basename(path: []const u8) []const u8 {
        if (path.len == 0) return path;

        // Skip trailing separators
        // 跳过尾随分隔符
        var end = path.len;
        while (end > 0 and isSep(path[end - 1])) end -= 1;
        if (end == 0) {
            // path was all separators; treat it as root
            // 路径全是分隔符；将其视为根
            return path[0..1];
        }

        // Find previous separator
        // 查找前一个分隔符
        var i: isize = @intCast(end);
        while (i > 0) : (i -= 1) {
            if (isSep(path[@intCast(i - 1)])) break;
        }
        const start: usize = @intCast(i);
        return path[start..end];
    }

    /// Return the directory portion (without trailing separators).
    /// Examples: "a/b/c" -> "a/b", "a" -> ".", "/" -> "/".
    /// 返回目录部分（不带尾随分隔符）。
    /// 示例："a/b/c" -> "a/b", "a" -> ".", "/" -> "/"。
    pub fn dirpath(path: []const u8) []const u8 {
        if (path.len == 0) return ".";

        // Skip trailing separators
        // 跳过尾随分隔符
        var end = path.len;
        while (end > 0 and isSep(path[end - 1])) end -= 1;
        if (end == 0) return path[0..1]; // all separators -> root
        // 所有分隔符 -> 根

        // Find previous separator
        // 查找前一个分隔符
        var i: isize = @intCast(end);
        while (i > 0) : (i -= 1) {
            const ch = path[@intCast(i - 1)];
            if (isSep(ch)) break;
        }
        if (i == 0) return ".";

        // Skip any trailing separators in the dir portion
        // 跳过目录部分中的任何尾随分隔符
        var d_end: usize = @intCast(i);
        while (d_end > 1 and isSep(path[d_end - 1])) d_end -= 1;
        if (d_end == 0) return path[0..1];
        return path[0..d_end];
    }

    /// Return the extension (without dot) of the last component or "" if none.
    /// Examples: "file.txt" -> "txt", "a.tar.gz" -> "gz", ".gitignore" -> "".
    /// 返回最后一个组件的扩展名（不带点），如果没有则返回 ""。
    /// 示例："file.txt" -> "txt", "a.tar.gz" -> "gz", ".gitignore" -> ""。
    pub fn extname(path: []const u8) []const u8 {
        const base = basename(path);
        if (base.len == 0) return base;
        if (base[0] == '.') {
            // Hidden file as first character '.' does not count as extension if there is no other dot
            // 隐藏文件以第一个字符 '.' 开头，如果没有其他点，则不计算为扩展名
            if (std.mem.indexOfScalar(u8, base[1..], '.')) |idx2| {
                const idx = 1 + idx2;
                if (idx + 1 < base.len) return base[(idx + 1)..];
                return "";
            } else return "";
        }
        if (std.mem.lastIndexOfScalar(u8, base, '.')) |idx| {
            if (idx + 1 < base.len) return base[(idx + 1)..];
        }
        return "";
    }

    /// Return a newly-allocated path with the extension replaced by `new_ext` (no dot).
    /// If there is no existing extension, appends one if `new_ext` is non-empty.
    /// 返回一个新分配的路径，其扩展名替换为 `new_ext`（不带点）。
    /// 如果没有现有扩展名，如果 `new_ext` 非空则追加一个。
    pub fn changeExtAlloc(allocator: std.mem.Allocator, path: []const u8, new_ext: []const u8) ![]u8 {
        const base = basename(path);
        const dir = dirpath(path);
        const sep: u8 = std.fs.path.sep;

        var base_core = base;
        if (std.mem.lastIndexOfScalar(u8, base, '.')) |idx| {
            if (!(idx == 0 and base[0] == '.')) {
                base_core = base[0..idx];
            }
        }

        const need_dot = new_ext.len != 0;
        const dir_has = dir.len != 0 and !(dir.len == 1 and dir[0] == '.' and base.len == path.len);
        // Compute length at runtime to avoid comptime_int dependency
        // 在运行时计算长度以避免 comptime_int 依赖
        var new_len: usize = 0;
        if (dir_has) new_len += dir.len + 1;
        new_len += base_core.len;
        if (need_dot) new_len += 1 + new_ext.len;

        var out = try allocator.alloc(u8, new_len);
        errdefer allocator.free(out);

        var w: usize = 0;
        if (dir_has) {
            @memcpy(out[w..][0..dir.len], dir);
            w += dir.len;
            out[w] = sep;
            w += 1;
        }
        @memcpy(out[w..][0..base_core.len], base_core);
        w += base_core.len;
        if (need_dot) {
            out[w] = '.';
            w += 1;
            @memcpy(out[w..][0..new_ext.len], new_ext);
            w += new_ext.len;
        }
        return out;
    }
};

inline fn isSep(ch: u8) bool {
    return ch == std.fs.path.sep or isOtherSep(ch);
}

inline fn isOtherSep(ch: u8) bool {
    // Be forgiving in parsing: treat both '/' and '\\' as separators on any platform
    // but only emit std.fs.path.sep when joining.
    // 在解析中要宽容：在任何平台上都将 '/' 和 '\\' 视为分隔符
    // 但仅在连接时发出 std.fs.path.sep。
    return ch == '/' or ch == '\\';
}

const std = @import("std");
const pathutil = @import("path_util.zig").pathutil;

pub fn main() !void {
    var out_buf: [2048]u8 = undefined;
    var out_writer = std.fs.File.stdout().writer(&out_buf);
    const out = &out_writer.interface;

    // Demonstrate join
    // 演示连接
    const j1 = try pathutil.joinAlloc(std.heap.page_allocator, &.{ "a", "b", "c" });
    defer std.heap.page_allocator.free(j1);
    try out.print("join a,b,c => {s}\n", .{j1});

    const j2 = try pathutil.joinAlloc(std.heap.page_allocator, &.{ "/", "usr/", "/bin" });
    defer std.heap.page_allocator.free(j2);
    try out.print("join /,usr/,/bin => {s}\n", .{j2});

    // Demonstrate basename/dirpath
    // 演示 basename/dirpath
    const p = "/home/user/docs/report.txt";
    try out.print("basename({s}) => {s}\n", .{ p, pathutil.basename(p) });
    try out.print("dirpath({s}) => {s}\n", .{ p, pathutil.dirpath(p) });

    // Extension helpers
    // 扩展名辅助函数
    try out.print("extname({s}) => {s}\n", .{ p, pathutil.extname(p) });
    const changed = try pathutil.changeExtAlloc(std.heap.page_allocator, p, "md");
    defer std.heap.page_allocator.free(changed);
    try out.print("changeExt({s}, md) => {s}\n", .{ p, changed });

    try out.flush();
}

const std = @import("std");
const testing = std.testing;
const pathutil = @import("path_util.zig").pathutil;

// Helper to allocate-join path parts with the testing allocator
// 使用测试分配器分配连接路径部分的辅助函数
fn ajoin(parts: []const []const u8) ![]u8 {
    return try pathutil.joinAlloc(testing.allocator, parts);
}

test "joinAlloc basic and absolute" {
    const p1 = try ajoin(&.{ "a", "b", "c" });
    defer testing.allocator.free(p1);
    try testing.expectEqualStrings("a" ++ [1]u8{std.fs.path.sep} ++ "b" ++ [1]u8{std.fs.path.sep} ++ "c", p1);

    const p2 = try ajoin(&.{ "/", "usr/", "/bin" });
    defer testing.allocator.free(p2);
    try testing.expectEqualStrings("/usr/bin", p2);

    const p3 = try ajoin(&.{ "", "a", "", "b" });
    defer testing.allocator.free(p3);
    try testing.expectEqualStrings("a" ++ [1]u8{std.fs.path.sep} ++ "b", p3);

    const p4 = try ajoin(&.{ "a/", "/b/" });
    defer testing.allocator.free(p4);
    try testing.expectEqualStrings("a" ++ [1]u8{std.fs.path.sep} ++ "b", p4);
}

test "basename and dirpath edges" {
    try testing.expectEqualStrings("c", pathutil.basename("a/b/c"));
    try testing.expectEqualStrings("b", pathutil.basename("/a/b/"));
    try testing.expectEqualStrings("/", pathutil.basename("////"));
    try testing.expectEqualStrings("", pathutil.basename(""));

    try testing.expectEqualStrings("a/b", pathutil.dirpath("a/b/c"));
    try testing.expectEqualStrings(".", pathutil.dirpath("a"));
    try testing.expectEqualStrings("/", pathutil.dirpath("////"));
}

test "extension and changeExtAlloc" {
    try testing.expectEqualStrings("txt", pathutil.extname("file.txt"));
    try testing.expectEqualStrings("gz", pathutil.extname("a.tar.gz"));
    try testing.expectEqualStrings("", pathutil.extname(".gitignore"));
    try testing.expectEqualStrings("", pathutil.extname("noext"));

    const changed1 = try pathutil.changeExtAlloc(testing.allocator, "a/b/file.txt", "md");
    defer testing.allocator.free(changed1);
    try testing.expectEqualStrings("a/b/file.md", changed1);

    const changed2 = try pathutil.changeExtAlloc(testing.allocator, "a/b/file", "md");
    defer testing.allocator.free(changed2);
    try testing.expectEqualStrings("a/b/file.md", changed2);

    const changed3 = try pathutil.changeExtAlloc(testing.allocator, "a/b/.profile", "txt");
    defer testing.allocator.free(changed3);
    try testing.expectEqualStrings("a/b/.profile.txt", changed3);
}

const std = @import("std");
const testing = std.testing;
const pathutil = @import("path_util.zig").pathutil;

test "deliberate leak caught by testing allocator" {
    const joined = try pathutil.joinAlloc(testing.allocator, &.{ "/", "tmp", "demo" });
    // Intentionally forget to free: allocator leak should be detected by the runner
    // 故意忘记释放：分配器泄漏应由运行器检测到
    // defer testing.allocator.free(joined);
    try testing.expect(std.mem.endsWith(u8, joined, "demo"));
}

const std = @import("std");
const testing = std.testing;
const pathutil = @import("path_util.zig").pathutil;

test "fixed: no leak after adding defer free" {
    // 修复后：添加 defer free 后无泄漏
    const joined = try pathutil.joinAlloc(testing.allocator, &.{ "/", "tmp", "demo" });
    defer testing.allocator.free(joined);
    try testing.expect(std.mem.endsWith(u8, joined, "demo"));
}