feat: better float explanations (#107)

Author: Charliechen114514

code/examples/vol1/c_float_representation.c

@@ -0,0 +1,31 @@
+#include <stdio.h>
+#include <string.h>
+
+/* 浮点数为什么是近似值？把 0.1f 的 32 个二进制位摊开看就明白了。 */
+int main(void) {
+    /* 1) float 只有 32 位：1 符号 + 8 指数 + 23 尾数 */
+    float f = 0.1f;
+    unsigned int bits;
+    memcpy(&bits, &f, sizeof(bits));
+
+    printf("0.1f 存进 float 的 32 个二进制位 (符号 | 指数 | 尾数):\n  ");
+    for (int i = 31; i >= 0; i--) {
+        printf("%d", (bits >> i) & 1);
+        if (i == 31 || i == 23)
+            printf(" ");
+    }
+    printf("\n\n");
+
+    /* 尾数 1001100110011... 是无限循环，23 位放不下只能截断，所以不是 0.1 */
+    printf("用不同精度打印它，都不是 0.1：\n");
+    printf("  9 位精度 : %.9f\n", f);
+    printf("  20 位精度: %.20f\n\n", f);
+
+    /* 2) 经典的 0.1 + 0.2 != 0.3 在 double 下才看得见 */
+    double a = 0.1, b = 0.2, c = 0.3;
+    printf("double: 0.1 + 0.2 == 0.3 ? %s\n", (a + b == c) ? "yes" : "no");
+    printf("  a + b = %.20f\n", a + b);
+    printf("  c     = %.20f\n", c);
+
+    return 0;
+}

code/examples/vol1/c_float_representation_en.c

@@ -0,0 +1,33 @@
+#include <stdio.h>
+#include <string.h>
+
+/* Why are floating-point numbers approximations? Spread out the 32 bits of 0.1f and it becomes
+ * clear. */
+int main(void) {
+    /* 1) float has only 32 bits: 1 sign + 8 exponent + 23 mantissa */
+    float f = 0.1f;
+    unsigned int bits;
+    memcpy(&bits, &f, sizeof(bits));
+
+    printf("32 bits of 0.1f in a float (sign | exponent | mantissa):\n  ");
+    for (int i = 31; i >= 0; i--) {
+        printf("%d", (bits >> i) & 1);
+        if (i == 31 || i == 23)
+            printf(" ");
+    }
+    printf("\n\n");
+
+    /* The mantissa 1001100110011... repeats forever; 23 bits can't hold it, so it gets truncated.
+     */
+    printf("Printed at different precisions — never exactly 0.1:\n");
+    printf("  9 digits : %.9f\n", f);
+    printf("  20 digits: %.20f\n\n", f);
+
+    /* 2) The classic 0.1 + 0.2 != 0.3 only shows up under double */
+    double a = 0.1, b = 0.2, c = 0.3;
+    printf("double: 0.1 + 0.2 == 0.3 ? %s\n", (a + b == c) ? "yes" : "no");
+    printf("  a + b = %.20f\n", a + b);
+    printf("  c     = %.20f\n", c);
+
+    return 0;
+}

documents/en/vol1-fundamentals/c_tutorials/02B-float-char-const-cast.md

@@ -69,55 +69,68 @@ long double ld = 3.14L;      // 后缀 L 表示 long double
 
 ### Floating-point numbers are imprecise — this is not a bug
 
-The most important concept to understand about floating-point numbers is this: **floating-point numbers are approximations, not exact values**. This is because computers use a finite number of binary bits to represent decimal fractions, just as you can only represent 1/3 using a finite number of decimal places — it will always be an approximation.
+To understand floating-point numbers, accept one fact first: **they are approximations, not exact values**. It feels counterintuitive — how can the `0.1` you store not equal `0.1`? The answer is hiding inside the binary structure of a floating-point number.
 
-```c
-#include <stdio.h>
+Start with integers as a warm-up. An `int` has only 32 binary bits, so the numbers it can represent have a fixed ceiling and floor; go past them and you overflow. Yet there are infinitely many integers, and the computer just picks one finite segment to represent. Floating-point numbers face the exact same problem: there are infinitely many real numbers, many with infinitely many fractional digits, and a `float` still only gets 32 bits. How does it cover such a vast range with so few bits? The same way you would on paper — scientific notation.
 
-int main(void)
-{
-    float a = 0.1f;
-    float b = 0.2f;
-    if (a + b == 0.3f) {
-        printf("equal\n");
-    } else {
-        printf("not equal: %.9f\n", a + b);
-    }
-    return 0;
-}
-```
+Decimal scientific notation writes `0.0123` as `1.23 × 10⁻²`, a mantissa times a power of 10. A computer does the same thing, only with base 2: `number = (±1) × mantissa × 2^exponent`. The 32 bits of a `float` are split into exactly these three parts:
 
-Let's verify this by compiling and running the code:
+| 1 bit sign | 8 bits exponent | 23 bits mantissa |
+|---|---|---|
+| Positive or negative | How large or small the number can get (range) | How many significant digits you get (precision) |
 
-```bash
-gcc -Wall -Wextra -std=c17 float_demo.c -o float_demo && ./float_demo
-```
+The exponent bits control magnitude, the mantissa bits control fine detail, and both are finite. The exponent lets you reach as high as `10³⁸` and as low as `10⁻⁴⁵`; but with only 23 mantissa bits, you get roughly 7 decimal digits of precision — anything beyond that cannot be stored.
 
-**Output:**
+The real trouble lives in those 23 mantissa bits. The decimal `0.1`, written in binary, is `0.0001100110011...` — an infinitely repeating fraction. The mantissa field has only 23 bits, so it cannot hold the infinite repetition and must truncate. What gets stored is no longer `0.1`. The little program below prints out the raw 32 bits of `0.1f`; click "Try it yourself" to run it directly:
+
+<OnlineCompilerDemo
+  title="What 0.1 actually looks like inside a float"
+  source-path="code/examples/vol1/c_float_representation_en.c"
+  description="Print the 32 bits of 0.1f (sign | exponent | mantissa), then see why 0.1 + 0.2 does not equal 0.3 under double."
+  allow-run
+  run-compiler="cg132"
+  run-options="-O2 -std=c17"
+/>
+
+The key lines of output look like this:
 
 ```text
-not equal: 0.300000012
+32 bits of 0.1f in a float (sign | exponent | mantissa):
+  0 01111011 10011001100110011001101
+
+Printed at different precisions — never exactly 0.1:
+  9 digits : 0.100000001
+  20 digits: 0.10000000149011611938
+
+double: 0.1 + 0.2 == 0.3 ? no
+  a + b = 0.30000000000000004441
+  c     = 0.29999999999999998890
 ```
 
-See? `0.1 + 0.2` does not equal `0.3` in floating-point arithmetic. This is not a compiler bug; it is an inherent characteristic of the IEEE 754 floating-point standard. Therefore, **never use `==` to compare floating-point numbers**. The correct approach is to use a small epsilon value to determine "approximate equality":
+Look at the first line: the sign bit is `0` (positive), the exponent is `01111011`, and the mantissa is `10011001100110011001101` — that run of `1001 1001 1001...` is the infinite repetition truncated to 23 bits, with the final `1` left over from rounding. That is why `0.1f` prints as `0.10000000149011611938`, not `0.1`.
+
+The `double` part is even clearer: `0.1 + 0.2` comes out to `0.30000000000000004441`, while `0.3` stored is `0.29999999999999998890`. Two numbers that were never equal to begin with, compared with `==`, will of course not be equal. There is no mystery here: a finite mantissa cannot hold an infinitely repeating fraction, so this is inevitable.
+
+::: warning
+Never compare floating-point numbers with `==`. `0.1 + 0.2 != 0.3` is the norm in floating-point arithmetic, not a bug. Checking for "approximate equality" with an epsilon is the correct fix.
+:::
+
+One related trap: under `float`, `0.1f + 0.2f` happens to equal `0.3f`. Don't conclude that `float` is somehow more "accurate" — the 23-bit mantissa is simply too coarse, so the error gets rounded away. Switch to the higher-precision `double` and the error has nowhere to hide. Always use this kind of approximate comparison for equality checks:
 
 ```c
 #include <math.h>
 
-/// @brief 判断两个 float 是否近似相等
-/// @param a 第一个浮点数
-/// @param b 第二个浮点数
-/// @return 1 表示近似相等，0 表示不相等
+/// @brief Check whether two floats are approximately equal
+/// @param a the first float
+/// @param b the second float
+/// @return 1 if approximately equal, 0 otherwise
 int float_equal(float a, float b)
 {
     return fabsf(a - b) < 1e-6f;
 }
 ```
 
-> ⚠️ **Warning**
-> Never compare floating-point numbers using `==`. In floating-point arithmetic, `0.1 + 0.2 != 0.3` is the norm, not a bug. Using epsilon to check for approximate equality is the correct approach.
-
-There is one more detail: when we write `float f = 0.1;`, the literal `0.1` is first treated as a `double` and then truncated to `float`—this might introduce additional precision differences. If we intend to use `float`, we should get into the habit of adding the `f` suffix.
+One more detail: when you write `float f = 0.1;`, the `0.1` is first treated as a `double` and then truncated to `float`, which introduces an extra precision difference. If you really mean to use `float`, get into the habit of adding the `f` suffix.
 
 ### Floating-Point in Embedded Systems
 
@@ -311,9 +324,9 @@ Predict the output of the following code, then compile and run it to verify your
 
 int main(void)
 {
-    float a = 0.1f;
-    float b = 0.2f;
-    float c = 0.3f;
+    double a = 0.1;
+    double b = 0.2;
+    double c = 0.3;
 
     printf("a + b == c? %s\n", (a + b == c) ? "yes" : "no");
     printf("a + b     = %.20f\n", a + b);

documents/en/vol1-fundamentals/c_tutorials/index.md

@@ -1,6 +1,11 @@
 # Comprehensive C Language Tutorial
 
-If you are planning to learn or revisit C for whatever reason, and find the C crash course in the parent directory too fast-paced, consider this tutorial instead. It is more detailed and gradual than the crash course, and you can still pick and choose topics based on your interests.
+PS: This part of the tutorial is not aimed at complete beginners. It grew out of a set of C notes taken back when working in embedded development, by which point C was already well in hand. So if you actually need to learn C from scratch, head over to this repo instead:
+
+> [GitHub: C Journey](https://github.com/Awesome-Embedded-Learning-Studio/C-Journey)
+> [Website: C Journey](https://awesome-embedded-learning-studio.github.io/C-Journey/)
+
+The C tutorials here are better suited for people who once learned C but have forgotten what it looks like.
 
 ## Fundamentals
 

documents/vol1-fundamentals/c_tutorials/02B-float-char-const-cast.md

@@ -61,37 +61,53 @@ long double ld = 3.14L;      // 后缀 L 表示 long double
 
 ### 浮点数是不精确的——这不是 bug
 
-这是理解浮点数最重要的一个认知：**浮点数是近似值，不是精确值**。原因在于计算机用有限的二进制位来表示十进制小数，就像你用有限的小数位来表示 1/3 一样——永远只能近似。
+理解浮点数，先认下一件事：**它是近似值，不是精确值**。这事反直觉——存进去的 `0.1` 凭什么就不等于 `0.1`？答案藏在浮点数内部的二进制结构里。
 
-```c
-#include <stdio.h>
+先用整数垫个底。一个 `int` 只有 32 个二进制位，能表示的数有上限也有下限，超过就溢出。可数学里的整数有无穷多个，计算机只取了其中一段。浮点数面对的是同一个问题：实数有无穷多个，不少还带无穷位小数，而 `float` 也只有 32 个位。它拿什么去盖住这么大的范围？靠的是和你纸上演算一样的办法——科学计数法。
 
-int main(void)
-{
-    float a = 0.1f;
-    float b = 0.2f;
-    if (a + b == 0.3f) {
-        printf("equal\n");
-    } else {
-        printf("not equal: %.9f\n", a + b);
-    }
-    return 0;
-}
-```
+十进制科学计数法把 `0.0123` 写成 `1.23 × 10⁻²`，一个尾数乘以 10 的幂。计算机干的事一样，只是底换成 2：`小数 = (±1) × 尾数 × 2^指数`。`float` 的 32 个位就照这三块切：
 
-来验证一下，编译运行：
+| 1 位符号 | 8 位指数 | 23 位尾数 |
+|---|---|---|
+| 正还是负 | 决定能表示多大、多小（范围） | 决定有多少位有效数字（精度） |
 
-```bash
-gcc -Wall -Wextra -std=c17 float_demo.c -o float_demo && ./float_demo
-```
+指数位管量级，尾数位管精细度，两个都有限。指数让你能写到 `10³⁸` 那么大、也能小到 `10⁻⁴⁵`；可尾数只有 23 位，有效数字大概就 7 位十进制，再多存不下。
 
-运行结果：
+真正的麻烦出在尾数那 23 格。十进制的 `0.1` 换成二进制是 `0.0001100110011...`，一个无限循环小数。尾数位只有 23 格，放不下无限循环，只能截断——存进去的早不是 `0.1` 了。下面这段小程序把 `0.1f` 的 32 个二进制位原样打印出来，点"动手试一试"就能直接跑：
+
+<OnlineCompilerDemo
+  title="0.1 在浮点数里到底长什么样"
+  source-path="code/examples/vol1/c_float_representation.c"
+  description="把 0.1f 的 32 个二进制位（符号|指数|尾数）打印出来，再看 double 下 0.1 + 0.2 为什么不等于 0.3。"
+  allow-run
+  run-compiler="cg132"
+  run-options="-O2 -std=c17"
+/>
+
+关键几行输出长这样：
 
 ```text
-not equal: 0.300000012
+0.1f 存进 float 的 32 个二进制位 (符号 | 指数 | 尾数):
+  0 01111011 10011001100110011001101
+
+用不同精度打印它，都不是 0.1：
+  9 位精度 : 0.100000001
+  20 位精度: 0.10000000149011611938
+
+double: 0.1 + 0.2 == 0.3 ? no
+  a + b = 0.30000000000000004441
+  c     = 0.29999999999999998890
 ```
 
-看到了吧——`0.1 + 0.2` 在浮点运算中并不等于 `0.3`。这不是编译器的 bug，是 IEEE 754 浮点标准的固有特性。所以，**永远不要用 `==` 比较浮点数**。正确的做法是用一个小的 epsilon 值来判断"近似相等"：
+看第一行：符号位是 `0`（正数），指数 `01111011`，尾数 `10011001100110011001101`——那串 `1001 1001 1001...` 就是无限循环被截到 23 位的样子，末尾那个 `1` 是舍入进位留下的。所以 `0.1f` 打印出来是 `0.10000000149011611938`，不是 `0.1`。
+
+`double` 那段更直观：`0.1 + 0.2` 算出来是 `0.30000000000000004441`，而 `0.3` 存进去是 `0.29999999999999998890`，两个本来就不等的数拿 `==` 比，自然不相等。原因不神秘：有限位尾数存不下无限循环小数，必然如此。
+
+::: warning
+永远不要用 `==` 比较浮点数。`0.1 + 0.2 != 0.3` 在浮点运算里是常态，不是 bug。用 epsilon 判断近似相等才是正解。
+:::
+
+顺带一个坑：`float` 下 `0.1f + 0.2f` 恰好等于 `0.3f`。别因此觉得 `float` 更"准"——只是 23 位尾数精度太低，把误差一起舍没了。换成精度更高的 `double`，误差就藏不住。判等一律用下面这种近似比较：
 
 ```c
 #include <math.h>
@@ -106,10 +122,7 @@ int float_equal(float a, float b)
 }
 ```
 
-> ⚠️ **踩坑预警**
-> 永远不要用 `==` 比较浮点数。`0.1 + 0.2 != 0.3` 在浮点运算中是常态，不是 bug。用 epsilon 判断近似相等才是正确做法。
-
-还有一个细节：写 `float f = 0.1;` 的时候，`0.1` 先被当作 `double` 处理，然后截断为 `float`——这可能会引入额外的精度差异。如果确定要用 `float`，养成加 `f` 后缀的习惯。
+还有一个细节：写 `float f = 0.1;` 时，`0.1` 先按 `double` 处理再截成 `float`，会引入额外的精度差异。确定用 `float` 就养成加 `f` 后缀的习惯。
 
 ### 嵌入式里的浮点
 
@@ -303,9 +316,9 @@ C++ 在类型系统上做了大量的安全加固，很多改进直接瞄准了
 
 int main(void)
 {
-    float a = 0.1f;
-    float b = 0.2f;
-    float c = 0.3f;
+    double a = 0.1;
+    double b = 0.2;
+    double c = 0.3;
 
     printf("a + b == c? %s\n", (a + b == c) ? "yes" : "no");
     printf("a + b     = %.20f\n", a + b);

documents/vol1-fundamentals/c_tutorials/index.md

@@ -1,6 +1,11 @@
 # C 语言系统教程
 
-如果你是因为一些原因打算学习或重修 C 语言，发现上一级目录的 C 语言速通教程节奏太紧，可以考虑这里的教程。它比速通教程更加详细，循序渐进，同样可以根据自己的喜好挑感兴趣的方向学习。
+PS: 这部分教程不是面向0基础的朋友的，本教程的原型是笔者曾今搞嵌入式的C语言笔记，当时写笔记的时候就已经掌握了C语言，所以如果存在C语言的学习需求，左转到这个仓库：
+
+> [Github C语言的旅程](https://github.com/Awesome-Embedded-Learning-Studio/C-Journey)
+> [网站 C Journey](https://awesome-embedded-learning-studio.github.io/C-Journey/)
+
+这里的C语言教程更偏向于曾学习过C但是忘记C长啥样的朋友看的。
 
 ## 基础篇