Referenced Card Finished for m29 (#18)

Reference Card Finished

Author: Charliechen114514

documents/cpp-reference/concurrency/04-jthread.md

@@ -0,0 +1,90 @@
+---
+title: "std::jthread"
+description: "自动 join 的线程类，析构时发送停止请求并等待线程退出"
+chapter: 99
+order: 4
+tags:
+  - host
+  - cpp-modern
+  - beginner
+difficulty: beginner
+cpp_standard: [20, 23]
+---
+
+<!--
+参考卡模板 (Reference Card Template)
+用于 documents/cpp-reference/ 下的特性速查页。
+与 article-template.md 不同，参考卡走精炼的结构化格式，不需要叙事风格。
+
+标签使用规则：
+1. 必须包含 1 个 platform 标签（参考卡统一用 host）
+2. 必须包含 1 个 difficulty 标签
+3. 至少包含 1 个 topic 标签
+4. 从 scripts/validate_frontmatter.py 的 VALID_TAGS 集合中选取
+-->
+
+# std::jthread（C++20）
+
+## 一句话
+
+自带 RAII 语义的线程类——析构时自动发送停止请求并 join，彻底消灭忘记 join 导致的 crash。
+
+## 头文件
+
+`#include <thread>`
+
+## 核心 API 速查
+
+| 操作 | 签名 | 说明 |
+|------|------|------|
+| 构造（带函数） | `template<class F> jthread(F&& f, Args&&... args)` | 启动新线程执行 f(args...) |
+| 构造（带 stop_token） | `template<class F> jthread(F&& f)` | f 的首参接收 `std::stop_token` |
+| 析构 | `~jthread()` | 请求停止 + join（若 joinable） |
+| 请求停止 | `bool request_stop() noexcept` | 请求协作式停止，返回是否成功 |
+| 获取停止令牌 | `std::stop_token get_stop_token() const noexcept` | 获取当前线程的停止令牌 |
+| 等待完成 | `void join()` | 阻塞等待线程结束 |
+| 分离线程 | `void detach()` | 分离，线程独立运行 |
+| 是否可 join | `bool joinable() const noexcept` | 检查线程是否可 join |
+| 获取 ID | `std::thread::id get_id() const noexcept` | 返回线程标识 |
+
+## 最小示例
+
+```cpp
+// Standard: C++20
+#include <iostream>
+#include <thread>
+
+void worker(std::stop_token st) {
+    while (!st.stop_requested()) {
+        std::cout << "working...\n";
+    }
+    std::cout << "stopped\n";
+}
+
+int main() {
+    std::jthread t(worker); // 自动传入 stop_token
+    // t 析构时自动 request_stop() + join()
+} // 输出: working... stopped
+```
+
+## 嵌入式适用性：中
+
+- RAII 自动 join 消除忘记 join 的隐患，提升代码健壮性
+- `std::stop_token` 协作式取消机制比手工标志变量更规范
+- 依赖操作系统线程支持，裸机 RTOS 场景需配合线程抽象层使用
+- 需要 C++20 标准库支持，GCC 10+ 即可用，但 Clang/libc++ 支持较晚（17+）
+
+## 编译器支持
+
+| GCC | Clang | MSVC |
+|-----|-------|------|
+| 10 | 17 | 19.28 |
+
+## 另见
+
+- [cppreference: std::jthread](https://en.cppreference.com/w/cpp/thread/jthread)
+- [cppreference: std::stop_token](https://en.cppreference.com/w/cpp/thread/stop_token)
+
+---
+
+*部分内容参考自 [cppreference.com](https://en.cppreference.com/)，采用 [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) 许可*

documents/cpp-reference/concurrency/index.md

@@ -15,4 +15,5 @@ tags:
   <ChapterLink href="01-atomic">std::atomic</ChapterLink>
   <ChapterLink href="02-thread">std::thread</ChapterLink>
   <ChapterLink href="03-mutex">std::mutex</ChapterLink>
+  <ChapterLink href="04-jthread">std::jthread</ChapterLink>
 </ChapterNav>

documents/cpp-reference/containers/06-filesystem.md

@@ -0,0 +1,95 @@
+---
+title: "std::filesystem"
+description: "跨平台的文件系统操作库：路径操作、目录遍历、文件状态查询"
+chapter: 99
+order: 6
+tags:
+  - host
+  - cpp-modern
+  - beginner
+difficulty: beginner
+cpp_standard: [17, 20, 23]
+---
+
+<!--
+参考卡模板 (Reference Card Template)
+用于 documents/cpp-reference/ 下的特性速查页。
+与 article-template.md 不同，参考卡走精炼的结构化格式，不需要叙事风格。
+
+标签使用规则：
+1. 必须包含 1 个 platform 标签（参考卡统一用 host）
+2. 必须包含 1 个 difficulty 标签
+3. 至少包含 1 个 topic 标签
+4. 从 scripts/validate_frontmatter.py 的 VALID_TAGS 集合中选取
+-->
+
+# std::filesystem（C++17）
+
+## 一句话
+
+平台无关的文件系统操作库：路径拼接与规范化、目录创建与遍历、文件复制与删除、权限与状态查询——告别 `stat()` 和 `opendir()`。
+
+## 头文件
+
+`#include <filesystem>`
+
+## 核心 API 速查
+
+| 操作 | 签名 | 说明 |
+|------|------|------|
+| 路径类 | `class path` | 路径的构造、拼接、分解（跨平台分隔符处理） |
+| 路径拼接 | `path operator/(const path& lhs, const path& rhs)` | `p / "subdir" / "file.txt"` |
+| 当前路径 | `path current_path()` | 获取/设置工作目录 |
+| 目录迭代 | `class directory_iterator` | 遍历单层目录 |
+| 递归迭代 | `class recursive_directory_iterator` | 递归遍历子目录 |
+| 文件状态 | `bool exists(const path& p)` | 检查路径是否存在 |
+| 文件大小 | `uintmax_t file_size(const path& p)` | 获取文件字节数 |
+| 创建目录 | `bool create_directory(const path& p)` | 创建单个目录 |
+| 创建多级目录 | `bool create_directories(const path& p)` | 递归创建整个路径 |
+| 复制文件 | `bool copy_file(const path& from, const path& to)` | 复制单个文件 |
+| 删除 | `bool remove(const path& p)` | 删除文件或空目录 |
+| 递归删除 | `uintmax_t remove_all(const path& p)` | 递归删除目录及内容 |
+| 重命名 | `void rename(const path& old, const path& newp)` | 重命名或移动 |
+
+## 最小示例
+
+```cpp
+// Standard: C++17
+#include <filesystem>
+#include <iostream>
+
+namespace fs = std::filesystem;
+
+int main() {
+    fs::path p = fs::current_path() / "test.txt";
+    std::cout << p << "\n";                      // 完整路径
+    std::cout << p.filename() << "\n";           // test.txt
+    std::cout << p.extension() << "\n";          // .txt
+
+    fs::create_directories("a/b/c");             // 递归创建
+    std::cout << fs::exists("a/b") << "\n";      // true
+    fs::remove_all("a");                         // 递归删除
+}
+```
+
+## 嵌入式适用性：低
+
+- 依赖操作系统文件系统抽象层（POSIX 或 Win32），裸机环境无文件系统
+- 适用于嵌入式 Linux（如 Buildroot/Yocto 平台）或上位机配置/日志工具
+- 头文件引入的开销较大，资源极度受限的设备不建议使用
+- 对需要文件系统的嵌入式场景（如 FAT32 on SD card），可选用轻量级替代（如 LittleFS）
+
+## 编译器支持
+
+| GCC | Clang | MSVC |
+|-----|-------|------|
+| 8 | 7 | 19.12 |
+
+## 另见
+
+- [教程：std::filesystem](../../vol2-modern-features/ch09-filesystem/01-filesystem-path.md)
+- [cppreference: std::filesystem](https://en.cppreference.com/w/cpp/filesystem)
+
+---
+
+*部分内容参考自 [cppreference.com](https://en.cppreference.com/)，采用 [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) 许可*

documents/cpp-reference/containers/07-format.md

@@ -0,0 +1,91 @@
+---
+title: "std::format"
+description: "类型安全、可扩展的格式化输出库，替代 printf 和 stringstream"
+chapter: 99
+order: 7
+tags:
+  - host
+  - cpp-modern
+  - beginner
+difficulty: beginner
+cpp_standard: [20, 23]
+---
+
+<!--
+参考卡模板 (Reference Card Template)
+用于 documents/cpp-reference/ 下的特性速查页。
+与 article-template.md 不同，参考卡走精炼的结构化格式，不需要叙事风格。
+
+标签使用规则：
+1. 必须包含 1 个 platform 标签（参考卡统一用 host）
+2. 必须包含 1 个 difficulty 标签
+3. 至少包含 1 个 topic 标签
+4. 从 scripts/validate_frontmatter.py 的 VALID_TAGS 集合中选取
+-->
+
+# std::format（C++20）
+
+## 一句话
+
+类型安全的 `printf` 替代品——用 `{}` 占位符格式化字符串，编译期检查参数数量，支持自定义类型格式化。
+
+## 头文件
+
+`#include <format>`
+
+## 核心 API 速查
+
+| 操作 | 签名 | 说明 |
+|------|------|------|
+| 格式化字符串 | `string format(fmt, args...)` | 返回格式化后的字符串 |
+| 格式化到输出 | `void vformat_to(out_it, fmt, args)` | 输出到迭代器 |
+| 格式化到缓冲区 | `size_t formatted_size(fmt, args...)` | 预计算输出长度 |
+| 格式化到 stdout | (C++23) `void print(fmt, args...)` | 直接输出到标准输出 |
+| 位置参数 | `"{0} {1} {0}"` | 按序号引用参数 |
+| 宽度/精度 | `"{:>10.2f}"` | 右对齐、宽度 10、精度 2 |
+| 自定义格式化 | `template<> struct formatter<T>` | 特化 `std::formatter` 支持自定义类型 |
+
+## 最小示例
+
+```cpp
+// Standard: C++20
+#include <format>
+#include <iostream>
+#include <string>
+
+int main() {
+    std::string s = std::format("Hello, {}!", "world");
+    std::cout << s << "\n"; // Hello, world!
+
+    int version = 2;
+    double pi = 3.14159265;
+    std::cout << std::format("v{}. pi={:.2f}", version, pi) << "\n";
+    // v2. pi=3.14
+
+    // 位置参数
+    std::cout << std::format("{0} + {0} = {1}", 3, 6) << "\n";
+    // 3 + 3 = 6
+}
+```
+
+## 嵌入式适用性：中
+
+- 替代 `printf`，消除格式字符串与参数类型不匹配的运行时崩溃风险
+- 替代 `std::stringstream`，避免堆分配开销
+- 编译期检查参数数量，但格式说明符的完整编译期验证需要 C++23 的 `std::is_constant_evaluated` 配合
+- Flash 开销可能较大（格式化引擎代码量），资源极度受限设备需评估
+- 可用 [{fmt}](https://github.com/fmtlib/fmt) 库作为 C++11 起的后备方案
+
+## 编译器支持
+
+| GCC | Clang | MSVC |
+|-----|-------|------|
+| 13 | 17 | 19.29 |
+
+## 另见
+
+- [cppreference: std::format](https://en.cppreference.com/w/cpp/utility/format)
+
+---
+
+*部分内容参考自 [cppreference.com](https://en.cppreference.com/)，采用 [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) 许可*

documents/cpp-reference/containers/08-flat-map.md

@@ -0,0 +1,92 @@
+---
+title: "std::flat_map"
+description: "基于连续存储的有序关联容器，缓存友好的 std::map 替代品"
+chapter: 99
+order: 8
+tags:
+  - host
+  - cpp-modern
+  - beginner
+difficulty: beginner
+cpp_standard: [23]
+---
+
+<!--
+参考卡模板 (Reference Card Template)
+用于 documents/cpp-reference/ 下的特性速查页。
+与 article-template.md 不同，参考卡走精炼的结构化格式，不需要叙事风格。
+
+标签使用规则：
+1. 必须包含 1 个 platform 标签（参考卡统一用 host）
+2. 必须包含 1 个 difficulty 标签
+3. 至少包含 1 个 topic 标签
+4. 从 scripts/validate_frontmatter.py 的 VALID_TAGS 集合中选取
+-->
+
+# std::flat_map（C++23）
+
+## 一句话
+
+用连续数组替代红黑树的有序映射——查找更快（缓存友好），内存更紧凑，但插入/删除是 O(n)。
+
+## 头文件
+
+`#include <flat_map>`
+
+## 核心 API 速查
+
+| 操作 | 签名 | 说明 |
+|------|------|------|
+| 访问元素 | `V& operator[](const K& key)` | 按键访问，不存在则插入默认值 |
+| 查找 | `iterator find(const K& key)` | 返回指向元素的迭代器 |
+| 插入 | `pair<iterator, bool> insert(const value_type&)` | 插入键值对 |
+| 删除 | `size_t erase(const K& key)` | 按键删除元素 |
+| 元素数量 | `size_t size() const` | 返回元素个数 |
+| 是否为空 | `bool empty() const` | 检查是否为空 |
+| 清空 | `void clear()` | 清除所有元素 |
+| 迭代 | `iterator begin()` / `end()` | 按键序遍历 |
+| 下界/上界 | `iterator lower_bound(const K&)` | 有序查找边界 |
+| 是否包含 | `bool contains(const K& key) const` | (C++20 起可用) 检查键是否存在 |
+
+## 最小示例
+
+```cpp
+// Standard: C++23
+#include <flat_map>
+#include <iostream>
+
+int main() {
+    std::flat_map<int, const char*> m;
+    m[1] = "one";
+    m[3] = "three";
+    m[2] = "two";
+
+    for (const auto& [k, v] : m) {
+        std::cout << k << ": " << v << "\n";
+    }
+    // 1: one  2: two  3: three  (按键序排列)
+
+    std::cout << std::boolalpha << m.contains(2) << "\n"; // true
+}
+```
+
+## 嵌入式适用性：中
+
+- 连续存储对 CPU 缓存友好，小数据集的查找性能远优于 `std::map`
+- 无节点分配器开销，内存碎片更少，适合堆空间受限的嵌入式环境
+- 插入/删除 O(n)，不适合频繁修改的大数据集
+- 编译器支持尚在推进中（GCC 15+、Clang 20+、MSVC 19.51+），生产环境需评估工具链
+
+## 编译器支持
+
+| GCC | Clang | MSVC |
+|-----|-------|------|
+| 15 | 20 | 19.51 |
+
+## 另见
+
+- [cppreference: std::flat_map](https://en.cppreference.com/w/cpp/container/flat_map)
+
+---
+
+*部分内容参考自 [cppreference.com](https://en.cppreference.com/)，采用 [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) 许可*