跳转到内容

std.process.Environ

标准库Zig 0.17.0官方原文
源码std/process/Environ.zig

第 1 行

字段

block: Block

操作系统提供的未经修改、未经处理的数据。

std.process.Environ.Allocator

别名

第 7 行

别名目标 std.mem.Allocator

std.process.Environ.assert

别名

第 8 行

别名目标 std.debug.assert

std.process.Environ.Block

类型

第 25 行

在未链接 libc 的 WASI 上,此类型为 void,因为必须 在运行时查询环境并进行堆分配。

Windows 上,环境被修改时 PEB 所指的内存 会变化,因此不能使用长期存活的指针。所以此 操作系统上也使用 void。

std.process.Environ.builtin

常量

第 3 行

std.process.Environ.contains

函数

第 564 行

Windows 上,若 key 不是有效的 WTF-8, 则返回 error.InvalidWtf8。

另见:

pub fn contains(environ: Environ, gpa: Allocator, key: []const u8) ContainsError!bool

参数

environ: Environ
gpa: Allocator
key: []const u8

错误

InvalidWtf8

Windows 上,用户提供的环境变量键必须是 有效的 WTF-8。若静态已知键有效, 则此错误不可达。

OutOfMemory
Unexpected

仅限 WASI。environ_sizes_get 或 environ_get 因 意外原因失败。

std.process.Environ.containsConstant

函数

第 595 行

在不链接 libc 的 WASI 上,由于需要分配内存,此函数不可用。

Windows 上,key 必须为有效的 WTF-8。

另见:

pub inline fn containsConstant(environ: Environ, comptime key: []const u8) bool

参数

environ: Environ
key: []const u8

std.process.Environ.ContainsError

错误集合

第 546 行

错误

InvalidWtf8

Windows 上,用户提供的环境变量键必须是 有效的 WTF-8。若静态已知键有效, 则此错误不可达。

OutOfMemory
Unexpected

仅限 WASI。environ_sizes_get 或 environ_get 因 意外原因失败。

std.process.Environ.containsUnempty

函数

第 578 行

在 Windows 上,若 key 不是有效的 WTF-8, 则返回 error.InvalidWtf8。

另见:

pub fn containsUnempty(environ: Environ, gpa: Allocator, key: []const u8) ContainsError!bool

参数

environ: Environ
gpa: Allocator
key: []const u8

错误

InvalidWtf8

Windows 上,用户提供的环境变量键必须是 有效的 WTF-8。若静态已知键有效, 则此错误不可达。

OutOfMemory
Unexpected

仅限 WASI。environ_sizes_get 或 environ_get 因 意外原因失败。

std.process.Environ.containsUnemptyConstant

函数

第 613 行

由于需要内存分配,此函数在未链接 libc 的 WASI 上 不可用。

Windows 上,key 必须是有效的 WTF-8。

另请参见:

pub inline fn containsUnemptyConstant(environ: Environ, comptime key: []const u8) bool

参数

environ: Environ
key: []const u8

std.process.Environ.createMap

函数

第 506 行

分配 Map,并将环境块复制到其中。

pub fn createMap(env: Environ, allocator: Allocator) CreateMapError!Map

参数

env: Environ
allocator: Allocator

错误

OutOfMemory
Unexpected

仅限 WASI。environ_sizes_get 或 environ_get 因 未预料且未记录的原因失败。

std.process.Environ.CreateMapError

错误集合

第 498 行

错误

OutOfMemory
Unexpected

仅限 WASI。environ_sizes_get 或 environ_get 因 未预料且未记录的原因失败。

std.process.Environ.createPosixBlock

函数

第 730 行

将另一种环境变量块转换为 POSIX 所需格式的 空字符分隔环境变量块。

pub fn createPosixBlock( existing: Environ, gpa: Allocator, options: CreatePosixBlockOptions, ) Allocator.Error!PosixBlock

参数

existing: Environ
gpa: Allocator
options: CreatePosixBlockOptions

错误

OutOfMemory

std.process.Environ.CreatePosixBlockOptions

容器

第 721 行

字段

zig_progress_fd: ?i32 = null

null 表示保持 ZIG_PROGRESS 环境变量不变。 若非 null,负值表示移除该环境变量,>= 0 则表示将其设为给定整数。

std.process.Environ.createWindowsBlock

函数

第 798 行

将另一种环境变量块转换为 POSIX 所需格式的 空字符分隔环境变量块。

pub fn createWindowsBlock( existing: Environ, gpa: Allocator, options: CreateWindowsBlockOptions, ) Allocator.Error!WindowsBlock

参数

existing: Environ
gpa: Allocator
options: CreateWindowsBlockOptions

错误

OutOfMemory

std.process.Environ.CreateWindowsBlockOptions

容器

第 789 行

字段

zig_progress_handle: ?std.os.windows.HANDLE = null

null 表示保持 ZIG_PROGRESS 环境变量不变。 若非 null,std.os.windows.INVALID_HANDLE_VALUE 表示移除 环境变量;否则将给定句柄作为整数赋给该变量。

std.process.Environ.empty

常量

第 17 行

Environ

std.process.Environ.Environ

别名

第 1 行

别名目标 std.process.Environ

std.process.Environ.getAlloc

函数

第 713 行

调用方拥有返回的内存。

Windows 上:

  • 如果 key 不是有效的 WTF-8,则 返回 error.InvalidWtf8。
  • 返回值编码为 WTF-8。

其他平台上,值是不规定编码的 不透明字节序列。

另请参见:

pub fn getAlloc(environ: Environ, gpa: Allocator, key: []const u8) GetAllocError![]u8

参数

environ: Environ
gpa: Allocator
key: []const u8

错误

EnvironmentVariableMissing
InvalidWtf8

Windows 上,用户提供的环境变量键必须是 有效的 WTF-8。若静态已知键有效, 则此错误不可达。

OutOfMemory

std.process.Environ.GetAllocError

错误集合

第 692 行

错误

EnvironmentVariableMissing
InvalidWtf8

Windows 上,用户提供的环境变量键必须是 有效的 WTF-8。若静态已知键有效, 则此错误不可达。

OutOfMemory

std.process.Environ.getPosix

函数

第 630 行

由于需要分配内存,在不使用 libc 的 WASI 上,此函数不可用。

另见:

pub fn getPosix(environ: Environ, key: []const u8) ?[:0]const u8

参数

environ: Environ
key: []const u8

std.process.Environ.getWindows

函数

第 655 行

仅适用于 Windows。获取名称以空终止、采用 WTF-16 编码的环境变量。

此函数使用 RtlEqualUnicodeString 执行 识别 Unicode 的不区分大小写查找。

另见:

pub fn getWindows(environ: Environ, key: [*:0]const u16) ?[:0]const u16

参数

environ: Environ
key: [*:0]const u16

std.process.Environ.GlobalBlock

容器

第 35 行

字段

use_global: bool

std.process.Environ.GlobalBlock.deinit

函数

第 41 行

pub fn deinit(_: GlobalBlock, _: Allocator) void

参数

std.process.Environ.GlobalBlock.empty

常量

第 38 行

GlobalBlock

std.process.Environ.GlobalBlock.global

常量

第 39 行

GlobalBlock

std.process.Environ.GlobalBlock.isEmpty

函数

第 43 行

pub fn isEmpty(block: GlobalBlock) bool

参数

block: GlobalBlock

std.process.Environ.Map

容器

第 100 行

每个键和值都独立分配,并由此数据结构拥有。

字段

array_hash_map: ArrayHashMap
allocator: Allocator

std.process.Environ.Map.ArrayHashMap

类型

第 104 行

std.process.Environ.Map.clearRetainingCapacity

函数

第 370 行

将长度设为零,释放所有键和值的内存,但不释放 条目所分配的内存。

pub fn clearRetainingCapacity(m: *Map) void

参数

m: *Map

std.process.Environ.Map.clone

函数

第 343 行

返回使用 gpa 分配的 em 的完整副本; 它不一定与分配 em 时使用的分配器相同。

pub fn clone(m: *const Map, gpa: Allocator) Allocator.Error!Map

参数

m: *const Map
gpa: Allocator

错误

OutOfMemory

std.process.Environ.Map.contains

函数

第 292 行

在 Windows 上,断言 key 为有效的 WTF-8。

pub fn contains(m: *const Map, key: []const u8) bool

参数

m: *const Map
key: []const u8

std.process.Environ.Map.count

函数

第 332 行

返回映射中存储的键值对数量。

pub fn count(self: Map) Size

参数

self: Map

std.process.Environ.Map.createPosixBlock

函数

第 381 行

根据哈希映射和选项,创建符合 POSIX 预期格式的空字符分隔环境变量块。

pub fn createPosixBlock( map: *const Map, gpa: Allocator, options: CreatePosixBlockOptions, ) Allocator.Error!PosixBlock

参数

map: *const Map
gpa: Allocator
options: CreatePosixBlockOptions

错误

OutOfMemory

std.process.Environ.Map.createWindowsBlock

函数

第 441 行

调用者拥有结果。

pub fn createWindowsBlock( map: *const Map, gpa: Allocator, options: CreateWindowsBlockOptions, ) error{ OutOfMemory, InvalidWtf8 }!WindowsBlock

参数

map: *const Map
gpa: Allocator
options: CreateWindowsBlockOptions

错误

InvalidWtf8
OutOfMemory

std.process.Environ.Map.deinit

函数

第 169 行

释放映射的后备存储,以及所有已存储的键和值。

pub fn deinit(self: *Map) void

参数

self: *Map

std.process.Environ.Map.EnvNameHashContext

命名空间

第 108 行

std.process.Environ.Map.EnvNameHashContext.eql

函数

第 132 行

pub fn eql(self: @This(), a: []const u8, b: []const u8, b_index: usize) bool

参数

self: @This()
a: []const u8
b: []const u8
b_index: usize

std.process.Environ.Map.EnvNameHashContext.hash

函数

第 109 行

pub fn hash(self: @This(), s: []const u8) u32

参数

self: @This()
s: []const u8

std.process.Environ.Map.eqlKeys

函数

第 138 行

fn eqlKeys(a: []const u8, b: []const u8) bool

参数

a: []const u8
b: []const u8

std.process.Environ.Map.get

函数

第 286 行

返回映射中与某键关联的值的副本。 若从映射移除此键, 返回的字符串即失效。 在 Windows 上,断言 key 是有效 WTF-8。

pub fn get(self: Map, key: []const u8) ?[]const u8

参数

self: Map
key: []const u8

std.process.Environ.Map.getPtr

函数

第 277 行

查找与键关联的值的地址。 映射调整大小时,返回的指针失效。 Windows 上,断言 key 为有效的 WTF-8。

pub fn getPtr(self: Map, key: []const u8) ?*[]const u8

参数

self: Map
key: []const u8

std.process.Environ.Map.init

函数

第 163 行

创建由指定分配器支持的 Map。 该分配器用于底层分配 及字符串去重。

pub fn init(allocator: Allocator) Map

参数

allocator: Allocator

std.process.Environ.Map.iterator

函数

第 337 行

返回遍历映射条目的迭代器。

pub fn iterator(self: *const Map) ArrayHashMap.Iterator

参数

self: *const Map

std.process.Environ.Map.keys

函数

第 177 行

pub fn keys(map: *const Map) [][]const u8

参数

map: *const Map

std.process.Environ.Map.orderedRemove

函数

第 322 行

若存在键匹配的条目,则从映射中删除。 通过将后续所有元素前移,从底层数组移除此条目,从而保持现有顺序。

移除条目时返回 true,否则返回 false。

这会使 get() 针对此键返回的值失效。 Windows 上,断言 key 是有效 WTF-8。

pub fn orderedRemove(self: *Map, key: []const u8) bool

参数

self: *Map
key: []const u8

std.process.Environ.Map.put

函数

第 257 行

将 key 和 value 复制到映射中。

断言 key 有效:

  • 不能包含 NUL('\x00') 字节。
  • 长度必须大于 0。
  • 不能包含 =,但 Windows 上允许仅第一个码点为 =。
  • Windows 上必须是有效的 WTF-8。
pub fn put(self: *Map, key: []const u8, value: []const u8) Allocator.Error!void

参数

self: *Map
key: []const u8
value: []const u8

错误

OutOfMemory

std.process.Environ.Map.putAll

函数

第 354 行

将 other 中的所有键值对添加到此 m。

pub fn putAll(m: *Map, other: *const Map) Allocator.Error!void

参数

m: *Map
other: *const Map

错误

OutOfMemory

std.process.Environ.Map.putMove

函数

第 238 行

与 put 相同,但键和值的所有权转移给 Map, 而不是复制。 若 putMove 失败,键和值的所有权不转移。

断言 key 有效:

  • 不得包含 NUL('\x00') 字节。
  • 长度必须 > 0。
  • 不得包含 =,但 Windows 上允许第一个代码点为 =。
  • Windows 上必须为有效的 WTF-8。
pub fn putMove(self: *Map, key: []u8, value: []u8) Allocator.Error!void

参数

self: *Map
key: []u8
value: []u8

错误

OutOfMemory

std.process.Environ.Map.putPosixBlock

函数

第 185 行

pub fn putPosixBlock(map: *Map, view: PosixBlock.View) Allocator.Error!void

参数

map: *Map
view: PosixBlock.View

错误

OutOfMemory

std.process.Environ.Map.putWindowsBlock

函数

第 199 行

pub fn putWindowsBlock(map: *Map, view: WindowsBlock.View) Allocator.Error!void

参数

map: *Map
view: WindowsBlock.View

错误

OutOfMemory

std.process.Environ.Map.Size

类型

第 106 行

std.process.Environ.Map.swapRemove

函数

第 305 行

若存在键匹配的条目,则从哈希映射删除。 通过与最后一个元素交换,从底层数组移除此条目。

移除条目时返回 true,否则返回 false。

这会使 get() 针对此键返回的值失效。 Windows 上,断言 key 是有效 WTF-8。

pub fn swapRemove(self: *Map, key: []const u8) bool

参数

self: *Map
key: []const u8

std.process.Environ.Map.validateKeyForFetch

函数

第 155 行

pub fn validateKeyForFetch(key: []const u8) bool

参数

key: []const u8

std.process.Environ.Map.validateKeyForPut

函数

第 145 行

pub fn validateKeyForPut(key: []const u8) bool

参数

key: []const u8

std.process.Environ.Map.values

函数

第 181 行

pub fn values(map: *const Map) [][]const u8

参数

map: *const Map

std.process.Environ.mem

别名

第 12 行

别名目标 std.mem

std.process.Environ.native_os

常量

第 4 行

std.process.Environ.posix

别名

第 11 行

别名目标 std.posix

std.process.Environ.PosixBlock

容器

第 48 行

字段

slice: [:null]const ?[*:0]const u8

std.process.Environ.PosixBlock.deinit

函数

第 53 行

pub fn deinit(block: PosixBlock, gpa: Allocator) void

参数

block: PosixBlock
gpa: Allocator

std.process.Environ.PosixBlock.empty

常量

第 51 行

PosixBlock

std.process.Environ.PosixBlock.isEmpty

函数

第 58 行

pub fn isEmpty(block: PosixBlock) bool

参数

block: PosixBlock

std.process.Environ.PosixBlock.view

函数

第 69 行

pub fn view(block: PosixBlock) View

参数

block: PosixBlock

std.process.Environ.PosixBlock.View

容器

第 62 行

字段

slice: []const [*:0]const u8

std.process.Environ.PosixBlock.View.isEmpty

函数

第 65 行

pub fn isEmpty(v: View) bool

参数

v: View

std.process.Environ.std

别名

第 6 行

别名目标 std

std.process.Environ.testing

别名

第 9 行

别名目标 std.testing

std.process.Environ.unicode

别名

第 10 行

别名目标 std.unicode

std.process.Environ.WindowsBlock

容器

第 74 行

字段

slice: [:0]const u16

std.process.Environ.WindowsBlock.deinit

函数

第 79 行

pub fn deinit(block: WindowsBlock, gpa: Allocator) void

参数

block: WindowsBlock
gpa: Allocator

std.process.Environ.WindowsBlock.empty

常量

第 77 行

WindowsBlock

std.process.Environ.WindowsBlock.isEmpty

函数

第 83 行

pub fn isEmpty(block: WindowsBlock) bool

参数

block: WindowsBlock

std.process.Environ.WindowsBlock.view

函数

第 94 行

pub fn view(block: WindowsBlock) View

参数

block: WindowsBlock

std.process.Environ.WindowsBlock.View

容器

第 87 行

字段

ptr: [*:0]const u16

std.process.Environ.WindowsBlock.View.isEmpty

函数

第 90 行

pub fn isEmpty(v: View) bool

参数

v: View
源码

std/process/Environ.zig

const Environ = @This();

const builtin = @import("builtin");
const native_os = builtin.os.tag;

const std = @import("../std.zig");
const Allocator = mem.Allocator;
const assert = std.debug.assert;
const testing = std.testing;
const unicode = std.unicode;
const posix = std.posix;
const mem = std.mem;

/// 操作系统提供的未经修改、未经处理的数据。
block: Block,

pub const empty: Environ = .{ .block = .empty };

/// 在未链接 libc 的 WASI 上,此类型为 `void`,因为必须
/// 在运行时查询环境并进行堆分配。
///
/// Windows 上,环境被修改时 PEB 所指的内存
/// 会变化,因此不能使用长期存活的指针。所以此
/// 操作系统上也使用 `void`。
pub const Block = switch (native_os) {
    .windows => GlobalBlock,
    .wasi, .emscripten => switch (builtin.link_libc) {
        false => GlobalBlock,
        true => PosixBlock,
    },
    .freestanding, .other => GlobalBlock,
    else => PosixBlock,
};

pub const GlobalBlock = struct {
    use_global: bool,

    pub const empty: GlobalBlock = .{ .use_global = false };
    pub const global: GlobalBlock = .{ .use_global = true };

    pub fn deinit(_: GlobalBlock, _: Allocator) void {}

    pub fn isEmpty(block: GlobalBlock) bool {
        return !block.use_global;
    }
};

pub const PosixBlock = struct {
    slice: [:null]const ?[*:0]const u8,

    pub const empty: PosixBlock = .{ .slice = &.{} };

    pub fn deinit(block: PosixBlock, gpa: Allocator) void {
        for (block.slice) |entry| gpa.free(mem.span(entry.?));
        gpa.free(block.slice);
    }

    pub fn isEmpty(block: PosixBlock) bool {
        return block.slice.len == 0;
    }

    pub const View = struct {
        slice: []const [*:0]const u8,

        pub fn isEmpty(v: View) bool {
            return v.slice.len == 0;
        }
    };
    pub fn view(block: PosixBlock) View {
        return .{ .slice = @ptrCast(block.slice) };
    }
};

pub const WindowsBlock = struct {
    slice: [:0]const u16,

    pub const empty: WindowsBlock = .{ .slice = &.{0} };

    pub fn deinit(block: WindowsBlock, gpa: Allocator) void {
        gpa.free(block.slice);
    }

    pub fn isEmpty(block: WindowsBlock) bool {
        return block.slice[0] == 0;
    }

    pub const View = struct {
        ptr: [*:0]const u16,

        pub fn isEmpty(v: View) bool {
            return v.ptr[0] == 0;
        }
    };
    pub fn view(block: WindowsBlock) View {
        return .{ .ptr = block.slice.ptr };
    }
};

/// 每个键和值都独立分配,并由此数据结构拥有。
pub const Map = struct {
    array_hash_map: ArrayHashMap,
    allocator: Allocator,

    const ArrayHashMap = std.array_hash_map.Custom([]const u8, []const u8, EnvNameHashContext, false);

    pub const Size = usize;

    pub const EnvNameHashContext = struct {
        pub fn hash(self: @This(), s: []const u8) u32 {
            _ = self;
            switch (native_os) {
                else => return std.array_hash_map.hashString(s),
                .windows => {
                    var h = std.hash.Wyhash.init(0);
                    var it = unicode.Wtf8View.initUnchecked(s).iterator();
                    while (it.nextCodepoint()) |cp| {
                        const cp_upper = if (std.math.cast(u16, cp)) |wtf16|
                            std.os.windows.toUpperWtf16(wtf16)
                        else
                            cp;
                        h.update(&[_]u8{
                            @truncate(cp_upper >> 0),
                            @truncate(cp_upper >> 8),
                            @truncate(cp_upper >> 16),
                        });
                    }
                    return @truncate(h.final());
                },
            }
        }

        pub fn eql(self: @This(), a: []const u8, b: []const u8, b_index: usize) bool {
            _ = self;
            _ = b_index;
            return eqlKeys(a, b);
        }
    };
    fn eqlKeys(a: []const u8, b: []const u8) bool {
        return switch (native_os) {
            else => std.array_hash_map.eqlString(a, b),
            .windows => std.os.windows.eqlIgnoreCaseWtf8(a, b),
        };
    }

    pub fn validateKeyForPut(key: []const u8) bool {
        switch (native_os) {
            else => return key.len > 0 and mem.findAny(u8, key, &.{ 0, '=' }) == null,
            .windows => {
                if (!unicode.wtf8ValidateSlice(key)) return false;
                return key.len > 0 and key[0] != 0 and mem.findAnyPos(u8, key, 1, &.{ 0, '=' }) == null;
            },
        }
    }

    pub fn validateKeyForFetch(key: []const u8) bool {
        if (native_os == .windows and !unicode.wtf8ValidateSlice(key)) return false;
        return true;
    }

    /// 创建由指定分配器支持的 Map。
    /// 该分配器用于底层分配
    /// 及字符串去重。
    pub fn init(allocator: Allocator) Map {
        return .{ .array_hash_map = .empty, .allocator = allocator };
    }

    /// 释放映射的后备存储,以及所有已存储的键和值。
    ///
    pub fn deinit(self: *Map) void {
        const gpa = self.allocator;
        for (self.keys()) |key| gpa.free(key);
        for (self.values()) |value| gpa.free(value);
        self.array_hash_map.deinit(gpa);
        self.* = undefined;
    }

    pub fn keys(map: *const Map) [][]const u8 {
        return map.array_hash_map.keys();
    }

    pub fn values(map: *const Map) [][]const u8 {
        return map.array_hash_map.values();
    }

    pub fn putPosixBlock(map: *Map, view: PosixBlock.View) Allocator.Error!void {
        for (view.slice) |entry| {
            var entry_i: usize = 0;
            while (entry[entry_i] != 0 and entry[entry_i] != '=') : (entry_i += 1) {}
            const key = entry[0..entry_i];

            var end_i: usize = entry_i;
            while (entry[end_i] != 0) : (end_i += 1) {}
            const value = entry[entry_i + 1 .. end_i];

            try map.put(key, value);
        }
    }

    pub fn putWindowsBlock(map: *Map, view: WindowsBlock.View) Allocator.Error!void {
        var i: usize = 0;
        while (view.ptr[i] != 0) {
            const key_start = i;

            // 某些特殊环境变量以 = 开头,
            // 因此若第一个字符是 =,就必须特殊处理,不把它当作键值分隔符。
            // https://devblogs.microsoft.com/oldnewthing/20100506-00/?p=14133
            //
            if (view.ptr[key_start] == '=') i += 1;

            while (view.ptr[i] != 0 and view.ptr[i] != '=') : (i += 1) {}
            const key_w = view.ptr[key_start..i];
            const key = try unicode.wtf16LeToWtf8Alloc(map.allocator, key_w);
            errdefer map.allocator.free(key);

            if (view.ptr[i] == '=') i += 1;

            const value_start = i;
            while (view.ptr[i] != 0) : (i += 1) {}
            const value_w = view.ptr[value_start..i];
            const value = try unicode.wtf16LeToWtf8Alloc(map.allocator, value_w);
            errdefer map.allocator.free(value);

            i += 1; // 跳过空字节

            try map.putMove(key, value);
        }
    }

    /// 与 `put` 相同,但键和值的所有权转移给 Map,
    /// 而不是复制。
    /// 若 `putMove` 失败,键和值的所有权不转移。
    ///
    /// 断言 `key` 有效:
    /// - 不得包含 NUL(`'\x00') 字节。
    /// - 长度必须 > 0。
    /// - 不得包含 `=`,但 Windows 上允许第一个代码点为 `=`。
    /// - Windows 上必须为有效的 [WTF-8](https://wtf-8.codeberg.page/)。
    pub fn putMove(self: *Map, key: []u8, value: []u8) Allocator.Error!void {
        assert(validateKeyForPut(key));
        const gpa = self.allocator;
        const get_or_put = try self.array_hash_map.getOrPut(gpa, key);
        if (get_or_put.found_existing) {
            gpa.free(get_or_put.key_ptr.*);
            gpa.free(get_or_put.value_ptr.*);
            get_or_put.key_ptr.* = key;
        }
        get_or_put.value_ptr.* = value;
    }

    /// 将 `key` 和 `value` 复制到映射中。
    ///
    /// 断言 `key` 有效:
    /// - 不能包含 NUL(`'\x00') 字节。
    /// - 长度必须大于 0。
    /// - 不能包含 `=`,但 Windows 上允许仅第一个码点为 `=`。
    /// - Windows 上必须是有效的 [WTF-8](https://wtf-8.codeberg.page/)。
    pub fn put(self: *Map, key: []const u8, value: []const u8) Allocator.Error!void {
        assert(validateKeyForPut(key));
        const gpa = self.allocator;
        const value_copy = try gpa.dupe(u8, value);
        errdefer gpa.free(value_copy);
        const get_or_put = try self.array_hash_map.getOrPut(gpa, key);
        errdefer {
            if (!get_or_put.found_existing) assert(self.array_hash_map.pop() != null);
        }
        if (get_or_put.found_existing) {
            gpa.free(get_or_put.value_ptr.*);
        } else {
            get_or_put.key_ptr.* = try gpa.dupe(u8, key);
        }
        get_or_put.value_ptr.* = value_copy;
    }

    /// 查找与键关联的值的地址。
    /// 映射调整大小时,返回的指针失效。
    /// Windows 上,断言 `key` 为有效的 [WTF-8](https://wtf-8.codeberg.page/)。
    pub fn getPtr(self: Map, key: []const u8) ?*[]const u8 {
        assert(validateKeyForFetch(key));
        return self.array_hash_map.getPtr(key);
    }

    /// 返回映射中与某键关联的值的副本。
    /// 若从映射移除此键,
    /// 返回的字符串即失效。
    /// 在 Windows 上,断言 `key` 是有效 [WTF-8](https://wtf-8.codeberg.page/)。
    pub fn get(self: Map, key: []const u8) ?[]const u8 {
        assert(validateKeyForFetch(key));
        return self.array_hash_map.get(key);
    }

    /// 在 Windows 上,断言 `key` 为有效的 [WTF-8](https://wtf-8.codeberg.page/)。
    pub fn contains(m: *const Map, key: []const u8) bool {
        assert(validateKeyForFetch(key));
        return m.array_hash_map.contains(key);
    }

    /// 若存在键匹配的条目,则从哈希映射删除。
    /// 通过与最后一个元素交换,从底层数组移除此条目。
    ///
    /// 移除条目时返回 true,否则返回 false。
    ///
    /// 这会使 get() 针对此键返回的值失效。
    /// Windows 上,断言 `key` 是有效 [WTF-8](https://wtf-8.codeberg.page/)。
    ///
    pub fn swapRemove(self: *Map, key: []const u8) bool {
        assert(validateKeyForFetch(key));
        const kv = self.array_hash_map.fetchSwapRemove(key) orelse return false;
        const gpa = self.allocator;
        gpa.free(kv.key);
        gpa.free(kv.value);
        return true;
    }

    /// 若存在键匹配的条目,则从映射中删除。
    /// 通过将后续所有元素前移,从底层数组移除此条目,从而保持现有顺序。
    ///
    /// 移除条目时返回 true,否则返回 false。
    ///
    /// 这会使 get() 针对此键返回的值失效。
    /// Windows 上,断言 `key` 是有效 [WTF-8](https://wtf-8.codeberg.page/)。
    ///
    pub fn orderedRemove(self: *Map, key: []const u8) bool {
        assert(validateKeyForFetch(key));
        const kv = self.array_hash_map.fetchOrderedRemove(key) orelse return false;
        const gpa = self.allocator;
        gpa.free(kv.key);
        gpa.free(kv.value);
        return true;
    }

    /// 返回映射中存储的键值对数量。
    pub fn count(self: Map) Size {
        return self.array_hash_map.count();
    }

    /// 返回遍历映射条目的迭代器。
    pub fn iterator(self: *const Map) ArrayHashMap.Iterator {
        return self.array_hash_map.iterator();
    }

    /// 返回使用 `gpa` 分配的 `em` 的完整副本;
    /// 它不一定与分配 `em` 时使用的分配器相同。
    pub fn clone(m: *const Map, gpa: Allocator) Allocator.Error!Map {
        var new: Map = .init(gpa);
        errdefer new.deinit();
        try new.array_hash_map.ensureUnusedCapacity(gpa, m.array_hash_map.count());
        for (m.array_hash_map.keys(), m.array_hash_map.values()) |key, value| {
            try new.put(key, value);
        }
        return new;
    }

    /// 将 `other` 中的所有键值对添加到此 `m`。
    pub fn putAll(m: *Map, other: *const Map) Allocator.Error!void {
        const gpa = m.allocator;
        try m.array_hash_map.ensureUnusedCapacity(gpa, other.array_hash_map.count());
        const start = m.count();
        errdefer while (m.array_hash_map.count() > start) {
            const kv = m.array_hash_map.pop().?;
            gpa.free(kv.key);
            gpa.free(kv.value);
        };
        for (other.array_hash_map.keys(), other.array_hash_map.values()) |key, value| {
            try m.put(key, value);
        }
    }

    /// 将长度设为零,释放所有键和值的内存,但不释放
    /// 条目所分配的内存。
    pub fn clearRetainingCapacity(m: *Map) void {
        const gpa = m.allocator;
        for (m.array_hash_map.keys(), m.array_hash_map.values()) |k, v| {
            gpa.free(k);
            gpa.free(v);
        }
        m.array_hash_map.clearRetainingCapacity();
    }

    /// 根据哈希映射和选项,创建符合 POSIX 预期格式的空字符分隔环境变量块。
    ///
    pub fn createPosixBlock(
        map: *const Map,
        gpa: Allocator,
        options: CreatePosixBlockOptions,
    ) Allocator.Error!PosixBlock {
        const ZigProgressAction = enum { nothing, edit, delete, add };
        const zig_progress_action: ZigProgressAction = action: {
            const fd = options.zig_progress_fd orelse break :action .nothing;
            const exists = map.contains("ZIG_PROGRESS");
            if (fd >= 0) {
                break :action if (exists) .edit else .add;
            } else {
                if (exists) break :action .delete;
            }
            break :action .nothing;
        };

        const envp = try gpa.allocSentinel(?[*:0]u8, len: {
            var len: usize = map.count();
            switch (zig_progress_action) {
                .add => len += 1,
                .delete => len -= 1,
                .nothing, .edit => {},
            }
            break :len len;
        }, null);
        var envp_len: usize = 0;
        errdefer {
            envp[envp_len] = null;
            PosixBlock.deinit(.{ .slice = envp[0..envp_len :null] }, gpa);
        }

        if (zig_progress_action == .add) {
            envp[envp_len] = try std.fmt.allocPrintSentinel(gpa, "ZIG_PROGRESS={d}", .{options.zig_progress_fd.?}, 0);
            envp_len += 1;
        }

        for (map.keys(), map.values()) |key, value| {
            if (mem.eql(u8, key, "ZIG_PROGRESS")) switch (zig_progress_action) {
                .add => unreachable,
                .delete => continue,
                .edit => {
                    envp[envp_len] = try std.fmt.allocPrintSentinel(gpa, "{s}={d}", .{
                        key, options.zig_progress_fd.?,
                    }, 0);
                    envp_len += 1;
                    continue;
                },
                .nothing => {},
            };

            envp[envp_len] = try std.fmt.allocPrintSentinel(gpa, "{s}={s}", .{ key, value }, 0);
            envp_len += 1;
        }

        assert(envp_len == envp.len);
        return .{ .slice = envp };
    }

    /// 调用者拥有结果。
    pub fn createWindowsBlock(
        map: *const Map,
        gpa: Allocator,
        options: CreateWindowsBlockOptions,
    ) error{ OutOfMemory, InvalidWtf8 }!WindowsBlock {
        // 计算所需字节数
        const max_chars_needed = max_chars_needed: {
            var max_chars_needed: usize = "\x00".len;
            if (options.zig_progress_handle) |handle| if (handle != std.os.windows.INVALID_HANDLE_VALUE) {
                max_chars_needed += std.fmt.count("ZIG_PROGRESS={d}\x00", .{@intFromPtr(handle)});
            };
            for (map.keys(), map.values()) |key, value| {
                if (options.zig_progress_handle != null and eqlKeys(key, "ZIG_PROGRESS")) continue;
                max_chars_needed += key.len + "=".len + value.len + "\x00".len;
            }
            break :max_chars_needed @max("\x00\x00".len, max_chars_needed);
        };
        const block = try gpa.alloc(u16, max_chars_needed);
        errdefer gpa.free(block);

        var i: usize = 0;
        if (options.zig_progress_handle) |handle| if (handle != std.os.windows.INVALID_HANDLE_VALUE) {
            @memcpy(
                block[i..][0.."ZIG_PROGRESS=".len],
                &[_]u16{ 'Z', 'I', 'G', '_', 'P', 'R', 'O', 'G', 'R', 'E', 'S', 'S', '=' },
            );
            i += "ZIG_PROGRESS=".len;
            var value_buf: [std.fmt.count("{d}", .{std.math.maxInt(usize)})]u8 = undefined;
            const value = std.mem.print(&value_buf, "{d}", .{@intFromPtr(handle)}) catch unreachable;
            for (block[i..][0..value.len], value) |*r, v| r.* = v;
            i += value.len;
            block[i] = 0;
            i += 1;
        };
        for (map.keys(), map.values()) |key, value| {
            if (options.zig_progress_handle != null and eqlKeys(key, "ZIG_PROGRESS")) continue;
            i += try unicode.wtf8ToWtf16Le(block[i..], key);
            block[i] = '=';
            i += 1;
            i += try unicode.wtf8ToWtf16Le(block[i..], value);
            block[i] = 0;
            i += 1;
        }
        // 空环境是一种特殊情况,需要额外的
        // NUL 终止符。CreateProcess 会读取第二个码元,尽管
        // 理论上第一个码元就足以识别
        // 环境为空(见 https://nullprogram.com/blog/2023/08/23/)。
        for (0..2) |_| {
            block[i] = 0;
            i += 1;
            if (i >= 2) break;
        } else unreachable;
        const reallocated = try gpa.realloc(block, i);
        return .{ .slice = reallocated[0 .. i - 1 :0] };
    }
};

pub const CreateMapError = error{
    OutOfMemory,
    /// 仅限 WASI。`environ_sizes_get` 或 `environ_get` 因
    /// 未预料且未记录的原因失败。
    Unexpected,
};

/// 分配 `Map`,并将环境块复制到其中。
pub fn createMap(env: Environ, allocator: Allocator) CreateMapError!Map {
    var map = Map.init(allocator);
    errdefer map.deinit();
    if (native_os == .windows) empty: {
        if (!env.block.use_global) break :empty;

        const peb = std.os.windows.peb();
        assert(std.os.windows.ntdll.RtlEnterCriticalSection(peb.FastPebLock) == .SUCCESS);
        defer assert(std.os.windows.ntdll.RtlLeaveCriticalSection(peb.FastPebLock) == .SUCCESS);
        try map.putWindowsBlock(.{ .ptr = peb.ProcessParameters.Environment });
    } else if (native_os == .wasi and !builtin.link_libc) empty: {
        if (!env.block.use_global) break :empty;

        var environ_count: usize = undefined;
        var environ_buf_size: usize = undefined;

        const environ_sizes_get_ret = std.os.wasi.environ_sizes_get(&environ_count, &environ_buf_size);
        if (environ_sizes_get_ret != .SUCCESS) {
            return posix.unexpectedErrno(environ_sizes_get_ret);
        }

        if (environ_count == 0) {
            return map;
        }

        const environ = try allocator.alloc([*:0]u8, environ_count);
        defer allocator.free(environ);
        const environ_buf = try allocator.alloc(u8, environ_buf_size);
        defer allocator.free(environ_buf);

        const environ_get_ret = std.os.wasi.environ_get(environ.ptr, environ_buf.ptr);
        if (environ_get_ret != .SUCCESS) {
            return posix.unexpectedErrno(environ_get_ret);
        }

        try map.putPosixBlock(.{ .slice = environ });
    } else try map.putPosixBlock(env.block.view());
    return map;
}

pub const ContainsError = error{
    OutOfMemory,
    /// Windows 上,用户提供的环境变量键必须是
    /// 有效的 [WTF-8](https://wtf-8.codeberg.page/)。若静态已知键有效,
    /// 则此错误不可达。
    InvalidWtf8,
    /// 仅限 WASI。`environ_sizes_get` 或 `environ_get` 因
    /// 意外原因失败。
    Unexpected,
};

/// Windows 上,若 `key` 不是有效的 [WTF-8](https://wtf-8.codeberg.page/),
/// 则返回 `error.InvalidWtf8`。
///
/// 另见:
/// * `createMap`
/// * `containsConstant`
/// * `containsUnempty`
pub fn contains(environ: Environ, gpa: Allocator, key: []const u8) ContainsError!bool {
    if (native_os == .windows and !unicode.wtf8ValidateSlice(key)) return error.InvalidWtf8;
    var map = try createMap(environ, gpa);
    defer map.deinit();
    return map.contains(key);
}

/// 在 Windows 上,若 `key` 不是有效的 [WTF-8](https://wtf-8.codeberg.page/),
/// 则返回 `error.InvalidWtf8`。
///
/// 另见:
/// * `createMap`
/// * `containsUnemptyConstant`
/// * `contains`
pub fn containsUnempty(environ: Environ, gpa: Allocator, key: []const u8) ContainsError!bool {
    if (native_os == .windows and !unicode.wtf8ValidateSlice(key)) return error.InvalidWtf8;
    var map = try createMap(environ, gpa);
    defer map.deinit();
    const value = map.get(key) orelse return false;
    return value.len != 0;
}

/// 在不链接 libc 的 WASI 上,由于需要分配内存,此函数不可用。
///
/// Windows 上,`key` 必须为有效的 [WTF-8](https://wtf-8.codeberg.page/)。
///
/// 另见:
/// * `contains`
/// * `containsUnemptyConstant`
/// * `createMap`
///
pub inline fn containsConstant(environ: Environ, comptime key: []const u8) bool {
    if (native_os == .windows) {
        const key_w = comptime unicode.wtf8ToWtf16LeStringLiteral(key);
        return getWindows(environ, key_w) != null;
    } else {
        return getPosix(environ, key) != null;
    }
}

/// 由于需要内存分配,此函数在未链接 libc 的 WASI 上
/// 不可用。
///
/// Windows 上,`key` 必须是有效的 [WTF-8](https://wtf-8.codeberg.page/)。
///
/// 另请参见:
/// * `containsUnempty`
/// * `containsConstant`
/// * `createMap`
pub inline fn containsUnemptyConstant(environ: Environ, comptime key: []const u8) bool {
    if (native_os == .windows) {
        const key_w = comptime unicode.wtf8ToWtf16LeStringLiteral(key);
        const value = getWindows(environ, key_w) orelse return false;
        return value.len != 0;
    } else {
        const value = getPosix(environ, key) orelse return false;
        return value.len != 0;
    }
}

/// 由于需要分配内存,在不使用 libc 的 WASI 上,此函数不可用。
///
/// 另见:
/// * `getWindows`
/// * `createMap`
///
pub fn getPosix(environ: Environ, key: []const u8) ?[:0]const u8 {
    if (mem.findScalar(u8, key, '=') != null) return null;
    for (environ.block.view().slice) |entry| {
        var entry_i: usize = 0;
        while (entry[entry_i] != 0) : (entry_i += 1) {
            if (entry_i == key.len) break;
            if (entry[entry_i] != key[entry_i]) break;
        }
        if ((entry_i != key.len) or (entry[entry_i] != '=')) continue;

        return mem.sliceTo(entry + entry_i + 1, 0);
    }
    return null;
}

/// 仅适用于 Windows。获取名称以空终止、采用 WTF-16
/// 编码的环境变量。
///
/// 此函数使用 RtlEqualUnicodeString 执行
/// 识别 Unicode 的不区分大小写查找。
///
/// 另见:
/// * `createMap`
/// * `containsConstant`
/// * `contains`
pub fn getWindows(environ: Environ, key: [*:0]const u16) ?[:0]const u16 {
    // 除起始位置外,任何位置出现 '=' 都会使此环境变量名称无效。
    const key_slice = mem.sliceTo(key, 0);
    if (key_slice.len == 0 or mem.findScalar(u16, key_slice[1..], '=') != null) return null;

    if (!environ.block.use_global) return null;

    const peb = std.os.windows.peb();
    assert(std.os.windows.ntdll.RtlEnterCriticalSection(peb.FastPebLock) == .SUCCESS);
    defer assert(std.os.windows.ntdll.RtlLeaveCriticalSection(peb.FastPebLock) == .SUCCESS);
    const ptr = peb.ProcessParameters.Environment;

    var i: usize = 0;
    while (ptr[i] != 0) {
        const key_value = mem.sliceTo(ptr[i..], 0);

        // 某些特殊环境变量以 = 开头,
        // 因此若第一个字符是 =,就必须特殊处理,不把它当作键值分隔符。
        // https://devblogs.microsoft.com/oldnewthing/20100506-00/?p=14133
        //
        const equal_index = mem.findScalarPos(u16, key_value, 1, '=') orelse {
            // 此约束由 CreateProcess 强制执行。
            // 若违反,CreateProcess 将以 INVALID_PARAMETER 失败。
            unreachable; // 必须包含一个 =
        };

        const this_key = key_value[0..equal_index];
        if (std.os.windows.eqlIgnoreCaseWtf16(key_slice, this_key)) {
            return key_value[equal_index + 1 ..];
        }

        // 跳过 NUL 终止符
        i += key_value.len + 1;
    }
    return null;
}

pub const GetAllocError = error{
    OutOfMemory,
    EnvironmentVariableMissing,
    /// Windows 上,用户提供的环境变量键必须是
    /// 有效的 [WTF-8](https://wtf-8.codeberg.page/)。若静态已知键有效,
    /// 则此错误不可达。
    InvalidWtf8,
};

/// 调用方拥有返回的内存。
///
/// Windows 上:
/// * 如果 `key` 不是有效的 [WTF-8](https://wtf-8.codeberg.page/),则
///   返回 `error.InvalidWtf8`。
/// * 返回值编码为 [WTF-8](https://wtf-8.codeberg.page/)。
///
/// 其他平台上,值是不规定编码的
/// 不透明字节序列。
///
/// 另请参见:
/// * `createMap`
pub fn getAlloc(environ: Environ, gpa: Allocator, key: []const u8) GetAllocError![]u8 {
    if (native_os == .windows and !unicode.wtf8ValidateSlice(key)) return error.InvalidWtf8;
    var map = createMap(environ, gpa) catch return error.OutOfMemory;
    defer map.deinit();
    const val = map.get(key) orelse return error.EnvironmentVariableMissing;
    return gpa.dupe(u8, val);
}

pub const CreatePosixBlockOptions = struct {
    /// `null` 表示保持 `ZIG_PROGRESS` 环境变量不变。
    /// 若非 null,负值表示移除该环境变量,>= 0
    /// 则表示将其设为给定整数。
    zig_progress_fd: ?i32 = null,
};

/// 将另一种环境变量块转换为 POSIX 所需格式的
/// 空字符分隔环境变量块。
pub fn createPosixBlock(
    existing: Environ,
    gpa: Allocator,
    options: CreatePosixBlockOptions,
) Allocator.Error!PosixBlock {
    const contains_zig_progress = for (existing.block.view().slice) |entry| {
        if (mem.eql(u8, mem.sliceTo(entry, '='), "ZIG_PROGRESS")) break true;
    } else false;

    const ZigProgressAction = enum { nothing, edit, delete, add };
    const zig_progress_action: ZigProgressAction = action: {
        const fd = options.zig_progress_fd orelse break :action .nothing;
        if (fd >= 0) {
            break :action if (contains_zig_progress) .edit else .add;
        } else {
            if (contains_zig_progress) break :action .delete;
        }
        break :action .nothing;
    };

    const envp = try gpa.allocSentinel(?[*:0]u8, len: {
        var len: usize = existing.block.slice.len;
        switch (zig_progress_action) {
            .add => len += 1,
            .delete => len -= 1,
            .nothing, .edit => {},
        }
        break :len len;
    }, null);
    var envp_len: usize = 0;
    errdefer {
        envp[envp_len] = null;
        PosixBlock.deinit(.{ .slice = envp[0..envp_len :null] }, gpa);
    }
    if (zig_progress_action == .add) {
        envp[envp_len] = try std.fmt.allocPrintSentinel(gpa, "ZIG_PROGRESS={d}", .{options.zig_progress_fd.?}, 0);
        envp_len += 1;
    }

    var existing_index: usize = 0;
    while (existing.block.slice[existing_index]) |entry| : (existing_index += 1) {
        if (mem.eql(u8, mem.sliceTo(entry, '='), "ZIG_PROGRESS")) switch (zig_progress_action) {
            .add => unreachable,
            .delete => continue,
            .edit => {
                envp[envp_len] = try std.fmt.allocPrintSentinel(gpa, "ZIG_PROGRESS={d}", .{options.zig_progress_fd.?}, 0);
                envp_len += 1;
                continue;
            },
            .nothing => {},
        };
        envp[envp_len] = try gpa.dupeSentinel(u8, mem.span(entry), 0);
        envp_len += 1;
    }

    assert(envp_len == envp.len);
    return .{ .slice = envp };
}

pub const CreateWindowsBlockOptions = struct {
    /// `null` 表示保持 `ZIG_PROGRESS` 环境变量不变。
    /// 若非 null,`std.os.windows.INVALID_HANDLE_VALUE` 表示移除
    /// 环境变量;否则将给定句柄作为整数赋给该变量。
    zig_progress_handle: ?std.os.windows.HANDLE = null,
};

/// 将另一种环境变量块转换为 POSIX 所需格式的
/// 空字符分隔环境变量块。
pub fn createWindowsBlock(
    existing: Environ,
    gpa: Allocator,
    options: CreateWindowsBlockOptions,
) Allocator.Error!WindowsBlock {
    if (!existing.block.use_global) return .{
        .slice = try gpa.dupeSentinel(u16, WindowsBlock.empty.slice, 0),
    };
    const peb = std.os.windows.peb();
    assert(std.os.windows.ntdll.RtlEnterCriticalSection(peb.FastPebLock) == .SUCCESS);
    defer assert(std.os.windows.ntdll.RtlLeaveCriticalSection(peb.FastPebLock) == .SUCCESS);
    const existing_block = peb.ProcessParameters.Environment;
    var ranges: [2]struct { start: usize, end: usize } = undefined;
    var ranges_len: usize = 0;
    ranges[ranges_len].start = 0;
    const zig_progress_key = [_]u16{ 'Z', 'I', 'G', '_', 'P', 'R', 'O', 'G', 'R', 'E', 'S', 'S', '=' };
    const needed_len = needed_len: {
        var needed_len: usize = "\x00".len;
        if (options.zig_progress_handle) |handle| if (handle != std.os.windows.INVALID_HANDLE_VALUE) {
            needed_len += std.fmt.count("ZIG_PROGRESS={d}\x00", .{@intFromPtr(handle)});
        };
        var i: usize = 0;
        while (existing_block[i] != 0) {
            const start = i;
            const entry = mem.sliceTo(existing_block[start..], 0);
            i += entry.len + "\x00".len;
            if (options.zig_progress_handle != null and entry.len >= zig_progress_key.len and
                std.os.windows.eqlIgnoreCaseWtf16(entry[0..zig_progress_key.len], &zig_progress_key))
            {
                ranges[ranges_len].end = start;
                ranges_len += 1;
                ranges[ranges_len].start = i;
            } else needed_len += entry.len + "\x00".len;
        }
        ranges[ranges_len].end = i;
        ranges_len += 1;
        break :needed_len @max("\x00\x00".len, needed_len);
    };
    const block = try gpa.alloc(u16, needed_len);
    errdefer gpa.free(block);
    var i: usize = 0;
    if (options.zig_progress_handle) |handle| if (handle != std.os.windows.INVALID_HANDLE_VALUE) {
        @memcpy(block[i..][0..zig_progress_key.len], &zig_progress_key);
        i += zig_progress_key.len;
        var value_buf: [std.fmt.count("{d}", .{std.math.maxInt(usize)})]u8 = undefined;
        const value = std.mem.print(&value_buf, "{d}", .{@intFromPtr(handle)}) catch unreachable;
        for (block[i..][0..value.len], value) |*r, v| r.* = v;
        i += value.len;
        block[i] = 0;
        i += 1;
    };
    for (ranges[0..ranges_len]) |range| {
        const range_len = range.end - range.start;
        @memcpy(block[i..][0..range_len], existing_block[range.start..range.end]);
        i += range_len;
    }
    // 空环境是一种特殊情况,需要额外的
    // NUL 终止符。CreateProcess 会读取第二个码元,尽管
    // 理论上第一个码元就足以识别
    // 环境为空(见 https://nullprogram.com/blog/2023/08/23/)。
    for (0..2) |_| {
        block[i] = 0;
        i += 1;
        if (i >= 2) break;
    } else unreachable;
    assert(i == block.len);
    return .{ .slice = block[0 .. i - 1 :0] };
}

test "Map.createPosixBlock" {
    const gpa = testing.allocator;

    var envmap = Map.init(gpa);
    defer envmap.deinit();

    try envmap.put("HOME", "/home/ifreund");
    try envmap.put("WAYLAND_DISPLAY", "wayland-1");
    try envmap.put("DISPLAY", ":1");
    try envmap.put("DEBUGINFOD_URLS", " ");
    try envmap.put("XCURSOR_SIZE", "24");

    const block = try envmap.createPosixBlock(gpa, .{});
    defer block.deinit(gpa);

    try testing.expectEqual(@as(usize, 5), block.slice.len);

    for (&[_][]const u8{
        "HOME=/home/ifreund",
        "WAYLAND_DISPLAY=wayland-1",
        "DISPLAY=:1",
        "DEBUGINFOD_URLS= ",
        "XCURSOR_SIZE=24",
    }, block.slice) |expected, actual| try testing.expectEqualStrings(expected, mem.span(actual.?));
}

test Map {
    const gpa = testing.allocator;

    var env: Map = .init(gpa);
    defer env.deinit();

    try env.put("SOMETHING_NEW", "hello");
    try testing.expectEqualStrings("hello", env.get("SOMETHING_NEW").?);
    try testing.expectEqual(@as(Map.Size, 1), env.count());

    // 覆盖
    try env.put("SOMETHING_NEW", "something");
    try testing.expectEqualStrings("something", env.get("SOMETHING_NEW").?);
    try testing.expectEqual(@as(Map.Size, 1), env.count());

    // 用于测试 Windows 专用转换缓冲区的更长新名称
    try env.put("SOMETHING_NEW_AND_LONGER", "1");
    try testing.expectEqualStrings("1", env.get("SOMETHING_NEW_AND_LONGER").?);
    try testing.expectEqual(@as(Map.Size, 2), env.count());

    // 仅 Windows 不区分大小写
    if (native_os == .windows) {
        try testing.expectEqualStrings("1", env.get("something_New_aNd_LONGER").?);
    } else {
        try testing.expect(null == env.get("something_New_aNd_LONGER"));
    }

    var it = env.iterator();
    var count: Map.Size = 0;
    while (it.next()) |entry| {
        const is_an_expected_name = mem.eql(u8, "SOMETHING_NEW", entry.key_ptr.*) or mem.eql(u8, "SOMETHING_NEW_AND_LONGER", entry.key_ptr.*);
        try testing.expect(is_an_expected_name);
        count += 1;
    }
    try testing.expectEqual(@as(Map.Size, 2), count);

    try testing.expect(env.swapRemove("SOMETHING_NEW"));
    try testing.expect(!env.swapRemove("SOMETHING_NEW"));
    try testing.expect(env.get("SOMETHING_NEW") == null);
    try testing.expect(!env.contains("SOMETHING_NEW"));

    try testing.expectEqual(@as(Map.Size, 1), env.count());

    if (native_os == .windows) {
        // 测试 Windows 上的 Unicode 大小写不敏感行为
        try env.put("КИРиллИЦА", "something else");
        try testing.expectEqualStrings("something else", env.get("кириллица").?);

        // 以及并非有效 UTF-8 的 WTF-8
        const wtf8_with_surrogate_pair = try unicode.wtf16LeToWtf8Alloc(gpa, &[_]u16{
            mem.nativeToLittle(u16, 0xD83D), // 未配对的高位代理项
        });
        defer gpa.free(wtf8_with_surrogate_pair);

        try env.put(wtf8_with_surrogate_pair, wtf8_with_surrogate_pair);
        try testing.expectEqualSlices(u8, wtf8_with_surrogate_pair, env.get(wtf8_with_surrogate_pair).?);
    }
}

test "convert from Environ to Map and back again" {
    if (native_os == .windows) return;
    if (native_os == .wasi and !builtin.link_libc) return;

    const gpa = testing.allocator;

    var map: Map = .init(gpa);
    defer map.deinit();
    try map.put("FOO", "BAR");
    try map.put("A", "");

    const environ: Environ = .{ .block = try map.createPosixBlock(gpa, .{}) };
    defer environ.block.deinit(gpa);

    try testing.expectEqual(true, environ.contains(gpa, "FOO"));
    try testing.expectEqual(false, environ.contains(gpa, "BAR"));
    try testing.expectEqual(true, environ.contains(gpa, "A"));
    try testing.expectEqual(true, environ.containsConstant("A"));
    try testing.expectEqual(false, environ.containsUnempty(gpa, "A"));
    try testing.expectEqual(false, environ.containsUnemptyConstant("A"));
    try testing.expectEqual(false, environ.contains(gpa, "B"));

    try testing.expectError(error.EnvironmentVariableMissing, environ.getAlloc(gpa, "BOGUS"));
    {
        const value = try environ.getAlloc(gpa, "FOO");
        defer gpa.free(value);
        try testing.expectEqualStrings("BAR", value);
    }

    var map2 = try environ.createMap(gpa);
    defer map2.deinit();

    try testing.expectEqualDeep(map.keys(), map2.keys());
    try testing.expectEqualDeep(map.values(), map2.values());
}

test "Map.putPosixBlock" {
    const gpa = testing.allocator;

    var map: Map = .init(gpa);
    defer map.deinit();

    try map.put("FOO", "BAR");
    try map.put("A", "");
    try map.put("ZIG_PROGRESS", "unchanged");

    const block = try map.createPosixBlock(gpa, .{});
    defer block.deinit(gpa);

    var map2: Map = .init(gpa);
    defer map2.deinit();
    try map2.putPosixBlock(block.view());

    try testing.expectEqualDeep(&[_][]const u8{ "FOO", "A", "ZIG_PROGRESS" }, map2.keys());
    try testing.expectEqualDeep(&[_][]const u8{ "BAR", "", "unchanged" }, map2.values());
}

test "Map.putWindowsBlock" {
    if (native_os != .windows) return;

    const gpa = testing.allocator;

    var map: Map = .init(gpa);
    defer map.deinit();

    try map.put("FOO", "BAR");
    try map.put("A", "");
    try map.put("=B", "");
    try map.put("ZIG_PROGRESS", "unchanged");

    const block = try map.createWindowsBlock(gpa, .{});
    defer block.deinit(gpa);

    var map2: Map = .init(gpa);
    defer map2.deinit();
    try map2.putWindowsBlock(block.view());

    try testing.expectEqualDeep(&[_][]const u8{ "FOO", "A", "=B", "ZIG_PROGRESS" }, map2.keys());
    try testing.expectEqualDeep(&[_][]const u8{ "BAR", "", "", "unchanged" }, map2.values());
}