update: 补充指针章节内容

Author: jinzhongjia

course/basic/advanced_type/pointer.md

@@ -10,7 +10,7 @@ outline: deep
 
 **取地址**：通过 `&` 符号来获取某个变量所对应的内存地址，如 `&integer` 就是获取变量 `integer` 的内存地址。
 
-与 C 不同，Zig 中的指针类型有多种，主要是对指向的元素做了区分，便于更好地使用。下图展示了它们指向元素的不同：
+与 C 不同，Zig 中的指针类型要分为两种（一种是单项指针，一种是多项指针），它们主要是对指向的元素做了区分，便于更好地使用。下图展示了它们指向元素的不同：
 
 ![pointer representation](/picture/basic/pointer-representation.svg)
 
@@ -36,23 +36,32 @@ zig 本身支持指针运算（加减操作），但有一点需要注意：最
 
 <<<@/code/release/pointer.zig#single_pointer
 
+单项指针本身支持以下操作：
+
+- 解引用语法 `ptr.*`
+- 切片语法 `ptr[0..1]`
+- 指针减法 `ptr - ptr`
+
 :::info 🅿️ 提示
 
-函数指针略有特殊：`const Call2Op = *const fn (a: i8, b: i8) i8;`
+函数指针略有特殊：
+
+<<<@/code/release/pointer.zig#fn_pointer
 
 :::
 
 ## 多项指针
 
-多项指针指向位置数量的多个元素。
+多项指针指向未知数量的多个元素。
 
 多项指针的类型为：`[*]T`，`T`是所指向内存区域的类型，且该类型必须具有明确的大小（这意味着它不能是 [`anyopaque`](https://ziglang.org/documentation/master/#toc-C-Type-Primitives) 和其他任意[不透明类型](https://ziglang.org/documentation/master/#opaque)）。
 
 解引用方法支持以下几种：
 
 - 索引语法 `ptr[i]`
-- 切片语法 `ptr[start..end]`
-- 指针运算 `ptr + x`，`ptr - x`
+- 切片语法 `ptr[start..end]` 和 `ptr[start..]`
+- 指针运算 `ptr + int`, `ptr - int`
+- 指针减法 `ptr - ptr`
 
 <<<@/code/release/pointer.zig#multi_pointer
 
@@ -62,9 +71,21 @@ zig 本身支持指针运算（加减操作），但有一点需要注意：最
 
 `*[N]T`：这是指向一个数组的单项指针，数组的长度为 N。也可以将其理解为指向 N 个元素的指针。
 
+支持这些语法：
+
+- 索引语法：`array_ptr[i]`
+- 切片语法：`array_ptr[start..end]`
+- `len` 属性：`array_ptr.len`
+- 指针减法：`array_ptr - array_ptr`
+
 `[]T`：这是切片，相当于一个胖指针，包含了一个类型为 `[*]T` 的指针和一个长度。
 
-数组指针的类型中就包含了长度信息，而切片中则实际存储着长度。数组指针和切片的长度都可以通过 `len` 属性来获取。
+支持这些语法：
+
+- 索引语法：`slice[i]`
+- 切片语法：`slice[start..end]`
+- `len` 属性：`slice.len`
+  数组指针的类型中就包含了长度信息，而切片中则实际存储着长度。数组指针和切片的长度都可以通过 `len` 属性来获取。
 
 :::details 示例
 
@@ -122,6 +143,20 @@ zig 本身支持指针运算（加减操作），但有一点需要注意：最
 
 其中 `[*] const u8` 可以看作是 C 中的 `* const char`，这是因为在 C 语言中一个普通的指针也可以指向一个数组，zig 仅仅是单独把这种令人迷惑的行为单独作为一个语法而已！
 
+## 指针和整数互转
+
+[`@ptrFromInt`](https://ziglang.org/documentation/master/#ptrFromInt) 可以将整数地址转换为指针，[`@intFromPtr`](https://ziglang.org/documentation/master/#intFromPtr) 可以将指针转换为整数：
+
+<<<@/code/release/pointer.zig#ptr2int
+
+## 指针强制转换
+
+内置函数 [`@ptrCast`](https://ziglang.org/documentation/master/#ptrCast) 可以将将指针的元素类型转换为另一种类型，也就是不同类型的指针强制转换。
+
+一般情况下，应当尽量避免使用 `@ptrCast`，这会创建一个新的指针，根据通过它的加载和存储操作，可能导致无法检测的非法行为。
+
+<<<@/code/release/pointer.zig#ptr_cast
+
 ## 额外特性
 
 以下的是指针的额外特性，初学者可以直接略过以下部分，等到你需要时再来学习即可！
@@ -142,7 +177,7 @@ zig 本身支持指针运算（加减操作），但有一点需要注意：最
 
 > 如果你不知道内存对齐的含义是什么，那么本节内容你可以跳过了，等到你需要时再来查看！
 
-每种类型都有一个对齐方式——数个字节，这样，当从内存加载或存储该类型的值时，内存地址必须能被该数字整除。我们可以使用 `@alignOf` 找出任何类型的内存对齐大小。
+每种类型都有一个对齐方式——也就是数个字节，这样，当从内存加载或存储该类型的值时，内存地址必须能被该数字整除。我们可以使用 `@alignOf` 找出任何类型的内存对齐大小。
 
 内存对齐大小取决于 CPU 架构，但始终是 2 的幂，并且小于 1 << 29。
 :::info
@@ -168,6 +203,51 @@ zig 本身支持指针运算（加减操作），但有一点需要注意：最
 
 :::
 
+如果有一个指针或切片，它的对齐很小，但我们知道它实际上有一个更大的对齐，那么使用 [`@alignCast`](https://ziglang.org/documentation/master/#alignCast) 让其 `align` 更大。在运行时是无操作的，但会额外加入一个 [安全检查](https://ziglang.org/documentation/master/#Incorrect-Pointer-Alignment)：
+
+> 例如这段代码就是错误的，不会被正常执行
+
+```zig
+const std = @import("std");
+
+test "pointer alignment safety" {
+    var array align(4) = [_]u32{ 0x11111111, 0x11111111 };
+    const bytes = std.mem.sliceAsBytes(array[0..]);
+    try std.testing.expect(foo(bytes) == 0x11111111);
+}
+fn foo(bytes: []u8) u32 {
+    const slice4 = bytes[1..5];
+    const int_slice = std.mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
+    return int_slice[0];
+}
+```
+
+```sh
+$ zig test test_incorrect_pointer_alignment.zig
+1/1 test_incorrect_pointer_alignment.test.pointer alignment safety...thread 958173 panic: incorrect alignment
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_incorrect_pointer_alignment.zig:10:68: 0x1048962 in foo (test)
+    const int_slice = std.mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
+                                                                   ^
+/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_incorrect_pointer_alignment.zig:6:31: 0x104880f in test.pointer alignment safety (test)
+    try std.testing.expect(foo(bytes) == 0x11111111);
+                              ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:214:25: 0x10efab9 in mainTerminal (test)
+        if (test_fn.func()) |_| {
+                        ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:62:28: 0x10e7ead in main (test)
+        return mainTerminal();
+                           ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:647:22: 0x10e7430 in posixCallMainAndExit (test)
+            root.main();
+                     ^
+/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:271:5: 0x10e6ffd in _start (test)
+    asm volatile (switch (native_arch) {
+    ^
+???:?:?: 0x0 in ??? (???)
+error: the following test command crashed:
+/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/608e4a8451ecb0974638281c85927599/test --seed=0x9bc870fd
+```
+
 ### 零指针
 
 零指针实际上是一个未定义的错误行为（[Pointer Cast Invalid Null](https://ziglang.org/documentation/master/#Pointer-Cast-Invalid-Null)），但是当我们给指针增加上 `allowzero` 修饰符后，它就变成合法的行为了！
@@ -185,3 +265,7 @@ zig 本身支持指针运算（加减操作），但有一点需要注意：最
 只要代码不依赖于未定义的内存布局，那么指针也可以在编译期发挥作用！
 
 <<<@/code/release/pointer.zig#comptime_pointer
+
+只要指针从未被取消引用，Zig 就能够保留 `comptime` 代码中的内存地址：
+
+<<<@/code/release/pointer.zig#comp_pointer

course/code/14/pointer.zig

@@ -9,6 +9,8 @@ pub fn main() !void {
     try AlignCast.main();
     try ZeroPointer.main();
     ComptimePointer.main();
+    ptr2int.main();
+    try compPointer.main();
 }
 
 const SinglePointer = struct {
@@ -24,6 +26,34 @@ const SinglePointer = struct {
     }
     // #endregion single_pointer
 };
+
+const fnPointer = struct {
+    // #region fn_pointer
+    const Call2Op = *const fn (a: i8, b: i8) i8;
+    // Call20p 是一个函数指针类型，指向一个接受两个 i8 类型参数并返回 i8 类型的函数
+    // #endregion fn_pointer
+};
+
+const ptr2int = struct {
+    pub fn main() void {
+        // #region ptr2int
+        const std = @import("std");
+
+        // ptrFromInt 将整数转换为指针
+        const ptr: *i32 = @ptrFromInt(0xdeadbee0);
+        // intFromPtr 将指针转换为整数
+        const addr = @intFromPtr(ptr);
+
+        if (@TypeOf(addr) == usize) {
+            std.debug.print("success\n", .{});
+        }
+        if (addr == 0xdeadbee0) {
+            std.debug.print("success\n", .{});
+        }
+        // #endregion ptr2int
+    }
+};
+
 const MultiPointer = struct {
     // #region multi_pointer
     const print = @import("std").debug.print;
@@ -192,3 +222,45 @@ const ComptimePointer = struct {
     }
     // #endregion comptime_pointer
 };
+
+const compPointer = struct {
+    pub fn main() !void {
+        // #region comp_pointer
+        comptime {
+            const expect = @import("std").testing.expect;
+            // 只要指针不被解引用，那么就可以这么做
+            const ptr: *i32 = @ptrFromInt(0xdeadbee0);
+            const addr = @intFromPtr(ptr);
+            try expect(@TypeOf(addr) == usize);
+            try expect(addr == 0xdeadbee0);
+        }
+        // #endregion comp_pointer
+    }
+};
+
+const ptrCast = struct {
+    const std = @import("std");
+    pub fn main() !void {
+        // #region ptr_cast
+        const bytes align(@alignOf(u32)) = [_]u8{ 0x12, 0x12, 0x12, 0x12 };
+        // 将 u8数组指针 转换为 u32 类型的指针
+        const u32_ptr: *const u32 = @ptrCast(&bytes);
+
+        if (u32_ptr.* == 0x12121212) {
+            std.debug.print("success\n", .{});
+        }
+
+        // 通过标准库转为 u32
+        const u32_value = std.mem.bytesAsSlice(u32, bytes[0..])[0];
+
+        if (u32_value == 0x12121212) {
+            std.debug.print("success\n", .{});
+        }
+
+        // 通过内置函数转换
+        if (@as(u32, @bitCast(bytes)) == 0x12121212) {
+            std.debug.print("success\n", .{});
+        }
+        // #endregion ptr_cast
+    }
+};