book: fill Chapter 10 (C++20) and fix Contracts/TM factual errors

changkun · changkun · commit 328e8dcd48bc · 2026-06-07T17:26:51.000+02:00
Replace the TODO stubs in the C++20 chapter with real content: - Concepts: a concrete, compiled requires-expression example - Modules: export/import syntax, with a note that it needs a module-aware multi-step build (not the repo one-liner) - Ranges: lazy filter|transform pipeline (compiled, code/10/10.3) - Coroutines: a minimal co_yield generator (compiled, code/10/10.4) - Correct two factual errors: Contracts were removed from C++20 (now targeting C++26, see #318) and Transactional Memory is only a TS, never part of C++20; they are no longer presented as C++20. Refs #1
diff --git a/book/en-us/10-cpp20.md b/book/en-us/10-cpp20.md
@@ -64,25 +64,132 @@ Even use it directly as a type:
 void sort(Sortable& c); // c is a Sortable type object
 ```
 
-Let's look at a practical example.
+Let's look at a practical example. The following uses a `requires` expression to define a concept `Addable`, requiring that a type support `+` with a result convertible back to the type, and uses it to constrain a function template:
 
-TODO:
+```cpp
+#include <concepts>
+#include <iostream>
+
+// Concept: T must support a + b, with a result convertible to T
+template <typename T>
+concept Addable = requires(T a, T b) {
+    { a + b } -> std::convertible_to<T>;
+};
 
-## Module
+template <Addable T>
+T sum(T a, T b) { return a + b; }
 
-TODO:
+int main() {
+    std::cout << sum(1, 2) << std::endl;     // 3
+    std::cout << sum(1.5, 2.5) << std::endl; // 4
+    // sum("a", "b"); // compile error: does not satisfy Addable, with a clear message
+}
+```
+
+When an argument of an unsatisfying type is passed, the compiler tells us directly that the constraint is not satisfied, instead of emitting a long cascade of internal template-instantiation errors.
+
+## Modules
+
+Modules aim to solve the many problems of the traditional header mechanism: repeated parsing, macro pollution, include-order sensitivity, and slow compilation. A module is declared with `export module` and explicitly `export`s the entities visible to the outside:
+
+```cpp
+// math.cppm — module interface unit
+export module math;
+
+export int add(int a, int b) {
+    return a + b;
+}
+```
+
+Consumers use `import` instead of `#include`:
+
+```cpp
+// main.cpp
+import math;
+import <iostream>;
+
+int main() {
+    std::cout << add(1, 2) << std::endl;
+}
+```
 
-## Contract
+> Unlike the other examples in this book, compiling modules requires dedicated toolchain support and usually two steps (compile the module interface unit first, then the consumer); it cannot be built with a single `clang++ file.cpp` command. Consult your compiler's documentation for the exact build procedure.
 
-TODO:
+## Ranges
+
+Ranges provide a higher-level, composable abstraction over the standard-library algorithms and iterators. With **range adaptors** and the pipe operator `|`, several lazy transformations can be chained in a declarative style:
+
+```cpp
+#include <iostream>
+#include <vector>
+#include <ranges>
+
+int main() {
+    std::vector<int> v{1, 2, 3, 4, 5, 6};
+    auto result = v | std::views::filter([](int x) { return x % 2 == 0; })
+                    | std::views::transform([](int x) { return x * x; });
+    for (int x : result) std::cout << x << ' '; // 4 16 36
+    std::cout << std::endl;
+}
+```
+
+These views are **lazily evaluated**: the filtering and transformation are computed element by element only when `result` is iterated, with no intermediate container created.
+
+## Coroutines
+
+A coroutine is a function that can be suspended and resumed. Any function whose body uses `co_await`, `co_yield`, or `co_return` is a coroutine. Note that C++20 provides only the **language machinery** plus the low-level support facilities in `<coroutine>`, leaving the "glue" such as the `promise_type` to the user or a library (a ready-made `std::generator` only arrived in C++23).
+
+Here is a minimal lazy generator that yields values one at a time with `co_yield`:
+
+```cpp
+#include <coroutine>
+#include <iostream>
+#include <optional>
+
+template <typename T>
+struct Generator {
+    struct promise_type {
+        T current;
+        Generator get_return_object() { return Generator{handle::from_promise(*this)}; }
+        std::suspend_always initial_suspend() { return {}; }
+        std::suspend_always final_suspend() noexcept { return {}; }
+        std::suspend_always yield_value(T value) { current = value; return {}; }
+        void return_void() {}
+        void unhandled_exception() { std::terminate(); }
+    };
+    using handle = std::coroutine_handle<promise_type>;
+    handle h;
+    explicit Generator(handle h) : h(h) {}
+    ~Generator() { if (h) h.destroy(); }
+    Generator(const Generator&) = delete;
+    Generator(Generator&& o) noexcept : h(o.h) { o.h = {}; }
+    std::optional<T> next() {
+        if (!h || h.done()) return std::nullopt;
+        h.resume();
+        if (h.done()) return std::nullopt;
+        return h.promise().current;
+    }
+};
+
+Generator<int> range(int a, int b) {
+    for (int i = a; i < b; ++i) co_yield i;
+}
+
+int main() {
+    auto g = range(1, 5);
+    while (auto v = g.next()) std::cout << *v << ' '; // 1 2 3 4
+    std::cout << std::endl;
+}
+```
 
-## Range
+## A note on Contracts and Transactional Memory
 
-TODO:
+A common misconception is worth clarifying: **Contracts** and **Transactional Memory** are *not* part of C++20.
 
-## Coroutine
+- Contracts were once in the C++20 working draft but were removed before the standard was published; they are now an important feature targeting C++26 (see this repository's C++26 tracking issue #318).
+- Transactional Memory exists only as a Technical Specification (TS) and was never merged into the C++20 standard.
 
-TODO:
+This chapter therefore no longer presents them as C++20 features.
 
 ## Conclusion
 
diff --git a/book/zh-cn/10-cpp20.md b/book/zh-cn/10-cpp20.md
@@ -53,30 +53,132 @@ void sort(T& c)
 void sort(Sortable& c); // c 是一个 Sortable 类型的对象
 ```
 
-我们现在来看一个实际的例子。
+我们现在来看一个实际的例子。下面用 `requires` 表达式定义一个概念 `Addable`，要求类型支持 `+` 运算且结果可转换回该类型，并用它来约束函数模板：
 
-TODO: https://godbolt.org/z/9liFPD
+```cpp
+#include <concepts>
+#include <iostream>
+
+// 定义概念：T 必须支持 a + b，且结果可转换为 T
+template <typename T>
+concept Addable = requires(T a, T b) {
+    { a + b } -> std::convertible_to<T>;
+};
+
+template <Addable T>
+T sum(T a, T b) { return a + b; }
+
+int main() {
+    std::cout << sum(1, 2) << std::endl;     // 3
+    std::cout << sum(1.5, 2.5) << std::endl; // 4
+    // sum("a", "b"); // 编译错误：不满足 Addable，错误信息清晰明了
+}
+```
+
+当传入不满足约束的类型时，编译器会直接告诉我们「约束不满足」，而不是抛出一长串模板实例化的内部错误。
 
 ## 模块
 
-TODO:
+模块（Modules）旨在解决传统头文件机制带来的诸多问题：重复解析、宏污染、包含顺序敏感以及缓慢的编译速度。一个模块用 `export module` 声明，并显式地 `export` 对外可见的实体：
 
-## 合约
+```cpp
+// math.cppm —— 模块接口单元
+export module math;
+
+export int add(int a, int b) {
+    return a + b;
+}
+```
+
+使用方则用 `import` 代替 `#include`：
+
+```cpp
+// main.cpp
+import math;
+import <iostream>;
+
+int main() {
+    std::cout << add(1, 2) << std::endl;
+}
+```
 
-TODO:
+> 与本书其他示例不同，模块的编译需要工具链的专门支持，并且通常要分两步（先编译模块接口单元、再编译使用方），无法用 `clang++ file.cpp` 这样的单条命令直接构建。具体的构建方式请参阅你所用编译器的文档。
 
 ## 范围
 
-TODO:
+范围（Ranges）为标准库的算法与迭代器提供了更高层、可组合的抽象。借助**范围适配器 (range adaptors)** 与管道运算符 `|`，我们可以把多个惰性变换串联起来，代码更具声明式风格：
+
+```cpp
+#include <iostream>
+#include <vector>
+#include <ranges>
+
+int main() {
+    std::vector<int> v{1, 2, 3, 4, 5, 6};
+    auto result = v | std::views::filter([](int x) { return x % 2 == 0; })
+                    | std::views::transform([](int x) { return x * x; });
+    for (int x : result) std::cout << x << ' '; // 4 16 36
+    std::cout << std::endl;
+}
+```
+
+这些视图都是**惰性求值**的：只有在真正遍历 `result` 时，过滤与变换才会逐元素地被计算，中间不会产生临时容器。
 
 ## 协程
 
-TODO:
+协程（Coroutines）是可以被挂起与恢复的函数。一个函数只要在函数体中使用了 `co_await`、`co_yield` 或 `co_return`，它就是一个协程。需要强调的是，C++20 只提供了协程的**语言机制**以及 `<coroutine>` 中的底层支撑设施，而把 `promise_type` 这类「胶水」留给用户或库去实现（C++23 才提供了开箱即用的 `std::generator`）。
+
+下面是一个最小的惰性生成器，利用 `co_yield` 逐个产出值：
+
+```cpp
+#include <coroutine>
+#include <iostream>
+#include <optional>
+
+template <typename T>
+struct Generator {
+    struct promise_type {
+        T current;
+        Generator get_return_object() { return Generator{handle::from_promise(*this)}; }
+        std::suspend_always initial_suspend() { return {}; }
+        std::suspend_always final_suspend() noexcept { return {}; }
+        std::suspend_always yield_value(T value) { current = value; return {}; }
+        void return_void() {}
+        void unhandled_exception() { std::terminate(); }
+    };
+    using handle = std::coroutine_handle<promise_type>;
+    handle h;
+    explicit Generator(handle h) : h(h) {}
+    ~Generator() { if (h) h.destroy(); }
+    Generator(const Generator&) = delete;
+    Generator(Generator&& o) noexcept : h(o.h) { o.h = {}; }
+    std::optional<T> next() {
+        if (!h || h.done()) return std::nullopt;
+        h.resume();
+        if (h.done()) return std::nullopt;
+        return h.promise().current;
+    }
+};
+
+Generator<int> range(int a, int b) {
+    for (int i = a; i < b; ++i) co_yield i;
+}
+
+int main() {
+    auto g = range(1, 5);
+    while (auto v = g.next()) std::cout << *v << ' '; // 1 2 3 4
+    std::cout << std::endl;
+}
+```
+
+## 关于合约与事务内存
 
+需要澄清一个常见的误解：**合约 (Contracts)** 与 **事务内存 (Transactional Memory)** 并不属于 C++20。
 
-## 事务内存
+- 合约曾被纳入 C++20 的工作草案，但在正式发布前被移除，目前作为一项重要特性正瞄准 C++26（参见本仓库的 C++26 追踪 issue #318）。
+- 事务内存只以技术规范 (Technical Specification, TS) 的形式存在，从未被合并进 C++20 标准。
 
-TODO:
+因此，本章不再将它们作为 C++20 的特性来介绍。
 
 ## 总结
 
diff --git a/code/10/10.3.ranges.cpp b/code/10/10.3.ranges.cpp
@@ -0,0 +1,24 @@
+//
+// 10.3.ranges.cpp
+// chapter 10 cpp20
+// modern c++ tutorial
+//
+// created by changkun at changkun.de
+// https://github.com/changkun/modern-cpp-tutorial
+//
+
+#include <iostream>
+#include <vector>
+#include <ranges>
+
+int main() {
+    std::vector<int> v{1, 2, 3, 4, 5, 6};
+
+    // Range adaptors compose lazily with the pipe operator: keep the
+    // even numbers, then square them. Nothing is computed until iterated.
+    auto result = v | std::views::filter([](int x) { return x % 2 == 0; })
+                    | std::views::transform([](int x) { return x * x; });
+
+    for (int x : result) std::cout << x << ' '; // 4 16 36
+    std::cout << std::endl;
+}
diff --git a/code/10/10.4.coroutine.cpp b/code/10/10.4.coroutine.cpp
@@ -0,0 +1,55 @@
+//
+// 10.4.coroutine.cpp
+// chapter 10 cpp20
+// modern c++ tutorial
+//
+// created by changkun at changkun.de
+// https://github.com/changkun/modern-cpp-tutorial
+//
+
+#include <coroutine>
+#include <iostream>
+#include <optional>
+
+// A minimal lazy generator coroutine. C++20 provides only the language
+// machinery (co_yield/co_await/co_return) plus the <coroutine> support
+// library; the user (or a library) supplies the promise_type. C++23
+// adds a ready-made std::generator.
+template <typename T>
+struct Generator {
+    struct promise_type {
+        T current;
+        Generator get_return_object() {
+            return Generator{handle::from_promise(*this)};
+        }
+        std::suspend_always initial_suspend() { return {}; }
+        std::suspend_always final_suspend() noexcept { return {}; }
+        std::suspend_always yield_value(T value) { current = value; return {}; }
+        void return_void() {}
+        void unhandled_exception() { std::terminate(); }
+    };
+    using handle = std::coroutine_handle<promise_type>;
+    handle h;
+    explicit Generator(handle h) : h(h) {}
+    ~Generator() { if (h) h.destroy(); }
+    Generator(const Generator&) = delete;
+    Generator(Generator&& o) noexcept : h(o.h) { o.h = {}; }
+
+    std::optional<T> next() {
+        if (!h || h.done()) return std::nullopt;
+        h.resume();
+        if (h.done()) return std::nullopt;
+        return h.promise().current;
+    }
+};
+
+Generator<int> range(int a, int b) {
+    for (int i = a; i < b; ++i)
+        co_yield i;
+}
+
+int main() {
+    auto g = range(1, 5);
+    while (auto v = g.next()) std::cout << *v << ' '; // 1 2 3 4
+    std::cout << std::endl;
+}
