非法行为与安全模式

const std = @import("std");

/// 执行带溢出检测和饱和的加法。
/// 如果发生溢出，返回最大值u8而不是环绕。
/// 在非溢出路径中使用@setRuntimeSafety(false)以提高性能。
fn guardedUncheckedAdd(a: u8, b: u8) u8 {
    // 使用内置溢出检测检查加法是否会溢出
    const sum = @addWithOverflow(a, b);
    const overflow = sum[1] == 1;
    // 溢出时饱和到最大值
    if (overflow) return std.math.maxInt(u8);

    // 安全路径：为此加法禁用运行时安全检查
    // 因为我们已经验证不会发生溢出
    return blk: {
        @setRuntimeSafety(false);
        break :blk a + b;
    };
}

/// 执行不带运行时安全检查的加法。
/// 这允许操作在溢出时环绕（安全模式中的未定义行为）。
/// 演示完全禁用函数作用域的安全性。
fn wrappingAddUnsafe(a: u8, b: u8) u8 {
    // 禁用整个函数的所有运行时安全检查
    @setRuntimeSafety(false);
    return a + b;
}

// 验证guardedUncheckedAdd正确处理正常加法和溢出饱和场景。
test "guarded unchecked addition saturates on overflow" {
    // 正常情况：120 + 80 = 200（无溢出）
    try std.testing.expectEqual(@as(u8, 200), guardedUncheckedAdd(120, 80));
    // 溢出情况：240 + 30 = 270 > 255，应饱和到255
    try std.testing.expectEqual(std.math.maxInt(u8), guardedUncheckedAdd(240, 30));
}

// 演示wrappingAddUnsafe在溢出时产生与@addWithOverflow相同的环绕结果。
test "wrapping addition mirrors overflow tuple" {
    // @addWithOverflow返回[wrapped_result, overflow_bit]
    const sum = @addWithOverflow(@as(u8, 250), @as(u8, 10));
    // 验证发生了溢出（250 + 10 = 260 > 255）
    try std.testing.expect(sum[1] == 1);
    // 验证环绕结果与未检查加法匹配（260 % 256 = 4）
    try std.testing.expectEqual(sum[0], wrappingAddUnsafe(250, 10));
}

const std = @import("std");
const builtin = @import("builtin");

// Extract the compile-time type of the optimization mode enum
// 提取优化模式枚举的编译时类型
const ModeType = @TypeOf(builtin.mode);

// / 捕获活动优化模式及其默认安全行为
const ModeInfo = struct {
    mode: ModeType,
    safety_default: bool,
};

// / 确定给定模式是否默认启用运行时安全检查。
// / Debug 和 ReleaseSafe 模式保留安全检查；ReleaseFast 和 ReleaseSmall 禁用它们。
fn defaultSafety(mode: ModeType) bool {
    return switch (mode) {
        // 这些模式优先考虑正确性，带有运行时检查
        .Debug, .ReleaseSafe => true,
        // 这些模式优先考虑性能/大小，通过移除检查
        .ReleaseFast, .ReleaseSmall => false,
    };
}

// / 执行检查加法，无需 panic 即可检测溢出。
// / 返回包装结果和溢出标志。
fn sampleAdd(a: u8, b: u8) struct { result: u8, overflowed: bool } {
    // @addWithOverflow 返回一个元组：[包装结果, 溢出位]
    const pair = @addWithOverflow(a, b);
    return .{ .result = pair[0], .overflowed = pair[1] == 1 };
}

// / 通过显式禁用运行时安全来执行未检查的加法。
// / 在 Debug/ReleaseSafe 模式下，这避免了溢出时的 panic。
// / 在 ReleaseFast/ReleaseSmall 模式下，安全已关闭，因此这是多余但无害的。
fn uncheckedAddStable(a: u8, b: u8) u8 {
    return blk: {
        // 仅为此块临时禁用运行时安全
        @setRuntimeSafety(false);
        // 不带溢出检查的原始加法；溢出时静默环绕
        break :blk a + b;
    };
}

pub fn main() void {
    // 捕获当前构建模式及其隐含的安全设置
    const info = ModeInfo{
        .mode = builtin.mode,
        .safety_default = defaultSafety(builtin.mode),
    };

    // 报告编译此二进制文件时使用的优化模式
    std.debug.print("optimize-mode: {s}\n", .{@tagName(info.mode)});
    // 显示此模式下是否默认开启运行时安全
    std.debug.print("runtime-safety-default: {}\n", .{info.safety_default});

    // 演示检查过的加法，报告溢出而不崩溃
    const checked = sampleAdd(200, 80);
    std.debug.print("checked-add result={d} overflowed={}\n", .{ checked.result, checked.overflowed });

    // 演示未检查的加法，静默环绕（24 = (200+80) % 256）
    const unchecked = uncheckedAddStable(200, 80);
    std.debug.print("unchecked-add result={d}\n", .{unchecked});
}

// 此文件演示Zig中不同的安全模式以及如何处理
// 具有不同运行时检查级别的转换。

const std = @import("std");

/// 在不进行运行时安全检查的情况下将ASCII数字字符转换为其数值。
/// 此函数使用断言记录前置条件，输入必须是
/// 有效的ASCII数字字符（'0'-'9'）。@setRuntimeSafety(false)指令禁用
/// 减法和转换操作的运行时整数溢出检查。
///
/// 前置条件：字节必须在['0', '9']范围内
/// 返回：数值（0-9）作为u4
pub fn asciiDigitToValueUnchecked(byte: u8) u4 {
    // 断言记录约定：调用者必须提供有效的ASCII数字
    std.debug.assert(byte >= '0' and byte <= '9');

    // 禁用运行时安全的代码块，用于性能关键路径
    return blk: {
        // 禁用此转换的运行时溢出/下溢检查
        @setRuntimeSafety(false);
        // 安全的转换，因为前置条件保证结果适合u4（0-9）
        break :blk @intCast(byte - '0');
    };
}

/// 将ASCII数字字符转换为其数值，带错误处理。
/// 此函数在运行时验证输入，如果
/// 字节不是有效的ASCII数字，则返回错误，使其可以安全用于不受信任的输入。
///
/// 返回：数值（0-9）作为u4，如果无效则返回error.InvalidDigit
pub fn asciiDigitToValue(byte: u8) !u4 {
    // 验证输入在有效的ASCII数字范围内
    if (byte < '0' or byte > '9') return error.InvalidDigit;
    // 安全转换：验证确保结果在0-9范围内
    return @intCast(byte - '0');
}

// 验证未检查的转换对所有有效输入产生正确结果。
// 测试所有ASCII数字以确保基于断言的函数保持正确性
// 即使在内部禁用运行时安全。
test "assert-backed conversion stays safe across modes" {
    // 在编译时迭代所有有效的ASCII数字字符
    inline for ("0123456789") |ch| {
        // 验证未检查函数产生与直接转换相同的结果
        try std.testing.expectEqual(@as(u4, @intCast(ch - '0')), asciiDigitToValueUnchecked(ch));
    }
}

// 验证返回错误的转换正确拒绝无效输入。
// 确保错误路径正确工作并提供有意义的诊断。
test "error path preserves diagnosability" {
    // 验证非数字字符返回预期错误
    try std.testing.expectError(error.InvalidDigit, asciiDigitToValue('z'));
}