refactor: Update example references and commands for clarity and consistency

Signed-off-by: FrozenlemonTee <1115306170@qq.com>

Author: FrozenLemonTee

README.md

@@ -98,14 +98,16 @@ Default policies are available under `policy::defaults`:
 
 ## Examples
 
-- `ex01_default_arithmetic`: Basic arithmetic under default policies.
+- `ex01_basic_usage`: Literals + primitive factory helpers with the built-in operator set.
 - `ex02_type_policy`: Type negotiation with `strict/compatible`, including how type policy affects construction from `underlying`.
 - `ex03_value_policy`: `checked/unchecked/saturating` behavior, including mixed binary operations with `underlying`.
 - `ex04_error_policy`: Error-handling behavior across different error policies.
 - `ex05_concurrency_policy`: Representative mixed read/write concurrency workload (writer `store` + reader `add/sub` + `CAS`).
-- `ex06_custom_underlying`: Custom underlying traits, rep validation, and common-rep extension.
-- `ex07_custom_policy`: Custom policy protocol implementation.
-- `ex08_custom_operation`: Custom operation extension.
+- `ex06_conversion`: Checked/saturating/truncating/exact conversion helpers across underlying values and primitives.
+- `ex07_algorithms`: Limits metadata, special numeric values, and hashing helpers.
+- `ex08_custom_underlying`: Custom underlying traits, rep validation, and common-rep extension.
+- `ex09_custom_policy`: Custom policy protocol implementation.
+- `ex10_custom_operation`: Custom operation extension.
 
 ## Project Layout
 
@@ -117,7 +119,7 @@ mcpplibs-primitives/
 │   ├── policy/                 # policy tags and protocol implementations
 │   ├── operations/             # operation tags / dispatcher / operators
 │   └── underlying/             # underlying traits and common_rep
-├── examples/                   # ex01 ~ ex08 examples
+├── examples/                   # example programs
 ├── tests/                      # test entry and basic test suite
 ├── xmake.lua                   # xmake build script
 ├── CMakeLists.txt              # CMake build script
@@ -151,7 +153,10 @@ xlings install
 
 ```bash
 xmake build mcpplibs-primitives
-xmake run basic                    # equivalent to ex01_default_arithmetic
+xmake run basic                    # compatibility alias for ex01_basic_usage
+xmake run ex01_basic_usage
+xmake run ex06_conversion
+xmake run ex07_algorithms
 xmake run ex05_concurrency_policy
 xmake run primitives_test
 ```
@@ -161,7 +166,9 @@ xmake run primitives_test
 ```bash
 cmake -B build -G Ninja
 cmake --build build --target mcpplibs-primitives
-cmake --build build --target ex01_default_arithmetic
+cmake --build build --target ex01_basic_usage
+cmake --build build --target ex06_conversion
+cmake --build build --target ex07_algorithms
 cmake --build build --target basic_tests
 ctest --test-dir build --output-on-failure
 ```

README.zh.md

@@ -98,14 +98,16 @@ if (v.compare_exchange(expected, 3)) {
 
 ## 示例程序
 
-- `ex01_default_arithmetic`: 默认策略下的基础算术运算示例。
+- `ex01_basic_usage`: 演示 literal 与 primitive 工厂函数联合使用，并覆盖更多内置操作符。
 - `ex02_type_policy`: 展示 `strict/compatible` 的类型协商差异，并包含 `underlying` 构造路径对 type 策略的影响。
 - `ex03_value_policy`: 展示 `checked/unchecked/saturating`，并包含与 `underlying` 的混合二元运算行为。
 - `ex04_error_policy`: 展示不同 error 策略的处理方式。
 - `ex05_concurrency_policy`: 读写组合并发场景（writer `store` + reader `add/sub` + `CAS`）示例。
-- `ex06_custom_underlying`: 自定义 underlying traits、rep 校验与 common rep 扩展。
-- `ex07_custom_policy`: 自定义策略协议实现示例。
-- `ex08_custom_operation`: 自定义 operation 扩展示例。
+- `ex06_conversion`: 展示 underlying 与 primitive 之间的 checked/saturating/truncating/exact 转换。
+- `ex07_algorithms`: 展示 limits、特殊数值与 hash 等 algorithms 辅助接口。
+- `ex08_custom_underlying`: 自定义 underlying traits、rep 校验与 common rep 扩展。
+- `ex09_custom_policy`: 自定义策略协议实现示例。
+- `ex10_custom_operation`: 自定义 operation 扩展示例。
 
 ## 项目结构
 
@@ -117,7 +119,7 @@ mcpplibs-primitives/
 │   ├── policy/                 # policy 标签与协议实现
 │   ├── operations/             # operation tags / dispatcher / operators
 │   └── underlying/             # underlying traits 与 common_rep
-├── examples/                   # ex01 ~ ex08 示例
+├── examples/                   # 示例程序
 ├── tests/                      # 测试入口与 basic 测试集
 ├── xmake.lua                   # xmake 构建脚本
 ├── CMakeLists.txt              # CMake 构建脚本
@@ -151,7 +153,10 @@ xlings install
 
 ```bash
 xmake build mcpplibs-primitives
-xmake run basic                    # 等价于 ex01_default_arithmetic
+xmake run basic                    # 等价于 ex01_basic_usage
+xmake run ex01_basic_usage
+xmake run ex06_conversion
+xmake run ex07_algorithms
 xmake run ex05_concurrency_policy
 xmake run primitives_test
 ```
@@ -161,7 +166,9 @@ xmake run primitives_test
 ```bash
 cmake -B build -G Ninja
 cmake --build build --target mcpplibs-primitives
-cmake --build build --target ex01_default_arithmetic
+cmake --build build --target ex01_basic_usage
+cmake --build build --target ex06_conversion
+cmake --build build --target ex07_algorithms
 cmake --build build --target basic_tests
 ctest --test-dir build --output-on-failure
 ```

docs/guide/en/extension.md

@@ -18,7 +18,7 @@ Required members:
 
 After registration, your type can be used as `primitive<YourType, ...>` if it satisfies `underlying_type`.
 
-Reference example: `examples/ex06_custom_underlying.cpp`.
+Reference example: `examples/ex08_custom_underlying.cpp`.
 
 ## 2) Custom Common Rep Negotiation
 
@@ -47,7 +47,7 @@ Custom policies require:
 
 If your value policy needs operation runtime behavior, also provide `operations::runtime::op_binding` specializations.
 
-Reference example: `examples/ex07_custom_policy.cpp`.
+Reference example: `examples/ex09_custom_policy.cpp`.
 
 ## 4) Custom Operation Tags
 
@@ -61,7 +61,7 @@ To add new operation tags:
 3. Provide `operations::runtime::op_binding<OpTag, ValuePolicy, CommonRep>`.
 4. Invoke via `operations::apply<OpTag>(lhs, rhs)`.
 
-Reference example: `examples/ex08_custom_operation.cpp`.
+Reference example: `examples/ex10_custom_operation.cpp`.
 
 ## Extension Checklist
 

docs/guide/en/installation-and-build.md

@@ -21,7 +21,7 @@ xmake build mcpplibs-primitives
 Run an example:
 
 ```bash
-xmake run ex01_default_arithmetic
+xmake run ex01_basic_usage
 ```
 
 Run tests:
@@ -36,7 +36,7 @@ Compatibility alias:
 xmake run basic
 ```
 
-`basic` runs `ex01_default_arithmetic`.
+`basic` runs `ex01_basic_usage`.
 
 ## Build with CMake
 
@@ -50,7 +50,9 @@ cmake --build build --target mcpplibs-primitives
 Build an example and tests:
 
 ```bash
-cmake --build build --target ex01_default_arithmetic
+cmake --build build --target ex01_basic_usage
+cmake --build build --target ex06_conversion
+cmake --build build --target ex07_algorithms
 cmake --build build --target basic_tests
 ctest --test-dir build --output-on-failure
 ```
@@ -59,14 +61,16 @@ ctest --test-dir build --output-on-failure
 
 Examples are available as independent targets:
 
-- `ex01_default_arithmetic`
+- `ex01_basic_usage`
 - `ex02_type_policy`
 - `ex03_value_policy`
 - `ex04_error_policy`
 - `ex05_concurrency_policy`
-- `ex06_custom_underlying`
-- `ex07_custom_policy`
-- `ex08_custom_operation`
+- `ex06_conversion`
+- `ex07_algorithms`
+- `ex08_custom_underlying`
+- `ex09_custom_policy`
+- `ex10_custom_operation`
 
 ## Common Build Issues
 

docs/guide/en/quick-start.md

@@ -38,14 +38,16 @@ This gives safe arithmetic and explicit error handling without requiring excepti
 
 Run examples in this order:
 
-1. `ex01_default_arithmetic`
+1. `ex01_basic_usage`
 2. `ex02_type_policy`
 3. `ex03_value_policy`
 4. `ex04_error_policy`
 5. `ex05_concurrency_policy`
-6. `ex06_custom_underlying`
-7. `ex07_custom_policy`
-8. `ex08_custom_operation`
+6. `ex06_conversion`
+7. `ex07_algorithms`
+8. `ex08_custom_underlying`
+9. `ex09_custom_policy`
+10. `ex10_custom_operation`
 
 Command:
 

docs/guide/zh/extension.md

@@ -18,7 +18,7 @@
 
 完成后，只要满足 `underlying_type`，即可用于 `primitive<YourType, ...>`。
 
-参考：`examples/ex06_custom_underlying.cpp`
+参考：`examples/ex08_custom_underlying.cpp`
 
 ## 2) 自定义 common rep 协商
 
@@ -47,7 +47,7 @@ struct mcpplibs::primitives::underlying::common_rep_traits<LhsRep, RhsRep> {
 
 如果 value policy 需要参与运行期运算逻辑，还要补充 `operations::runtime::op_binding` 特化。
 
-参考：`examples/ex07_custom_policy.cpp`
+参考：`examples/ex09_custom_policy.cpp`
 
 ## 4) 自定义 operation 标签
 
@@ -61,7 +61,7 @@ struct mcpplibs::primitives::underlying::common_rep_traits<LhsRep, RhsRep> {
 3. 提供 `operations::runtime::op_binding<OpTag, ValuePolicy, CommonRep>`。
 4. 通过 `operations::apply<OpTag>(lhs, rhs)` 调用。
 
-参考：`examples/ex08_custom_operation.cpp`
+参考：`examples/ex10_custom_operation.cpp`
 
 ## 扩展检查清单
 

docs/guide/zh/installation-and-build.md

@@ -21,7 +21,7 @@ xmake build mcpplibs-primitives
 运行示例：
 
 ```bash
-xmake run ex01_default_arithmetic
+xmake run ex01_basic_usage
 ```
 
 运行测试：
@@ -36,7 +36,7 @@ xmake run primitives_test
 xmake run basic
 ```
 
-`basic` 对应 `ex01_default_arithmetic`。
+`basic` 对应 `ex01_basic_usage`。
 
 ## 使用 CMake 构建
 
@@ -50,7 +50,9 @@ cmake --build build --target mcpplibs-primitives
 构建示例与测试：
 
 ```bash
-cmake --build build --target ex01_default_arithmetic
+cmake --build build --target ex01_basic_usage
+cmake --build build --target ex06_conversion
+cmake --build build --target ex07_algorithms
 cmake --build build --target basic_tests
 ctest --test-dir build --output-on-failure
 ```
@@ -59,14 +61,16 @@ ctest --test-dir build --output-on-failure
 
 可独立构建/运行的示例目标：
 
-- `ex01_default_arithmetic`
+- `ex01_basic_usage`
 - `ex02_type_policy`
 - `ex03_value_policy`
 - `ex04_error_policy`
 - `ex05_concurrency_policy`
-- `ex06_custom_underlying`
-- `ex07_custom_policy`
-- `ex08_custom_operation`
+- `ex06_conversion`
+- `ex07_algorithms`
+- `ex08_custom_underlying`
+- `ex09_custom_policy`
+- `ex10_custom_operation`
 
 ## 常见构建问题
 

docs/guide/zh/quick-start.md

@@ -38,14 +38,16 @@ int main() {
 
 建议按以下顺序运行示例：
 
-1. `ex01_default_arithmetic`
+1. `ex01_basic_usage`
 2. `ex02_type_policy`
 3. `ex03_value_policy`
 4. `ex04_error_policy`
 5. `ex05_concurrency_policy`
-6. `ex06_custom_underlying`
-7. `ex07_custom_policy`
-8. `ex08_custom_operation`
+6. `ex06_conversion`
+7. `ex07_algorithms`
+8. `ex08_custom_underlying`
+9. `ex09_custom_policy`
+10. `ex10_custom_operation`
 
 运行示例：