Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/Build/Cache/Path.zig

Source line 1

Fields

root_dir: Cache.Directory
sub_path: []const u8 = ""

The path, relative to the root dir, that this Path represents. Empty string means the root_dir is the path.

std.Build.Cache.Path.access

function

Source line 121

pub fn access(p: Path, io: Io, sub_path: []const u8, flags: Io.Dir.AccessOptions) !void

Parameters

p: Path
io: Io
sub_path: []const u8
flags: Io.Dir.AccessOptions

std.Build.Cache.Path.Allocator

alias

Source line 6

Alias of std.mem.Allocator

std.Build.Cache.Path.assert

alias

Source line 5

Alias of std.debug.assert

std.Build.Cache.Path.atomicFile

function

Source line 106

pub fn atomicFile( p: Path, io: Io, sub_path: []const u8, options: Io.Dir.CreateFileAtomicOptions, buf: *[Io.Dir.max_path_bytes]u8, ) !Io.File.Atomic

Parameters

p: Path
io: Io
sub_path: []const u8
options: Io.Dir.CreateFileAtomicOptions
buf: *[Io.Dir.max_path_bytes]u8

std.Build.Cache.Path.basename

function

Source line 215

pub fn basename(p: Path) []const u8

Parameters

p: Path

std.Build.Cache.Path.Cache

alias

Source line 7

Alias of std.Build.Cache

std.Build.Cache.Path.clone

function

Source line 14

pub fn clone(p: Path, arena: Allocator) Allocator.Error!Path

Parameters

p: Path
arena: Allocator

Errors

OutOfMemory

std.Build.Cache.Path.createDirPath

function

Source line 131

pub fn createDirPath(p: Path, io: Io, sub_path: []const u8) !void

Parameters

p: Path
io: Io
sub_path: []const u8

std.Build.Cache.Path.createDirPathOpen

function

Source line 86

pub fn createDirPathOpen(p: Path, io: Io, sub_path: []const u8, opts: Io.Dir.CreateDirPathOpenOptions) !Io.Dir

Parameters

p: Path
io: Io
sub_path: []const u8
opts: Io.Dir.CreateDirPathOpenOptions

std.Build.Cache.Path.cwd

function

Source line 21

pub fn cwd() Path

std.Build.Cache.Path.dirname

function

Source line 208

pub fn dirname(p: Path) ?Path

Parameters

p: Path

std.Build.Cache.Path.eql

function

Source line 192

pub fn eql(self: Path, other: Path) bool

Parameters

self: Path
other: Path

std.Build.Cache.Path.fmtEscapeChar

function

Source line 164

Deprecated, use double quoted escape to print paths.

pub fn fmtEscapeChar(path: Path) std.fmt.Alt(Path, formatEscapeChar)

Parameters

path: Path

std.Build.Cache.Path.fmtEscapeString

function

Source line 149

pub fn fmtEscapeString(path: Path) std.fmt.Alt(Path, formatEscapeString)

Parameters

path: Path

std.Build.Cache.Path.format

function

Source line 179

pub fn format(self: Path, writer: *Io.Writer) Io.Writer.Error!void

Parameters

self: Path
writer: *Io.Writer

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Build.Cache.Path.formatEscapeChar

function

Source line 169

Deprecated, use double quoted escape to print paths.

pub fn formatEscapeChar(path: Path, writer: *Io.Writer) Io.Writer.Error!void

Parameters

path: Path
writer: *Io.Writer

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Build.Cache.Path.formatEscapeString

function

Source line 153

pub fn formatEscapeString(path: Path, writer: *Io.Writer) Io.Writer.Error!void

Parameters

path: Path
writer: *Io.Writer

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Build.Cache.Path.initCwd

function

Source line 25

pub fn initCwd(sub_path: []const u8) Path

Parameters

sub_path: []const u8

std.Build.Cache.Path.Io

alias

Source line 4

Alias of std.Io

std.Build.Cache.Path.join

function

Source line 29

pub fn join(p: Path, arena: Allocator, sub_path: []const u8) Allocator.Error!Path

Parameters

p: Path
arena: Allocator
sub_path: []const u8

Errors

OutOfMemory

std.Build.Cache.Path.joinString

function

Source line 49

pub fn joinString(p: Path, gpa: Allocator, sub_path: []const u8) Allocator.Error![]u8

Parameters

p: Path
gpa: Allocator
sub_path: []const u8

Errors

OutOfMemory

std.Build.Cache.Path.joinStringZ

function

Source line 55

pub fn joinStringZ(p: Path, gpa: Allocator, sub_path: []const u8) Allocator.Error![:0]u8

Parameters

p: Path
gpa: Allocator
sub_path: []const u8

Errors

OutOfMemory

std.Build.Cache.Path.openDir

function

Source line 71

pub fn openDir( p: Path, io: Io, sub_path: []const u8, args: Io.Dir.OpenOptions, ) Io.Dir.OpenError!Io.Dir

Parameters

p: Path
io: Io
sub_path: []const u8
args: Io.Dir.OpenOptions

Errors

AccessDenied
BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

FileNotFound
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound

On Windows, \\server or \\server\share was not found.

NoDevice
NotDir
PermissionDenied
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Build.Cache.Path.openFile

function

Source line 61

pub fn openFile(p: Path, io: Io, sub_path: []const u8, flags: Io.Dir.OpenFileOptions) !Io.File

Parameters

p: Path
io: Io
sub_path: []const u8
flags: Io.Dir.OpenFileOptions

std.Build.Cache.Path.Path

alias

Source line 1

Alias of std.Build.Cache.Path

std.Build.Cache.Path.resolvePosix

function

Source line 39

pub fn resolvePosix(p: Path, arena: Allocator, sub_path: []const u8) Allocator.Error!Path

Parameters

p: Path
arena: Allocator
sub_path: []const u8

Errors

OutOfMemory

std.Build.Cache.Path.statFile

function

Source line 96

pub fn statFile(p: Path, io: Io, sub_path: []const u8) !Io.Dir.Stat

Parameters

p: Path
io: Io
sub_path: []const u8

std.Build.Cache.Path.std

alias

Source line 3

Alias of std

std.Build.Cache.Path.stem

function

Source line 204

pub fn stem(p: Path) []const u8

Parameters

p: Path

std.Build.Cache.Path.subPathOpt

function

Source line 196

pub fn subPathOpt(self: Path) ?[]const u8

Parameters

self: Path

std.Build.Cache.Path.subPathOrDot

function

Source line 200

pub fn subPathOrDot(self: Path) []const u8

Parameters

self: Path

std.Build.Cache.Path.TableAdapter

namespace

Source line 220

Useful to make Path a key in std.ArrayHashMap.

std.Build.Cache.Path.TableAdapter.eql

function

Source line 232

pub fn eql(self: TableAdapter, a: Cache.Path, b: Cache.Path, b_index: usize) bool

Parameters

self: TableAdapter
a: Cache.Path
b: Cache.Path
b_index: usize

std.Build.Cache.Path.TableAdapter.hash

function

Source line 223

pub fn hash(self: TableAdapter, a: Cache.Path) u32

Parameters

std.Build.Cache.Path.TableAdapter.Hash

alias

Source line 221

Alias of std.hash.Wyhash

std.Build.Cache.Path.toString

function

Source line 141

pub fn toString(p: Path, allocator: Allocator) Allocator.Error![]u8

Parameters

p: Path
allocator: Allocator

Errors

OutOfMemory

std.Build.Cache.Path.toStringZ

function

Source line 145

pub fn toStringZ(p: Path, allocator: Allocator) Allocator.Error![:0]u8

Parameters

p: Path
allocator: Allocator

Errors

OutOfMemory
Source code

std/Build/Cache/Path.zig

const Path = @This();

const std = @import("../../std.zig");
const Io = std.Io;
const assert = std.debug.assert;
const Allocator = std.mem.Allocator;
const Cache = std.Build.Cache;

root_dir: Cache.Directory,
/// The path, relative to the root dir, that this `Path` represents.
/// Empty string means the root_dir is the path.
sub_path: []const u8 = "",

pub fn clone(p: Path, arena: Allocator) Allocator.Error!Path {
    return .{
        .root_dir = try p.root_dir.clone(arena),
        .sub_path = try arena.dupe(u8, p.sub_path),
    };
}

pub fn cwd() Path {
    return initCwd("");
}

pub fn initCwd(sub_path: []const u8) Path {
    return .{ .root_dir = .cwd(), .sub_path = sub_path };
}

pub fn join(p: Path, arena: Allocator, sub_path: []const u8) Allocator.Error!Path {
    if (sub_path.len == 0) return p;
    const parts: []const []const u8 =
        if (p.sub_path.len == 0) &.{sub_path} else &.{ p.sub_path, sub_path };
    return .{
        .root_dir = p.root_dir,
        .sub_path = try Io.Dir.path.join(arena, parts),
    };
}

pub fn resolvePosix(p: Path, arena: Allocator, sub_path: []const u8) Allocator.Error!Path {
    if (sub_path.len == 0) return p;
    const new_sub_path = try Io.Dir.path.resolvePosix(arena, &.{ p.sub_path, sub_path });
    return .{
        .root_dir = p.root_dir,
        // Use "" instead of "." to represent `root_dir` itself.
        .sub_path = if (std.mem.eql(u8, new_sub_path, ".")) "" else new_sub_path,
    };
}

pub fn joinString(p: Path, gpa: Allocator, sub_path: []const u8) Allocator.Error![]u8 {
    const parts: []const []const u8 =
        if (p.sub_path.len == 0) &.{sub_path} else &.{ p.sub_path, sub_path };
    return p.root_dir.join(gpa, parts);
}

pub fn joinStringZ(p: Path, gpa: Allocator, sub_path: []const u8) Allocator.Error![:0]u8 {
    const parts: []const []const u8 =
        if (p.sub_path.len == 0) &.{sub_path} else &.{ p.sub_path, sub_path };
    return p.root_dir.joinZ(gpa, parts);
}

pub fn openFile(p: Path, io: Io, sub_path: []const u8, flags: Io.Dir.OpenFileOptions) !Io.File {
    var buf: [Io.Dir.max_path_bytes]u8 = undefined;
    const joined_path = if (p.sub_path.len == 0) sub_path else p: {
        break :p std.mem.print(&buf, "{s}" ++ Io.Dir.path.sep_str ++ "{s}", .{
            p.sub_path, sub_path,
        }) catch return error.NameTooLong;
    };
    return p.root_dir.handle.openFile(io, joined_path, flags);
}

pub fn openDir(
    p: Path,
    io: Io,
    sub_path: []const u8,
    args: Io.Dir.OpenOptions,
) Io.Dir.OpenError!Io.Dir {
    var buf: [Io.Dir.max_path_bytes]u8 = undefined;
    const joined_path = if (p.sub_path.len == 0) sub_path else p: {
        break :p std.mem.print(&buf, "{s}" ++ Io.Dir.path.sep_str ++ "{s}", .{
            p.sub_path, sub_path,
        }) catch return error.NameTooLong;
    };
    return p.root_dir.handle.openDir(io, joined_path, args);
}

pub fn createDirPathOpen(p: Path, io: Io, sub_path: []const u8, opts: Io.Dir.CreateDirPathOpenOptions) !Io.Dir {
    var buf: [Io.Dir.max_path_bytes]u8 = undefined;
    const joined_path = if (p.sub_path.len == 0) sub_path else p: {
        break :p std.mem.print(&buf, "{s}" ++ Io.Dir.path.sep_str ++ "{s}", .{
            p.sub_path, sub_path,
        }) catch return error.NameTooLong;
    };
    return p.root_dir.handle.createDirPathOpen(io, joined_path, opts);
}

pub fn statFile(p: Path, io: Io, sub_path: []const u8) !Io.Dir.Stat {
    var buf: [Io.Dir.max_path_bytes]u8 = undefined;
    const joined_path = if (p.sub_path.len == 0) sub_path else p: {
        break :p std.mem.print(&buf, "{s}" ++ Io.Dir.path.sep_str ++ "{s}", .{
            p.sub_path, sub_path,
        }) catch return error.NameTooLong;
    };
    return p.root_dir.handle.statFile(io, joined_path, .{});
}

pub fn atomicFile(
    p: Path,
    io: Io,
    sub_path: []const u8,
    options: Io.Dir.CreateFileAtomicOptions,
    buf: *[Io.Dir.max_path_bytes]u8,
) !Io.File.Atomic {
    const joined_path = if (p.sub_path.len == 0) sub_path else p: {
        break :p std.mem.print(buf, "{s}" ++ Io.Dir.path.sep_str ++ "{s}", .{
            p.sub_path, sub_path,
        }) catch return error.NameTooLong;
    };
    return p.root_dir.handle.createFileAtomic(io, joined_path, options);
}

pub fn access(p: Path, io: Io, sub_path: []const u8, flags: Io.Dir.AccessOptions) !void {
    var buf: [Io.Dir.max_path_bytes]u8 = undefined;
    const joined_path = if (p.sub_path.len == 0) sub_path else p: {
        break :p std.mem.print(&buf, "{s}" ++ Io.Dir.path.sep_str ++ "{s}", .{
            p.sub_path, sub_path,
        }) catch return error.NameTooLong;
    };
    return p.root_dir.handle.access(io, joined_path, flags);
}

pub fn createDirPath(p: Path, io: Io, sub_path: []const u8) !void {
    var buf: [Io.Dir.max_path_bytes]u8 = undefined;
    const joined_path = if (p.sub_path.len == 0) sub_path else p: {
        break :p std.mem.print(&buf, "{s}" ++ Io.Dir.path.sep_str ++ "{s}", .{
            p.sub_path, sub_path,
        }) catch return error.NameTooLong;
    };
    return p.root_dir.handle.createDirPath(io, joined_path);
}

pub fn toString(p: Path, allocator: Allocator) Allocator.Error![]u8 {
    return allocator.print("{f}", .{p});
}

pub fn toStringZ(p: Path, allocator: Allocator) Allocator.Error![:0]u8 {
    return allocator.printSentinel("{f}", .{p}, 0);
}

pub fn fmtEscapeString(path: Path) std.fmt.Alt(Path, formatEscapeString) {
    return .{ .data = path };
}

pub fn formatEscapeString(path: Path, writer: *Io.Writer) Io.Writer.Error!void {
    if (path.root_dir.path) |p| {
        try std.zig.stringEscape(p, writer);
        if (path.sub_path.len > 0) try std.zig.stringEscape(Io.Dir.path.sep_str, writer);
    }
    if (path.sub_path.len > 0) {
        try std.zig.stringEscape(path.sub_path, writer);
    }
}

/// Deprecated, use double quoted escape to print paths.
pub fn fmtEscapeChar(path: Path) std.fmt.Alt(Path, formatEscapeChar) {
    return .{ .data = path };
}

/// Deprecated, use double quoted escape to print paths.
pub fn formatEscapeChar(path: Path, writer: *Io.Writer) Io.Writer.Error!void {
    if (path.root_dir.path) |p| {
        for (p) |byte| try std.zig.charEscape(byte, writer);
        if (path.sub_path.len > 0) try writer.writeByte(Io.Dir.path.sep);
    }
    if (path.sub_path.len > 0) {
        for (path.sub_path) |byte| try std.zig.charEscape(byte, writer);
    }
}

pub fn format(self: Path, writer: *Io.Writer) Io.Writer.Error!void {
    if (Io.Dir.path.isAbsolute(self.sub_path)) {
        return writer.writeAll(self.sub_path);
    } else if (self.root_dir.path) |p| {
        var bufs: [3][]const u8 = .{ p, Io.Dir.path.sep_str, self.sub_path };
        return writer.writeVecAll(bufs[0..if (self.sub_path.len > 0) 3 else 1]);
    } else if (self.sub_path.len > 0) {
        return writer.writeAll(self.sub_path);
    } else {
        return writer.writeByte('.');
    }
}

pub fn eql(self: Path, other: Path) bool {
    return self.root_dir.eql(other.root_dir) and std.mem.eql(u8, self.sub_path, other.sub_path);
}

pub fn subPathOpt(self: Path) ?[]const u8 {
    return if (self.sub_path.len == 0) null else self.sub_path;
}

pub fn subPathOrDot(self: Path) []const u8 {
    return if (self.sub_path.len == 0) "." else self.sub_path;
}

pub fn stem(p: Path) []const u8 {
    return Io.Dir.path.stem(p.sub_path);
}

pub fn dirname(p: Path) ?Path {
    return .{
        .root_dir = p.root_dir,
        .sub_path = Io.Dir.path.dirname(p.subPathOpt() orelse return null) orelse "",
    };
}

pub fn basename(p: Path) []const u8 {
    return Io.Dir.path.basename(p.sub_path);
}

/// Useful to make `Path` a key in `std.ArrayHashMap`.
pub const TableAdapter = struct {
    pub const Hash = std.hash.Wyhash;

    pub fn hash(self: TableAdapter, a: Cache.Path) u32 {
        _ = self;
        const seed = switch (@typeInfo(@TypeOf(a.root_dir.handle.handle))) {
            .pointer => @intFromPtr(a.root_dir.handle.handle),
            .int => @as(u32, @bitCast(a.root_dir.handle.handle)),
            else => @compileError("unimplemented hash function"),
        };
        return @truncate(Hash.hash(seed, a.sub_path));
    }
    pub fn eql(self: TableAdapter, a: Cache.Path, b: Cache.Path, b_index: usize) bool {
        _ = self;
        _ = b_index;
        return a.eql(b);
    }
};