数据基础

const std = @import("std");

/// Prints information about a slice including its label, length, and first element.
/// 打印有关切片的信息，包括其标签、长度和第一个元素。
/// If the slice is empty, displays -1 as the head value.
/// 如果切片为空，则显示-1作为头值。
fn describe(label: []const u8, data: []const i32) void {
    // Get first element or -1 if slice is empty
    // 获取第一个元素，如果切片为空则为-1
    const head = if (data.len > 0) data[0] else -1;
    std.debug.print("{s}: len={} head={d}\n", .{ label, data.len, head });
}

/// Demonstrates array and slice fundamentals in Zig, including:
/// 演示Zig中的数组和切片基础，包括：
/// - Array declaration and initialization
/// - 数组声明和初始化
/// - Creating slices from arrays with different mutability
/// - 从具有不同可变性的数组创建切片
/// - Modifying arrays through direct indexing and slices
/// - 通过直接索引和切片修改数组
/// - Array copying behavior (value semantics)
/// - 数组复制行为（值语义）
/// - Creating empty and zero-length slices
/// - 创建空切片和零长度切片
pub fn main() !void {
    // Declare mutable array with inferred size
    // 声明具有推断大小的可变数组
    var values = [_]i32{ 3, 5, 8, 13 };
    // Declare const array with explicit size using anonymous struct syntax
    // 使用匿名结构语法声明具有显式大小的const数组
    const owned: [4]i32 = .{ 1, 2, 3, 4 };

    // Create a mutable slice covering the entire array
    // 创建覆盖整个数组的可变切片
    var mutable_slice: []i32 = values[0..];
    // Create an immutable slice of the first two elements
    // 创建前两个元素的不可变切片
    const prefix: []const i32 = values[0..2];
    // Create a zero-length slice (empty but valid)
    // 创建零长度切片（空但有效）
    const empty = values[0..0];

    // Modify array directly by index
    // 通过索引直接修改数组
    values[1] = 99;
    // Modify array through mutable slice
    // 通过可变切片修改数组
    mutable_slice[0] = -3;

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

    // Arrays are copied by value in Zig
    // 在Zig中，数组按值复制
    var copy = owned;
    copy[0] = -1;
    // Show that modifying the copy doesn't affect the original
    // 显示修改副本不会影响原始数组
    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");

/// Demonstrates sentinel-terminated strings and arrays in Zig, including:
/// 演示Zig中的哨兵终止字符串和数组，包括：
/// - Zero-terminated string literals ([:0]const u8)
/// - 零终止字符串字面量（[:0]const u8）
/// - Many-item sentinel pointers ([*:0]const u8)
/// - 多项哨兵指针（[*:0]const u8）
/// - Sentinel-terminated arrays ([N:0]T)
/// - 哨兵终止数组（[N:0]T）
/// - Converting between sentinel slices and regular slices
/// - 在哨兵切片和常规切片之间转换
/// - Mutation through sentinel pointers
/// - 通过哨兵指针进行修改
pub fn main() !void {
    // String literals in Zig are sentinel-terminated by default with a zero byte
    // Zig中的字符串字面量默认以零字节哨兵终止
    // [:0]const u8 denotes a slice with a sentinel value of 0 at the end
    // [:0]const u8表示末尾有哨兵值0的切片
    const literal: [:0]const u8 = "data fundamentals";

    // Convert the sentinel slice to a many-item sentinel pointer
    // 将哨兵切片转换为多项哨兵指针
    // [*:0]const u8 is compatible with C-style null-terminated strings
    // [*:0]const u8与C风格的空终止字符串兼容
    const c_ptr: [*:0]const u8 = literal;

    // std.mem.span converts a sentinel-terminated pointer back to a slice
    // std.mem.span将哨兵终止指针转换回切片
    // It scans until it finds the sentinel value (0) to determine the length
    // 它扫描直到找到哨兵值（0）以确定长度
    const bytes = std.mem.span(c_ptr);
    std.debug.print("literal len={} contents=\"{s}\"\n", .{ bytes.len, bytes });

    // Declare a sentinel-terminated array with explicit size and sentinel value
    // 声明具有显式大小和哨兵值的哨兵终止数组
    // [6:0]u8 means an array of 6 elements plus a sentinel 0 byte at position 6
    // [6:0]u8表示一个6元素的数组加上位置6的哨兵0字节
    var label: [6:0]u8 = .{ 'l', 'a', 'b', 'e', 'l', 0 };

    // Create a mutable sentinel slice from the array
    // 从数组创建可变哨兵切片
    // The [0.. :0] syntax creates a slice from index 0 to the end, with sentinel 0
    // [0.. :0]语法创建从索引0到末尾的切片，带哨兵0
    var sentinel_view: [:0]u8 = label[0.. :0];

    // Modify the first element through the sentinel slice
    // 通过哨兵切片修改第一个元素
    sentinel_view[0] = 'L';

    // Create a regular (non-sentinel) slice from the first 4 elements
    // 从前4个元素创建常规（非哨兵）切片
    // This drops the sentinel guarantees but provides a bounded slice
    // 这会取消哨兵保证但提供有界切片
    const trimmed: []const u8 = sentinel_view[0..4];
    std.debug.print("trimmed slice len={} -> {s}\n", .{ trimmed.len, trimmed });

    // Convert the sentinel slice to a many-item sentinel pointer
    // 将哨兵切片转换为多项哨兵指针
    // This allows unchecked indexing while preserving sentinel information
    // 这允许unchecked索引，同时保留哨兵信息
    const tail: [*:0]u8 = sentinel_view;

    // Modify element at index 4 through the many-item sentinel pointer
    // 通过多项哨兵指针修改索引4处的元素
    // No bounds checking occurs, but the sentinel guarantees remain valid
    // 不会发生边界检查，但哨兵保证仍然有效
    tail[4] = 'X';

    // Demonstrate that mutations through the pointer affected the original array
    // 演示通过指针的修改影响了原始数组
    // std.mem.span uses the sentinel to reconstruct the full slice
    // std.mem.span使用哨兵重构完整切片
    std.debug.print("full label after mutation: {s}\n", .{std.mem.span(tail)});
}

const std = @import("std");

/// A simple structure representing a sensor device with a numeric reading.
/// 一个简单的结构，表示具有数值的传感器设备。
const Sensor = struct {
    reading: i32,
};

/// Prints a sensor's reading value to debug output.
/// 将传感器的读数值打印到调试输出。
/// Takes a single pointer to a Sensor and displays its current reading.
/// 接受指向传感器的单个指针并显示其当前读数。
fn report(label: []const u8, ptr: *Sensor) void {
    std.debug.print("{s} -> reading {d}\n", .{ label, ptr.reading });
}

/// Demonstrates pointer fundamentals, optional pointers, and many-item pointers in Zig.
/// 演示Zig中的指针基础、可选指针和多项指针。
/// This example covers:
/// - Single-item pointers (*T) and pointer dereferencing
/// - 单项指针（*T）和指针解引用
/// - Pointer aliasing and mutation through aliases
/// - 指针别名和通过别名进行修改
/// - Optional pointers (?*T) for representing nullable references
/// - 代表可空引用的可选指针（?*T）
/// - Unwrapping optional pointers with if statements
/// - 使用if语句解包可选指针
/// - Many-item pointers ([*]T) for unchecked multi-element access
/// - 用于unchecked多元素访问的多项指针（[*]T）
/// - Converting slices to many-item pointers via .ptr property
/// - 通过.ptr属性将切片转换为多项指针
pub fn main() !void {
    // Create a sensor instance on the stack
    // 在栈上创建传感器实例
    var sensor = Sensor{ .reading = 41 };

    // Create a single-item pointer alias to the sensor
    // 创建指向传感器的单项指针别名
    // The & operator takes the address of sensor
    // &运算符获取sensor的地址
    var alias: *Sensor = &sensor;

    // Modify the sensor through the pointer alias
    // 通过指针别名修改传感器
    // Zig automatically dereferences pointer fields
    // Zig自动解引用指针字段
    alias.reading += 1;

    report("alias", alias);

    // Declare an optional pointer initialized to null
    // 声明初始化为null的可选指针
    // ?*T represents a pointer that may or may not hold a valid address
    // ?*T表示可能持有或可能不持有有效地址的指针
    var maybe_alias: ?*Sensor = null;

    // Attempt to unwrap the optional pointer
    // 尝试解包可选指针
    // This branch will not execute because maybe_alias is 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", .{});
    }

    // Assign a valid address to the optional pointer
    // 将有效地址分配给可选指针
    maybe_alias = &sensor;

    // Unwrap and use the optional pointer
    // 解包并使用可选指针
    // The |pointer| capture syntax extracts the non-null value
    // |pointer|捕获语法提取非null值
    if (maybe_alias) |pointer| {
        pointer.reading += 10;
        std.debug.print("optional pointer mutated to {d}\n", .{sensor.reading});
    }

    // Create an array and a slice view of it
    // 创建数组及其切片视图
    var samples = [_]i32{ 5, 7, 9, 11 };
    const view: []i32 = samples[0..];

    // Extract a many-item pointer from the slice
    // 从切片中提取多项指针
    // Many-item pointers ([*]T) allow unchecked indexing without length tracking
    // 多项指针（[*]T）允许在无需长度跟踪的情况下进行unchecked索引
    const many: [*]i32 = view.ptr;

    // Modify the underlying array through the many-item pointer
    // 通过多项指针修改底层数组
    // No bounds checking is performed at this point
    // 此时不执行边界检查
    many[2] = 42;

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

const std = @import("std");

/// Demonstrates memory alignment concepts and various type casting operations in Zig.
/// 演示Zig中的内存对齐概念和各种类型转换操作。
/// This example covers:
/// - Memory alignment guarantees with align() attribute
/// - 使用align()属性的内存对齐保证
/// - Pointer casting with alignment adjustments using @alignCast
/// - 使用@alignCast的指针转换和对齐调整
/// - Type punning with @ptrCast for reinterpreting memory
/// - 使用@ptrCast进行类型转换以重新解释内存
/// - Bitwise reinterpretation with @bitCast
/// - 使用@bitCast进行按位重新解释
/// - Truncating integers with @truncate
/// - 使用@truncate截断整数
/// - Widening integers with @intCast
/// - 使用@intCast扩展整数
/// - Floating-point precision conversion with @floatCast
/// - 使用@floatCast进行浮点精度转换
pub fn main() !void {
    // Create a byte array aligned to u64 boundary, initialized with little-endian bytes
    // 创建对齐到u64边界的字节数组，用小端字节初始化
    // representing 0x11223344 in the first 4 bytes
    // 在前4个字节中表示0x11223344
    var raw align(@alignOf(u64)) = [_]u8{ 0x44, 0x33, 0x22, 0x11, 0, 0, 0, 0 };

    // Get a pointer to the first byte with explicit u64 alignment
    // 获取具有显式u64对齐的第一个字节的指针
    const base: *align(@alignOf(u64)) u8 = &raw[0];

    // Adjust alignment constraint from u64 to u32 using @alignCast
    // 使用@alignCast将对齐约束从u64调整为u32
    // This is safe because u64 alignment (8 bytes) satisfies u32 alignment (4 bytes)
    // 这是安全的，因为u64对齐（8字节）满足u32对齐（4字节）
    const aligned_bytes = @as(*align(@alignOf(u32)) const u8, @alignCast(base));

    // Reinterpret the byte pointer as a u32 pointer to read 4 bytes as a single integer
    // 将字节指针重新解释为u32指针，将4字节作为单个整数读取
    const word_ptr = @as(*const u32, @ptrCast(aligned_bytes));

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

    // Alternative approach: directly reinterpret the first 4 bytes using @bitCast
    // 替代方法：使用@bitCast直接重新解释前4个字节
    // This creates a copy and doesn't require pointer manipulation
    // 这会创建一个副本，不需要指针操作
    const from_bytes = @as(u32, @bitCast(raw[0..4].*));
    std.debug.print("bitcast copy = 0x{X:0>8}\n", .{from_bytes});

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

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

    // Demonstrate @floatCast: reduce f64 precision to f32
    // 演示@floatCast：将f64精度降低到f32
    // May result in precision loss for values that cannot be exactly represented in f32
    // 对于无法在f32中精确表示的值，可能会导致精度损失
    const ratio64: f64 = 1.875;
    const ratio32: f32 = @as(f32, @floatCast(ratio64));
    std.debug.print("floatCast ratio -> {}\n", .{ratio32});
}