跳转到内容
标准库Zig 0.17.0官方原文
源码std/std.zig

第 1 行

std.array_hash_map

别名

第 64 行

别名目标 std.array_hash_map

std.array_list

别名

第 55 行

别名目标 std.array_list

std.ArrayHashMapUnmanaged

别名

第 40 行

已弃用;请使用 array_hash_map.Custom。

别名目标 std.array_hash_map.Custom

std.ArrayList

类型函数

第 52 行

内存中连续且可增长的条目列表,是对 T 值切片的封装。

整个生命周期必须使用同一分配器。 直接使用 empty 或 initCapacity 初始化,再使用 deinit 或 toOwnedSlice 反初始化。

pub fn ArrayList(comptime T: type) type

参数

T: type

std.ArrayListAligned

别名

第 58 行

已弃用;请使用 array_list.Aligned。

别名目标 std.array_list.Aligned

std.ArrayListAlignedUnmanaged

别名

第 60 行

已弃用;请使用 array_list.Aligned。

别名目标 std.array_list.Aligned

std.ArrayListUnmanaged

别名

第 62 行

已弃用;请使用 ArrayList。

别名目标 std.ArrayList

std.ascii

别名

第 103 行

别名目标 std.ascii

std.atomic

别名

第 65 行

别名目标 std.atomic

std.AutoArrayHashMapUnmanaged

别名

第 42 行

已弃用;请使用 array_hash_map.Auto。

别名目标 std.array_hash_map.Auto

std.AutoHashMap

别名

第 1 行

别名目标 std.hash_map.AutoHashMap

std.AutoHashMapUnmanaged

别名

第 2 行

别名目标 std.hash_map.AutoHashMapUnmanaged

std.base64

别名

第 66 行

别名目标 std.base64

std.bit_set

别名

第 67 行

别名目标 std.bit_set

std.BitStack

别名

第 3 行

别名目标 std.BitStack

std.BufMap

别名

第 5 行

别名目标 std.buf_map.BufMap

std.BufSet

别名

第 6 行

别名目标 std.buf_set.BufSet

std.Build

别名

第 4 行

别名目标 std.Build

std.builtin

别名

第 71 行

已弃用;请使用 lang。

将在 Zig 0.17.0 之后移除。

别名目标 std.lang

std.c

别名

第 73 行

别名目标 std.c

std.coff

别名

第 74 行

别名目标 std.coff

std.compress

别名

第 75 行

别名目标 std.compress

std.crypto

别名

第 77 行

别名目标 std.crypto

std.debug

别名

第 78 行

别名目标 std.debug

std.Deque

别名

第 9 行

别名目标 std.deque.Deque

std.DoublyLinkedList

别名

第 10 行

别名目标 std.DoublyLinkedList

std.dwarf

别名

第 79 行

别名目标 std.dwarf

std.DynamicBitSet

别名

第 13 行

已弃用:请使用 bit_set.DynamicManaged。

别名目标 std.bit_set.DynamicBitSet

std.DynamicBitSetUnmanaged

别名

第 15 行

已弃用:使用 bit_set.Dynamic。

别名目标 std.bit_set.DynamicBitSetUnmanaged

std.DynLib

别名

第 11 行

别名目标 std.dynamic_library.DynLib

std.elf

别名

第 80 行

别名目标 std.elf

std.EnumArray

别名

第 16 行

别名目标 std.enums.EnumArray

std.EnumMap

别名

第 17 行

别名目标 std.enums.EnumMap

std.enums

别名

第 81 行

别名目标 std.enums

std.EnumSet

别名

第 18 行

别名目标 std.enums.EnumSet

std.fmt

别名

第 82 行

别名目标 std.fmt

std.fs

别名

第 83 行

别名目标 std.fs

std.hash

别名

第 85 行

别名目标 std.hash

std.hash_map

别名

第 86 行

别名目标 std.hash_map

std.HashMap

别名

第 19 行

别名目标 std.hash_map.HashMap

std.HashMapUnmanaged

别名

第 20 行

别名目标 std.hash_map.HashMapUnmanaged

std.heap

别名

第 87 行

别名目标 std.heap

std.http

别名

第 88 行

别名目标 std.http

std.Io

别名

第 21 行

别名目标 std.Io

std.json

别名

第 89 行

别名目标 std.json

std.lang

别名

第 72 行

别名目标 std.lang

std.leb

别名

第 90 行

别名目标 std.leb128

std.log

别名

第 91 行

别名目标 std.log

std.macho

别名

第 92 行

别名目标 std.macho

std.math

别名

第 93 行

别名目标 std.math

std.mem

别名

第 94 行

别名目标 std.mem

std.meta

别名

第 95 行

别名目标 std.meta

std.MultiArrayList

别名

第 22 行

别名目标 std.multi_array_list.MultiArrayList

std.options

常量

第 119 行

编译时已知的设置,可由根源文件覆盖。

Options

std.Options

容器

第 121 行

字段

enable_segfault_handler: bool = debug.default_enable_segfault_handler
signal_stack_size: ?u64 = 1 << 18

若设置,std.start 和 std.Thread 会为每个线程配置指定大小的备用信号栈。 尤其是,若启用 enable_segfault_handler,段错误处理器将 使用该备用栈,因此即使段错误由栈溢出 引起,仍可输出栈跟踪。

在 POSIX 目标上,通过 sigaltstack(2) 配置信号栈。

Windows 上目前忽略此值。

log_level: log.Level = log.default_level

当前日志级别。

log_scope_levels: []const log.ScopeLevel = &.{}
logFn: fn (
    comptime message_level: log.Level,
    comptime scope: @EnumLiteral(),
    comptime format: []const u8,
    args: anytype,
) void = log.defaultLog
page_size_min: ?usize = null

覆盖 std.heap.page_size_min。

page_size_max: ?usize = null

覆盖 std.heap.page_size_max。

queryPageSize: fn () usize = heap.defaultQueryPageSize

覆盖在运行期确定操作系统页大小的默认实现。

fmt_max_depth: usize = fmt.default_max_depth
http_disable_tls: bool = false

默认情况下,std.http.Client 支持 HTTPS 连接。将此选项设为 true 可 禁用 TLS 支持。

这可能减小二进制大小,但也会导致 无法建立 HTTPS 连接。

http_enable_ssl_key_log_file: bool = @import("builtin").mode == .debug

这使 std.http.Client 能够将 SSL 密钥记录到 SSLKEYLOGFILE 环境变量指定的文件中。创建此类日志文件后,其他能够访问该文件的程序 就可以解密此程序产生的全部 std.http.Client 流量。

side_channels_mitigations: crypto.SideChannelsMitigations = crypto.default_side_channels_mitigations
allow_stack_tracing: bool = !@import("builtin").strip_debug_info

是否允许捕获和写出栈追踪。影响以下函数:

剥离调试信息后,通常仍可收集和打印栈追踪,但其用途往往降低,因为通常无法映射到源码位置,或者源码位置不准确。栈追踪逻辑本身也可能相当大,尤其在 ReleaseSmall 中可能不合需要。

若为 false,捕获的栈追踪始终为空;尝试写出栈追踪时,只会向相关 Io.Writer 打印错误并返回。

networking: bool = true

允许禁用 std.Io 实现中的网络功能。

unexpected_error_tracing: bool = @import("builtin").mode == .debug and switch (@import("builtin").zig_backend) {
    .stage2_llvm, .stage2_x86_64 => true,
    else => false,
}

error.Unexpected 是否输出其值及栈跟踪。

若发生此错误,应将错误码加入对应 switch 表达式,必要时在错误集合中引入新错误, 并向 Zig 提交补丁。

std.Options.cwd

常量

第 234 行

覆盖 std.Io.Dir.cwd。

?fn () Io.Dir

std.Options.debug_io

常量

第 228 行

此 Io 实例由 std.debug 用于 std.debug.print、 捕获栈回溯、加载调试信息、查找可执行文件 自身路径,以及访问影响终端模式 检测的环境变量。默认使用静态初始化的单例, 独立于应用的 Io 实例,以便简化 调试。例如,调试基于协程的 Io 实现时,通常希望 std.debug.print 直接写入 stderr,而不尝试与被调试的 代码交互。

Io

std.Options.debug_threaded_io

常量

第 214 行

?*Io.Threaded

std.Options.elf_debug_info_search_paths

常量

第 206 行

TODO: 此项是独立声明而非字段,用于规避 Zig 惰性不足造成的编译错误。

?fn (exe_path: []const u8) switch (@import("builtin").object_format) { .elf => debug.ElfFile.DebugInfoSearchPaths, else => void, }

std.Options.FilePermissions

常量

第 231 行

覆盖 std.Io.File.Permissions。

?type

std.Options.logTerminalMode

别名

第 202 行

TODO: 此项是独立声明而非字段,用于规避 Zig 惰性不足造成的编译错误。

别名目标 std.log.defaultTerminalMode

std.os

别名

第 96 行

别名目标 std.os

std.pdb

别名

第 97 行

别名目标 std.pdb

std.pie

别名

第 98 行

别名目标 std.pie

std.posix

别名

第 99 行

别名目标 std.posix

std.PriorityDequeue

别名

第 24 行

别名目标 std.priority_dequeue.PriorityDequeue

std.PriorityQueue

别名

第 23 行

别名目标 std.priority_queue.PriorityQueue

std.process

别名

第 100 行

别名目标 std.process

std.Progress

别名

第 25 行

别名目标 std.Progress

std.Random

别名

第 26 行

别名目标 std.Random

std.root

常量

第 116 行

std.SemanticVersion

别名

第 27 行

别名目标 std.SemanticVersion

std.simd

别名

第 102 行

别名目标 std.simd

std.SinglyLinkedList

别名

第 28 行

别名目标 std.SinglyLinkedList

std.sort

别名

第 101 行

别名目标 std.sort

std.spirv

别名

第 84 行

别名目标 std.spirv

std.start

别名

第 114 行

别名目标 std.start

std.static_string_map

别名

第 76 行

别名目标 std.static_string_map

std.StaticBitSet

别名

第 30 行

已弃用:使用 bit_set.Static。

别名目标 std.bit_set.StaticBitSet

std.StaticStringMap

别名

第 7 行

别名目标 std.static_string_map.StaticStringMap

std.StaticStringMapWithEql

别名

第 8 行

别名目标 std.static_string_map.StaticStringMapWithEql

std.StringArrayHashMapUnmanaged

别名

第 44 行

已弃用;使用 array_hash_map.String。

别名目标 std.array_hash_map.String

std.StringHashMap

别名

第 31 行

别名目标 std.hash_map.StringHashMap

std.StringHashMapUnmanaged

别名

第 32 行

别名目标 std.hash_map.StringHashMapUnmanaged

std.tar

别名

第 104 行

别名目标 std.tar

std.Target

别名

第 33 行

别名目标 std.Target

std.testing

别名

第 105 行

别名目标 std.testing

std.Thread

别名

第 34 行

别名目标 std.Thread

std.time

别名

第 106 行

别名目标 std.time

std.Treap

别名

第 35 行

别名目标 std.treap.Treap

std.tz

别名

第 107 行

别名目标 std.tz

std.Tz

别名

第 36 行

别名目标 std.tz.Tz

std.unicode

别名

第 108 行

别名目标 std.unicode

std.Uri

别名

第 37 行

别名目标 std.Uri

std.valgrind

别名

第 109 行

别名目标 std.valgrind

std.wasm

别名

第 110 行

别名目标 std.wasm

std.zig

别名

第 111 行

别名目标 std.zig

std.zip

别名

第 112 行

别名目标 std.zip

std.zon

别名

第 113 行

别名目标 std.zon

源码

std/std.zig

pub const AutoHashMap = hash_map.AutoHashMap;
pub const AutoHashMapUnmanaged = hash_map.AutoHashMapUnmanaged;
pub const BitStack = @import("BitStack.zig");
pub const Build = @import("Build.zig");
pub const BufMap = @import("buf_map.zig").BufMap;
pub const BufSet = @import("buf_set.zig").BufSet;
pub const StaticStringMap = static_string_map.StaticStringMap;
pub const StaticStringMapWithEql = static_string_map.StaticStringMapWithEql;
pub const Deque = @import("deque.zig").Deque;
pub const DoublyLinkedList = @import("DoublyLinkedList.zig");
pub const DynLib = @import("dynamic_library.zig").DynLib;
/// 已弃用:请使用 `bit_set.DynamicManaged`。
pub const DynamicBitSet = bit_set.DynamicBitSet;
/// 已弃用:使用 `bit_set.Dynamic`。
pub const DynamicBitSetUnmanaged = bit_set.DynamicBitSetUnmanaged;
pub const EnumArray = enums.EnumArray;
pub const EnumMap = enums.EnumMap;
pub const EnumSet = enums.EnumSet;
pub const HashMap = hash_map.HashMap;
pub const HashMapUnmanaged = hash_map.HashMapUnmanaged;
pub const Io = @import("Io.zig");
pub const MultiArrayList = @import("multi_array_list.zig").MultiArrayList;
pub const PriorityQueue = @import("priority_queue.zig").PriorityQueue;
pub const PriorityDequeue = @import("priority_dequeue.zig").PriorityDequeue;
pub const Progress = @import("Progress.zig");
pub const Random = @import("Random.zig");
pub const SemanticVersion = @import("SemanticVersion.zig");
pub const SinglyLinkedList = @import("SinglyLinkedList.zig");
/// 已弃用:使用 `bit_set.Static`。
pub const StaticBitSet = bit_set.StaticBitSet;
pub const StringHashMap = hash_map.StringHashMap;
pub const StringHashMapUnmanaged = hash_map.StringHashMapUnmanaged;
pub const Target = @import("Target.zig");
pub const Thread = @import("Thread.zig");
pub const Treap = @import("treap.zig").Treap;
pub const Tz = tz.Tz;
pub const Uri = @import("Uri.zig");

/// 已弃用;请使用 `array_hash_map.Custom`。
pub const ArrayHashMapUnmanaged = array_hash_map.Custom;
/// 已弃用;请使用 `array_hash_map.Auto`。
pub const AutoArrayHashMapUnmanaged = array_hash_map.Auto;
/// 已弃用;使用 `array_hash_map.String`。
pub const StringArrayHashMapUnmanaged = array_hash_map.String;

/// 内存中连续且可增长的条目列表,是对
/// `T` 值切片的封装。
///
/// 整个生命周期必须使用同一分配器。
/// 直接使用 `empty` 或 `initCapacity` 初始化,再使用 `deinit` 或
/// `toOwnedSlice` 反初始化。
pub fn ArrayList(comptime T: type) type {
    return array_list.Aligned(T, null);
}
pub const array_list = @import("array_list.zig");

/// 已弃用;请使用 `array_list.Aligned`。
pub const ArrayListAligned = array_list.Aligned;
/// 已弃用;请使用 `array_list.Aligned`。
pub const ArrayListAlignedUnmanaged = array_list.Aligned;
/// 已弃用;请使用 `ArrayList`。
pub const ArrayListUnmanaged = ArrayList;

pub const array_hash_map = @import("array_hash_map.zig");
pub const atomic = @import("atomic.zig");
pub const base64 = @import("base64.zig");
pub const bit_set = @import("bit_set.zig");
/// 已弃用;请使用 `lang`。
///
/// 将在 Zig 0.17.0 之后移除。
pub const builtin = lang;
pub const lang = @import("lang.zig");
pub const c = @import("c.zig");
pub const coff = @import("coff.zig");
pub const compress = @import("compress.zig");
pub const static_string_map = @import("static_string_map.zig");
pub const crypto = @import("crypto.zig");
pub const debug = @import("debug.zig");
pub const dwarf = @import("dwarf.zig");
pub const elf = @import("elf.zig");
pub const enums = @import("enums.zig");
pub const fmt = @import("fmt.zig");
pub const fs = @import("fs.zig");
pub const spirv = @import("spirv.zig");
pub const hash = @import("hash.zig");
pub const hash_map = @import("hash_map.zig");
pub const heap = @import("heap.zig");
pub const http = @import("http.zig");
pub const json = @import("json.zig");
pub const leb = @import("leb128.zig");
pub const log = @import("log.zig");
pub const macho = @import("macho.zig");
pub const math = @import("math.zig");
pub const mem = @import("mem.zig");
pub const meta = @import("meta.zig");
pub const os = @import("os.zig");
pub const pdb = @import("pdb.zig");
pub const pie = @import("pie.zig");
pub const posix = @import("posix.zig");
pub const process = @import("process.zig");
pub const sort = @import("sort.zig");
pub const simd = @import("simd.zig");
pub const ascii = @import("ascii.zig");
pub const tar = @import("tar.zig");
pub const testing = @import("testing.zig");
pub const time = @import("time.zig");
pub const tz = @import("tz.zig");
pub const unicode = @import("unicode.zig");
pub const valgrind = @import("valgrind.zig");
pub const wasm = @import("wasm.zig");
pub const zig = @import("zig.zig");
pub const zip = @import("zip.zig");
pub const zon = @import("zon.zig");
pub const start = @import("start.zig");

const root = @import("root");

/// 编译时已知的设置,可由根源文件覆盖。
pub const options: Options = if (@hasDecl(root, "std_options")) root.std_options else .{};

pub const Options = struct {
    enable_segfault_handler: bool = debug.default_enable_segfault_handler,

    /// 若设置,`std.start` 和 `std.Thread` 会为每个线程配置指定大小的备用信号栈。
    /// 尤其是,若启用 `enable_segfault_handler`,段错误处理器将
    /// 使用该备用栈,因此即使段错误由栈溢出
    /// 引起,仍可输出栈跟踪。
    ///
    /// 在 POSIX 目标上,通过 sigaltstack(2) 配置信号栈。
    ///
    /// Windows 上目前忽略此值。
    signal_stack_size: ?u64 = 1 << 18, // 对于自托管 x86_64 后端,已观察到 1<<17 足以进行栈追踪

    /// 当前日志级别。
    log_level: log.Level = log.default_level,

    log_scope_levels: []const log.ScopeLevel = &.{},

    logFn: fn (
        comptime message_level: log.Level,
        comptime scope: @EnumLiteral(),
        comptime format: []const u8,
        args: anytype,
    ) void = log.defaultLog,

    /// 覆盖 `std.heap.page_size_min`。
    page_size_min: ?usize = null,
    /// 覆盖 `std.heap.page_size_max`。
    page_size_max: ?usize = null,
    /// 覆盖在运行期确定操作系统页大小的默认实现。
    queryPageSize: fn () usize = heap.defaultQueryPageSize,

    fmt_max_depth: usize = fmt.default_max_depth,

    /// 默认情况下,std.http.Client 支持 HTTPS 连接。将此选项设为 `true` 可
    /// 禁用 TLS 支持。
    ///
    /// 这可能减小二进制大小,但也会导致
    /// 无法建立 HTTPS 连接。
    http_disable_tls: bool = false,

    /// 这使 `std.http.Client` 能够将 SSL 密钥记录到 SSLKEYLOGFILE
    /// 环境变量指定的文件中。创建此类日志文件后,其他能够访问该文件的程序
    /// 就可以解密此程序产生的全部 `std.http.Client` 流量。
    http_enable_ssl_key_log_file: bool = @import("builtin").mode == .debug,

    side_channels_mitigations: crypto.SideChannelsMitigations = crypto.default_side_channels_mitigations,

    /// 是否允许捕获和写出栈追踪。影响以下函数:
    /// * `debug.captureCurrentStackTrace`
    /// * `debug.writeCurrentStackTrace`
    /// * `debug.dumpCurrentStackTrace`
    /// * `debug.writeStackTrace`
    /// * `debug.dumpStackTrace`
    /// * `debug.writeErrorReturnTrace`
    /// * `debug.dumpErrorReturnTrace`
    ///
    /// 剥离调试信息后,通常仍可收集和打印栈追踪,但其用途往往降低,因为通常无法映射到源码位置,或者源码位置不准确。栈追踪逻辑本身也可能相当大,尤其在 ReleaseSmall 中可能不合需要。
    ///
    /// 若为 `false`,捕获的栈追踪始终为空;尝试写出栈追踪时,只会向相关 `Io.Writer` 打印错误并返回。
    ///
    ///
    ///
    ///
    allow_stack_tracing: bool = !@import("builtin").strip_debug_info,

    /// 允许禁用 std.Io 实现中的网络功能。
    networking: bool = true,

    /// `error.Unexpected` 是否输出其值及栈跟踪。
    ///
    /// 若发生此错误,应将错误码加入对应
    /// switch 表达式,必要时在错误集合中引入新错误,
    /// 并向 Zig 提交补丁。
    unexpected_error_tracing: bool = @import("builtin").mode == .debug and switch (@import("builtin").zig_backend) {
        .stage2_llvm, .stage2_x86_64 => true,
        else => false,
    },

    /// TODO: 此项是独立声明而非字段,用于规避 Zig 惰性不足造成的编译错误。
    ///
    pub const logTerminalMode: fn () Io.Terminal.Mode = log.defaultTerminalMode;

    /// TODO: 此项是独立声明而非字段,用于规避 Zig 惰性不足造成的编译错误。
    ///
    pub const elf_debug_info_search_paths: ?fn (exe_path: []const u8) switch (@import("builtin").object_format) {
        .elf => debug.ElfFile.DebugInfoSearchPaths,
        else => void,
    } = if (@hasDecl(root, "std_options_elf_debug_info_search_paths"))
        root.std_options_elf_debug_info_search_paths
    else
        null;

    pub const debug_threaded_io: ?*Io.Threaded = if (@hasDecl(root, "std_options_debug_threaded_io"))
        root.std_options_debug_threaded_io
    else
        Io.Threaded.global_single_threaded;

    /// 此 `Io` 实例由 `std.debug` 用于 `std.debug.print`、
    /// 捕获栈回溯、加载调试信息、查找可执行文件
    /// 自身路径,以及访问影响终端模式
    /// 检测的环境变量。默认使用静态初始化的单例,
    /// 独立于应用的 `Io` 实例,以便简化
    /// 调试。例如,调试基于协程的 `Io`
    /// 实现时,通常希望 `std.debug.print`
    /// 直接写入 stderr,而不尝试与被调试的
    /// 代码交互。
    pub const debug_io: Io = if (@hasDecl(root, "std_options_debug_io")) root.std_options_debug_io else debug_threaded_io.?.io();

    /// 覆盖 `std.Io.File.Permissions`。
    pub const FilePermissions: ?type = if (@hasDecl(root, "std_options_FilePermissions")) root.std_options_FilePermissions else null;

    /// 覆盖 `std.Io.Dir.cwd`。
    pub const cwd: ?fn () Io.Dir = if (@hasDecl(root, "std_options_cwd")) root.std_options_cwd else null;
};

// 强制导入 start.zig 文件;该文件中的编译期逻辑决定
// 是否导出适当的启动符号,并调用 main。
comptime {
    _ = start;
}

test {
    testing.refAllDecls(@This());
}

comptime {
    debug.assert(@import("std") == @This()); // 标准库测试需要 --zig-lib-dir
}