数据基础

const std = @import("std");

/// 打印切片的详细信息，包括标签、长度和首元素
/// 如果切片为空，显示 -1 作为首元素的值
fn describe(label: []const u8, data: []const i32) void {
    // 获取首元素，如果切片为空则返回 -1
    const head = if (data.len > 0) data[0] else -1;
    std.debug.print("{s}: len={} head={d}\n", .{ label, data.len, head });
}

/// 演示 Zig 中数组和切片的基础知识，包括：
/// - 数组声明和初始化
/// - 从不同可变性的数组创建切片
/// - 通过直接索引和切片修改数组
/// - 数组复制行为（值语义）
/// - 创建空切片和零长度切片
pub fn main() !void {
    // 声明可推断大小的可变数组
    var values = [_]i32{ 3, 5, 8, 13 };
    // 使用匿名结构语法声明显式大小的常量数组
    const owned: [4]i32 = .{ 1, 2, 3, 4 };

    // 创建覆盖整个数组的可变切片
    var mutable_slice: []i32 = values[0..];
    // 创建前两个元素的不可变切片
    const prefix: []const i32 = values[0..2];
    // 创建零长度切片（空但有效）
    const empty = values[0..0];

    // 通过索引直接修改数组
    values[1] = 99;
    // 通过可变切片修改数组
    mutable_slice[0] = -3;

    std.debug.print("array len={} allows mutation\n", .{values.len});
    describe("mutable_slice", mutable_slice);
    describe("prefix", prefix);
    // 演示切片修改会影响底层数组
    std.debug.print("values[0] after slice write = {d}\n", .{values[0]});
    std.debug.print("empty slice len={} is zero-length\n", .{empty.len});

    // 在 Zig 中数组按值复制
    var copy = owned;
    copy[0] = -1;
    // 显示修改副本不会影响原始数组
    std.debug.print("copy[0]={d} owned[0]={d}\n", .{ copy[0], owned[0] });

    // Create a slice from an empty array literal using address-of operator
    // 从空数组字面量创建切片使用取地址运算符
    const zero: []const i32 = &[_]i32{};
    std.debug.print("zero slice len={} from literal\n", .{zero.len});
}

const std = @import("std");

/// 演示Zig中的哨兵终止字符串和数组，包括：
/// - 零终止字符串字面量（[:0]const u8）
/// - 多项哨兵指针（[*:0]const u8）
/// - 哨兵终止数组（[N:0]T）
/// - 哨兵切片与常规切片之间的转换
/// - 通过哨兵指针进行修改
pub fn main() !void {
    // Zig中的字符串字面量默认以零字节哨兵终止
    // [:0]const u8表示在末尾有哨兵值0的切片
    const literal: [:0]const u8 = "data fundamentals";

    // 将哨兵切片转换为多项哨兵指针
    // [*:0]const u8与C风格空终止字符串兼容
    const c_ptr: [*:0]const u8 = literal;

    // std.mem.span将哨兵终止指针转换回切片
    // 它扫描直到找到哨兵值（0）以确定长度
    const bytes = std.mem.span(c_ptr);
    std.debug.print("literal len={} contents=\"{s}\"\n", .{ bytes.len, bytes });

    // 声明具有显式大小和哨兵值的哨兵终止数组
    // [6:0]u8表示6个元素的数组加上位置6的哨兵0字节
    var label: [6:0]u8 = .{ 'l', 'a', 'b', 'e', 'l', 0 };

    // 从数组创建可变哨兵切片
    // [0..:0]语法从索引0到末尾创建切片，带有哨兵0
    var sentinel_view: [:0]u8 = label[0.. :0];

    // 通过哨兵切片修改第一个元素
    sentinel_view[0] = 'L';

    // 从前4个元素创建常规（非哨兵）切片
    // 这会放弃哨兵保证但提供有界切片
    const trimmed: []const u8 = sentinel_view[0..4];
    std.debug.print("trimmed slice len={} -> {s}\n", .{ trimmed.len, trimmed });

    // 将哨兵切片转换为多项哨兵指针
    // 这允许unchecked索引，同时保留哨兵信息
    const tail: [*:0]u8 = sentinel_view;

    // 通过多项哨兵指针修改索引4处的元素
    // 不会发生边界检查，但哨兵保证仍然有效
    tail[4] = 'X';

    // 演示通过指针的修改影响了原始数组
    // std.mem.span使用哨兵重建完整切片
    std.debug.print("full label after mutation: {s}\n", .{std.mem.span(tail)});
}

const std = @import("std");

/// 表示具有数值读数的传感器设备的简单结构
const Sensor = struct {
    reading: i32,
};

/// 将传感器的读数值打印到调试输出
/// 接受指向传感器的单个指针并显示其当前读数
fn report(label: []const u8, ptr: *Sensor) void {
    std.debug.print("{s} -> reading {d}\n", .{ label, ptr.reading });
}

/// 演示Zig中的指针基础、可选指针和多项目指针
/// 本示例涵盖：
/// - 单项目指针（*T）和指针解引用
/// - 指针别名和通过别名进行修改
/// - 用于表示可空引用的可选指针（?*T）
/// - 使用if语句解包可选指针
/// - 用于未检查多元素访问的多项目指针（[*]T）
/// - 通过.ptr属性将切片转换为多项目指针
pub fn main() !void {
    // 在栈上创建传感器实例
    var sensor = Sensor{ .reading = 41 };

    // 创建传感器的单项目指针别名
    // &操作符获取传感器的地址
    var alias: *Sensor = &sensor;

    // 通过指针别名修改传感器
    // Zig自动解引用指针字段
    alias.reading += 1;

    report("alias", alias);

    // 声明初始化为null的可选指针
    // ?*T表示可能持有或不持有有效地址的指针
    var maybe_alias: ?*Sensor = null;

    // 尝试解包可选指针
    // 此分支不会执行，因为maybe_alias为null
    if (maybe_alias) |pointer| {
        std.debug.print("unexpected pointer: {d}\n", .{pointer.reading});
    } else {
        std.debug.print("optional pointer empty\n", .{});
    }

    // 将有效地址赋值给可选指针
    maybe_alias = &sensor;

    // 解包并使用可选指针
    // |pointer|捕获语法提取非空值
    if (maybe_alias) |pointer| {
        pointer.reading += 10;
        std.debug.print("optional pointer mutated to {d}\n", .{sensor.reading});
    }

    // 创建数组及其切片视图
    var samples = [_]i32{ 5, 7, 9, 11 };
    const view: []i32 = samples[0..];

    // 从切片中提取多项目指针
    // 多项目指针（[*]T）允许不带长度跟踪的未检查索引
    const many: [*]i32 = view.ptr;

    // 通过多项目指针修改底层数组
    // 此时不执行边界检查
    many[2] = 42;

    std.debug.print("slice view len={}\n", .{view.len});
    // 验证通过多项目指针的修改影响了原始数组
    std.debug.print("samples[2] via many pointer = {d}\n", .{samples[2]});
}

const std = @import("std");

/// 演示Zig中的内存对齐概念和各种类型转换操作
/// 本示例涵盖：
/// - 使用align()属性的内存对齐保证
/// - 使用@alignCast的指针转换和对齐调整
/// - 使用@ptrCast进行内存重新解释的类型转换
/// - 使用@bitCast的位级重新解释
/// - 使用@truncate截断整数
/// - 使用@intCast扩展整数
/// - 使用@floatCast浮点精度转换
pub fn main() !void {
    // 创建对齐到u64边界的字节数组，用小端字节初始化
    // 表示前4个字节中的0x11223344
    var raw align(@alignOf(u64)) = [_]u8{ 0x44, 0x33, 0x22, 0x11, 0, 0, 0, 0 };

    // 获取指向首字节的指针，带有显式u64对齐
    const base: *align(@alignOf(u64)) u8 = &raw[0];

    // 使用@alignCast调整对齐约束从u64到u32
    // 这是安全的，因为u64对齐（8字节）满足u32对齐（4字节）
    const aligned_bytes = @as(*align(@alignOf(u32)) const u8, @alignCast(base));

    // 将字节指针重新解释为u32指针，将4字节读取为单个整数
    const word_ptr = @as(*const u32, @ptrCast(aligned_bytes));

    // 解引用以获取32位值（小端：0x11223344）
    const number = word_ptr.*;
    std.debug.print("32-bit value = 0x{X:0>8}\n", .{number});

    // 替代方法：使用@bitCast直接重新解释前4字节
    // 这会创建一个副本，不需要指针操作
    const from_bytes = @as(u32, @bitCast(raw[0..4].*));
    std.debug.print("bitcast copy = 0x{X:0>8}\n", .{from_bytes});

    // 演示@truncate：提取最低有效8位（0x44）
    const small: u8 = @as(u8, @truncate(number));

    // 演示@intCast：将无符号u32扩展为有符号i64，无数据丢失
    const widened: i64 = @as(i64, @intCast(number));
    std.debug.print("truncate -> 0x{X:0>2}, widen -> {d}\n", .{ small, widened });

    // 演示@floatCast：将f64精度降低到f32
    // 对于无法在f32中精确表示的值，可能会导致精度损失
    const ratio64: f64 = 1.875;
    const ratio32: f32 = @as(f32, @floatCast(ratio64));
    std.debug.print("floatCast ratio -> {}\n", .{ratio32});
}