控制流基础

// File: chapters-data/code/02__control-flow-essentials/branching.zig

// Demonstrates Zig's control flow and optional handling capabilities
// 演示Zig的控制流和可选值处理能力
const std = @import("std");

/// Determines a descriptive label for an optional integer value.
/// 为可选整数确定描述性标签
/// Uses labeled blocks to handle different numeric cases cleanly.
/// 使用带标签的代码块简洁处理不同的数值情况
/// Returns a string classification based on the value's properties.
/// 返回基于值属性的字符串分类
fn chooseLabel(value: ?i32) []const u8 {
    // Unwrap the optional value using payload capture syntax
    // 使用载荷捕获语法解包可选值
    return if (value) |v| blk: {
        // Check for zero first
        // 首先检查是否为零
        if (v == 0) break :blk "zero";
        // Positive numbers
        // 正数
        if (v > 0) break :blk "positive";
        // All remaining cases are negative
        // 所有剩余情况都是负数
        break :blk "negative";
    } else "missing";
    // Handle null case
    // 处理空值情况
}

pub fn main() !void {
    // Array containing both present and absent (null) values
    // 包含存在值和空值的数组
    const samples = [_]?i32{ 5, 0, null, -3 };

    // Iterate through samples with index capture
    // 遍历样本并捕获索引
    for (samples, 0..) |item, index| {
        // Classify each sample value
        // 对每个样本值进行分类
        const label = chooseLabel(item);
        // Display the index and corresponding label
        // 显示索引和对应的标签
        std.debug.print("sample {d}: {s}\n", .{ index, label });
    }
}

// 文件路径: chapters-data/code/02__control-flow-essentials/loop_labels.zig

// 演示Zig中的带标签循环和while-else结构
const std = @import("std");

/// 查找第一个两元素都为偶数的行
/// 使用while循环和continue语句跳过无效行
/// 返回匹配行的基于零的索引，如果未找到则返回null
fn findAllEvenPair(rows: []const [2]i32) ?usize {
    // 在迭代期间跟踪当前行索引
    var row: usize = 0;
    // while-else结构：break提供值，else提供回退
    const found = while (row < rows.len) : (row += 1) {
        // 提取当前对进行检查
        const pair = rows[row];
        // 如果第一个元素是奇数则跳过该行
        if (@mod(pair[0], 2) != 0) continue;
        // 如果第二个元素是奇数则跳过该行
        if (@mod(pair[1], 2) != 0) continue;
        // 两个元素都是偶数：返回此行的索引
        break row;
    } else null; // 耗尽所有行后未找到匹配行

    return found;
}

pub fn main() !void {
    // 测试数据，包含混合奇偶值的整数对
    const grid = [_][2]i32{
        .{ 3, 7 }, // 两者都是奇数
        .{ 2, 4 }, // 两者都是偶数（目标）
        .{ 5, 6 }, // 混合
    };

    // 查找第一个全偶数对并报告结果
    if (findAllEvenPair(&grid)) |row| {
        std.debug.print("first all-even row: {d}\n", .{row});
    } else {
        std.debug.print("no all-even rows\n", .{});
    }

    // 演示用于多级break控制的带标签循环
    var attempts: usize = 0;
    // 为外部while循环添加标签以启用从嵌套for循环跳出
    outer: while (attempts < grid.len) : (attempts += 1) {
        // 遍历当前行的列并捕获索引
        for (grid[attempts], 0..) |value, column| {
            // 检查是否找到目标值
            if (value == 4) {
                // 报告目标值的位置
                std.debug.print(
                    "found target value at row {d}, column {d}\n",
                    .{ attempts, column },
                );
                // 使用外部标签跳出两个循环
                break :outer;
            }
        }
    }
}

// File: chapters-data/code/02__control-flow-essentials/switch_examples.zig

// Import the standard library for I/O operations
// 导入标准库用于I/O操作
const std = @import("std");

// Define an enum representing different compilation modes
// 定义一个枚举，表示不同的编译模式
const Mode = enum { fast, safe, tiny };

/// Converts a numeric score into a descriptive text message.
/// 将数值分数转换为描述性文本消息。
/// Demonstrates switch expressions with ranges, multiple values, and catch-all cases.
/// 演示switch表达式的范围匹配、多值匹配和通配符匹配用法。
/// Returns a string literal describing the score's progress level.
/// 返回描述分数进度级别的字符串字面量。
fn describeScore(score: u8) []const u8 {
    return switch (score) {
        0 => "no progress",           // Exact match for zero
        // 精确匹配零值
        1...3 => "warming up",         // Range syntax: matches 1, 2, or 3
        // 范围语法：匹配 1, 2 或 3
        4, 5 => "halfway there",       // Multiple discrete values
        // 匹配多个离散值
        6...9 => "almost done",        // Range: matches 6 through 9
        // 范围语法：匹配 6 到 9
        10 => "perfect run",           // Maximum valid score
        // 最大有效分数
        else => "out of range",        // Catch-all for any other value
        // 通配符：匹配所有其他值
    };
}

pub fn main() !void {
    // Array of test scores to demonstrate switch behavior
    // 测试分数数组，用于演示switch行为
    const samples = [_]u8{ 0, 2, 5, 8, 10, 12 };

    // Iterate through each score and print its description
    // 遍历每个分数并打印其描述
    for (samples) |score| {
        std.debug.print("{d}: {s}\n", .{ score, describeScore(score) });
    }

    // Demonstrate switch with enum values
    // 演示与枚举值一起使用的switch语句
    const mode: Mode = .safe;

    // Switch on enum to assign different numeric factors based on mode
    // 基于枚举值切换，根据模式分配不同的数值因子
    // All enum cases must be handled (exhaustive matching)
    // 必须处理所有枚举情况（穷尽性匹配）
    const factor = switch (mode) {
        .fast => 32,  // Optimization for speed
        // 速度优化
        .safe => 16,  // Balanced mode
        // 平衡模式
        .tiny => 4,   // Optimization for size
        // 体积优化
    };

    // Print the selected mode and its corresponding factor
    // 打印选中的模式及其对应的因子
    std.debug.print("mode {s} -> factor {d}\n", .{ @tagName(mode), factor });
}

// 文件路径: chapters-data/code/02__control-flow-essentials/script_runner.zig

// 演示高级控制流：switch表达式、带标签循环
// 和基于阈值条件的早期终止
const std = @import("std");

/// 脚本处理器中所有可能操作类型的枚举
const Action = enum { add, skip, threshold, unknown };

/// 表示单个处理步骤，包含相关操作和值
const Step = struct {
    tag: Action,
    value: i32,
};

/// 包含脚本执行完成或提前终止后的最终状态
const Outcome = struct {
    index: usize, // 处理停止的步骤索引
    total: i32,   // 终止时的累积总值
};

/// 将单字符代码映射到对应的Action枚举值
/// 对于无法识别的代码返回.unknown以保持穷举处理
fn mapCode(code: u8) Action {
    return switch (code) {
        'A' => .add,
        'S' => .skip,
        'T' => .threshold,
        else => .unknown,
    };
}

/// 执行步骤序列，累积值并检查阈值限制
/// 如果阈值步骤发现总值达到或超过限制，则提前停止处理
/// 返回包含停止索引和最终累积总值的Outcome
fn process(script: []const Step, limit: i32) Outcome {
    // 加法操作的运行累积器
    var total: i32 = 0;

    // for-else结构：break提供早期终止值，else提供完成值
    const stop = outer: for (script, 0..) |step, index| {
        // 根据当前步骤的操作类型分派
        switch (step.tag) {
            // 加法操作：将步骤的值累积到运行总值
            .add => total += step.value,
            // 跳过操作：绕过此步骤而不修改状态
            .skip => continue :outer,
            // 阈值检查：如果达到或超过限制则提前终止
            .threshold => {
                if (total >= limit) break :outer Outcome{ .index = index, .total = total };
                // 未达到阈值：继续下一步
                continue :outer;
            },
            // 安全断言：未知操作不应出现在已验证的脚本中
            .unknown => unreachable,
        }
    } else Outcome{ .index = script.len, .total = total }; // 所有步骤后正常完成

    return stop;
}

pub fn main() !void {
    // 定义演示所有操作类型的脚本序列
    const script = [_]Step{
        .{ .tag = mapCode('A'), .value = 2 },  // 加2 → 总计: 2
        .{ .tag = mapCode('S'), .value = 0 },  // 跳过（无效果）
        .{ .tag = mapCode('A'), .value = 5 },  // 加5 → 总计: 7
        .{ .tag = mapCode('T'), .value = 6 },  // 阈值检查 (7 >= 6: 触发早期退出)
        .{ .tag = mapCode('A'), .value = 10 }, // 由于早期终止而永不执行
    };

    // 使用阈值限制6执行脚本
    const outcome = process(&script, 6);

    // 报告执行停止的位置和最终累积值
    std.debug.print(
        "stopped at step {d} with total {d}\n",
        .{ outcome.index, outcome.total },
    );
}

// 文件路径: chapters-data/code/02__control-flow-essentials/range_scan.zig

// 演示带标签break和continue语句的while循环
const std = @import("std");

pub fn main() !void {
    // 示例数据数组，包含混合的正数、负数和零值
    const data = [_]i16{ 12, 5, 9, -1, 4, 0 };

    // 搜索数组中的第一个负值
    var index: usize = 0;
    // while-else结构：break提供值，else提供回退
    const first_negative = while (index < data.len) : (index += 1) {
        // 检查当前元素是否为负数
        if (data[index] < 0) break index;
    } else null; // 扫描整个数组后未找到负值

    // 报告负值搜索结果
    if (first_negative) |pos| {
        std.debug.print("first negative at index {d}\n", .{pos});
    } else {
        std.debug.print("no negatives in sequence\n", .{});
    }

    // 累积偶数之和直到遇到零
    var sum: i64 = 0;
    var count: usize = 0;

    // 为循环添加标签以启用显式break定位
    accumulate: while (count < data.len) : (count += 1) {
        const value = data[count];
        // 遇到零时停止累积
        if (value == 0) {
            std.debug.print("encountered zero, breaking out\n", .{});
            break :accumulate;
        }
        // 使用带标签的continue跳过奇数值
        if (@mod(value, 2) != 0) continue :accumulate;
        // 将偶数值加到运行总和
        sum += value;
    }

    // 显示零之前的偶数前缀值的累积和
    std.debug.print("sum of even prefix values = {d}\n", .{sum});
}