docs: Update README and installation guide with new namespaces and features

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

Author: FrozenLemonTee

README.md

@@ -9,7 +9,7 @@
 | [中文](README.zh.md) - [English](README.md) - [Forum](https://mcpp.d2learn.org/forum) |
 |---------------------------------------------------------------------------------|
 | [用户文档](docs/guide/zh/README.md) - [User Documentation](docs/guide/en/README.md) |
-| [API文档](docs/guide/api/README.md) - [API Documentation](docs/api/en/README.md)  |
+| [API文档](docs/api/zh/README.md) - [API Documentation](docs/api/en/README.md)  |
 
 This repository provides configurable `primitive` infrastructure (`underlying traits`, `policy`, and `operations/dispatcher`) to unify numeric behavior, error handling, and concurrency access semantics.
 
@@ -161,7 +161,7 @@ xmake run ex05_concurrency_policy
 xmake run primitives_test
 ```
 
-**Using CMake**
+**Using CMake** (`CMake >= 3.31`)
 
 ```bash
 cmake -B build -G Ninja

README.zh.md

@@ -1,36 +1,36 @@
 # mcpplibs primitives
 
-> C++23 模块化原语库 - `import mcpplibs.primitives;`
+> C++23 模块化 primitives 库 - `import mcpplibs.primitives;`
 
 [![d2x](https://img.shields.io/badge/d2x-ok-green.svg)](https://github.com/d2learn/d2x)
 [![Online-ebook](https://img.shields.io/badge/online-ebook-orange.svg)](https://github.com/d2learn/d2x)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE-CODE)
 
 | [中文](README.zh.md) - [English](README.md) - [论坛](https://mcpp.d2learn.org/forum) |
 |----------------------------------------------------------------------------------|
-| [用户文档](docs/guide/zh/README.md) - [User Documentation](docs/guide/en/README.md)  |
-| [API文档](docs/guide/api/README.md) - [API Documentation](docs/api/en/README.md)   |
+| [用户文档](docs/guide/zh/README.md) - [User Documentation](docs/guide/en/README.md) |
+| [API文档](docs/api/zh/README.md) - [API Documentation](docs/api/en/README.md) |
 
-本仓库提供可配置的 `primitive` 基础设施（`underlying traits`、`policy`、`operations/dispatcher`），用于统一约束数值计算、错误处理与并发访问语义。
+本仓库提供可配置的 `primitive` 基础设施（`underlying traits`、`policy`、`operations/dispatcher`），用于统一数值行为、错误处理与并发访问语义。
 
 > [!WARNING]
-> 当前项目仍在快速演进中，API 可能发生变更。
+> 项目仍在快速演进中，API 可能继续调整。
 
 ## 特性
 
-- **C++23 模块** — `import mcpplibs.primitives;`
-- **双构建系统** — 同时支持 xmake 和 CMake
-- **策略驱动行为** — 值/类型/错误/并发策略可组合配置
-- **混合运算支持** — 支持 `primitive` 与 `underlying` 的混合二元运算
-- **并发访问接口** — `primitive::load/store/compare_exchange`
+- **C++23 模块**: `import mcpplibs.primitives;`
+- **双构建系统**: 同时支持 xmake 和 CMake
+- **策略驱动行为**: value/type/error/concurrency 策略可组合配置
+- **混合运算支持**: 支持 `primitive` 与 `underlying` 的二元运算
+- **并发访问接口**: `primitive::load/store/compare_exchange`
 
 ## Operators
 
-该库为 `primitive` 提供了常见的一元、算术、位运算与比较操作。  
-算术结果通过统一分发链路返回 `std::expected<..., policy::error::kind>`。
+该库为 `primitive` 提供常见的一元、算术、位运算和比较操作。
+算术路径通过统一分发链路返回 `std::expected<..., policy::error::kind>`。
 
-- 值策略（`policy::value::checked` / `policy::value::saturating` / `policy::value::unchecked`）决定溢出行为；
-- 错误策略（`policy::error::throwing` / `policy::error::expected` / `policy::error::terminate`）决定错误传播方式。
+- 值策略（`policy::value::checked` / `policy::value::saturating` / `policy::value::unchecked`）定义溢出行为。
+- 错误策略（`policy::error::throwing` / `policy::error::expected` / `policy::error::terminate`）定义错误传播方式。
 
 示例：
 
@@ -53,24 +53,24 @@ auto maybe_overflow =
 
 ## Policy 协议命名空间
 
-自定义 policy 时，协议入口按职责拆分到子命名空间：
+实现自定义 policy 时，协议入口按职责拆分为以下命名空间：
 
 - `policy::type::handler` / `policy::type::handler_available`
 - `policy::concurrency::handler` / `policy::concurrency::injection`
 - `policy::value::handler` / `policy::value::decision`
 - `policy::error::handler` / `policy::error::request` / `policy::error::kind`
 
-预设 policy 标签：
+内置 policy 标签：
 
 - `policy::value::{checked, unchecked, saturating}`
 - `policy::type::{strict, compatible, transparent}`
 - `policy::error::{throwing, expected, terminate}`
 - `policy::concurrency::{none, fenced, fenced_relaxed, fenced_acq_rel, fenced_seq_cst}`
 
-并发策略说明：
+并发说明：
 
-- `fenced*` 系列是操作级并发语义，通过策略注入内存序 fence；
-- `primitive` 存储仍保持统一、零额外存储抽象；
+- `fenced*` 系列提供操作级并发语义，并通过策略注入内存序 fence。
+- `primitive` 存储保持统一的零额外存储抽象。
 - `primitive::load/store/compare_exchange` 由并发策略协议提供，若策略未实现会在编译期报错。
 
 示例（并发访问 API）：
@@ -98,16 +98,16 @@ if (v.compare_exchange(expected, 3)) {
 
 ## 示例程序
 
-- `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_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 扩展示例。
+- `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_conversion`: 展示 underlying 与 primitive 之间的 `checked/saturating/truncating/exact` 转换辅助接口。
+- `ex07_algorithms`: 展示 limits 元信息、特殊数值和哈希辅助接口。
+- `ex08_custom_underlying`: 展示自定义 underlying traits、rep 校验和 common rep 扩展。
+- `ex09_custom_policy`: 展示自定义 policy 协议实现。
+- `ex10_custom_operation`: 展示自定义 operation 扩展。
 
 ## 项目结构
 
@@ -120,7 +120,7 @@ mcpplibs-primitives/
 │   ├── operations/             # operation tags / dispatcher / operators
 │   └── underlying/             # underlying traits 与 common_rep
 ├── examples/                   # 示例程序
-├── tests/                      # 测试入口与 basic 测试集
+├── tests/                      # 测试入口与基础测试集
 ├── xmake.lua                   # xmake 构建脚本
 ├── CMakeLists.txt              # CMake 构建脚本
 └── .xlings.json                # xlings 包描述文件
@@ -153,15 +153,15 @@ xlings install
 
 ```bash
 xmake build mcpplibs-primitives
-xmake run basic                    # 等价于 ex01_basic_usage
+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
 ```
 
-**使用 CMake**
+**使用 CMake**（`CMake >= 3.31`）
 
 ```bash
 cmake -B build -G Ninja
@@ -192,8 +192,8 @@ target("myapp")
 
 ## 相关链接
 
-- [mcpp-style-ref | 现代 C++ 编码/项目风格参考](https://github.com/mcpp-community/mcpp-style-ref)
-- [d2mystl | 从零实现一个迷你STL库](https://github.com/mcpp-community/d2mystl)
-- [mcpp 社区官网](https://mcpp.d2learn.org)
-- [mcpp | 现代 C++ 爱好者论坛](https://mcpp.d2learn.org/forum)
-- [入门教程: 动手学现代 C++](https://github.com/Sunrisepeak/mcpp-standard)
+- [mcpp-style-ref | 现代 C++ 编码与项目风格参考](https://github.com/mcpp-community/mcpp-style-ref)
+- [d2mystl | 从零实现一个迷你 STL](https://github.com/mcpp-community/d2mystl)
+- [mcpp 社区网站](https://mcpp.d2learn.org)
+- [mcpp 论坛](https://mcpp.d2learn.org/forum)
+- [入门教程：动手学习现代 C++](https://github.com/Sunrisepeak/mcpp-standard)

docs/api/en/README.md

@@ -16,14 +16,19 @@ This module exports:
 - `mcpplibs.primitives.policy`
 - `mcpplibs.primitives.primitive`
 - `mcpplibs.primitives.operations`
+- `mcpplibs.primitives.algorithms`
+- `mcpplibs.primitives.conversion`
 
 ## Namespace Overview
 
 - `mcpplibs::primitives`: core types, concepts, and `primitive`.
 - `mcpplibs::primitives::underlying`: underlying traits and categories.
 - `mcpplibs::primitives::policy`: policy tags, defaults, and protocols.
 - `mcpplibs::primitives::operations`: functional dispatch API.
+- `mcpplibs::primitives::conversion`: numeric risk checks and cast helpers.
+- `mcpplibs::primitives::algorithms`: limits and hash helpers.
 - `mcpplibs::primitives::operators`: operator overload entry.
+- `mcpplibs::primitives::literals`: checked underlying literal suffixes.
 - `mcpplibs::primitives::meta`: primitive metadata traits.
 - `mcpplibs::primitives::types`: convenience aliases for common underlying types.
 
@@ -96,7 +101,7 @@ Notes:
 
 ### Convenience aliases (`types`)
 
-- Integers: `U8/U16/U32/U64`, `I8/I16/I32/I64`
+- Integers: `U8/U16/U32/U64`, `Size`, `Diff`, `I8/I16/I32/I64`
 - Floating-point: `F32/F64/F80`
 - Bool/chars: `Bool/UChar/Char8/Char16/Char32/WChar`
 
@@ -108,6 +113,25 @@ using value_t = mcpplibs::primitives::types::I32<
     mcpplibs::primitives::policy::error::expected>;
 ```
 
+### Factory helpers and literals
+
+- `with(value)` builds a `primitive` with default policies from an underlying value.
+- `with<Policies...>(value)` applies an explicit policy set during construction.
+- `with(policies_tuple, value)` reuses an existing policies tuple.
+- `mcpplibs::primitives::literals` provides checked suffixes such as
+  `_u8/_u16/_u32/_u64/_size/_diff`, `_i8/_i16/_i32/_i64`,
+  `_f32/_f32e/_f64/_f64e/_f80/_f80e`, and character suffixes
+  `_uchar/_char8/_char16/_char32/_wchar`.
+
+Example:
+
+```cpp
+using namespace mcpplibs::primitives;
+using namespace mcpplibs::primitives::literals;
+
+auto value = with<policy::value::checked, policy::error::expected>(42_i32);
+```
+
 ## `operations` API
 
 The `operations` namespace provides function-style APIs with unified `std::expected` results.
@@ -172,6 +196,58 @@ using namespace mcpplibs::primitives::operators;
 
 Operator results are still `std::expected<...>`, not raw values.
 
+## `conversion` API
+
+The `conversion` namespace provides reusable casts for underlying values,
+primitives, and mixed source/destination pairs.
+
+### Common result aliases and risk model
+
+- `cast_result<T> = std::expected<T, conversion::risk::kind>`
+- `conversion::risk::kind`:
+  `none`, `overflow`, `underflow`, `domain_error`, `precision_loss`,
+  `sign_loss`, `invalid_type_combination`
+
+### Conversion helpers
+
+- `numeric_risk<Dest>(value)`
+- `unchecked_cast<Dest>(value)`
+- `checked_cast<Dest>(value)`
+- `saturating_cast<Dest>(value)`
+- `truncating_cast<Dest>(value)`
+- `exact_cast<Dest>(value)`
+
+Notes:
+
+- `checked_cast` and `exact_cast` return `cast_result<T>`.
+- `saturating_cast` clamps overflow/underflow for numeric destinations.
+- `truncating_cast` is useful for floating-to-integral conversions.
+- Overloads exist for underlying -> underlying, primitive -> primitive,
+  primitive -> underlying, and underlying -> primitive paths.
+
+## `algorithms` API
+
+The `algorithms` namespace provides reusable limits metadata and hashing helpers
+for built-in and supported custom underlyings.
+
+### Limits
+
+- `limits<T>`
+- `limited_type<T>`
+- `min_value<T>()`
+- `lowest_value<T>()`
+- `max_value<T>()`
+- `epsilon_value<T>()`
+- `infinity_value<T>()`
+- `quiet_nan_value<T>()`
+
+### Hashing
+
+- `hash<T>`
+- `hash_result_t<T>`
+- `hashable<T>`
+- `hash_value(value)`
+
 ## policy API
 
 ### Built-in policy tags

docs/api/zh/README.md

@@ -16,14 +16,19 @@ import mcpplibs.primitives;
 - `mcpplibs.primitives.policy`
 - `mcpplibs.primitives.primitive`
 - `mcpplibs.primitives.operations`
+- `mcpplibs.primitives.algorithms`
+- `mcpplibs.primitives.conversion`
 
 ## 命名空间总览
 
 - `mcpplibs::primitives`: 核心类型、概念与 `primitive`。
 - `mcpplibs::primitives::underlying`: underlying traits 与类别。
 - `mcpplibs::primitives::policy`: policy 标签、默认值与协议。
 - `mcpplibs::primitives::operations`: 分发函数 API。
+- `mcpplibs::primitives::conversion`: 数值风险检查与转换辅助接口。
+- `mcpplibs::primitives::algorithms`: limits 与 hash 辅助接口。
 - `mcpplibs::primitives::operators`: 运算符重载入口。
+- `mcpplibs::primitives::literals`: 带范围校验的 underlying 字面量后缀。
 - `mcpplibs::primitives::meta`: primitive 元信息 traits。
 - `mcpplibs::primitives::types`: 常用 underlying 的 primitive 别名。
 
@@ -96,7 +101,7 @@ class primitive;
 
 ### 预定义别名（`types`）
 
-- 整型：`U8/U16/U32/U64`、`I8/I16/I32/I64`
+- 整型：`U8/U16/U32/U64`、`Size`、`Diff`、`I8/I16/I32/I64`
 - 浮点：`F32/F64/F80`
 - 布尔/字符：`Bool/UChar/Char8/Char16/Char32/WChar`
 
@@ -108,6 +113,25 @@ using value_t = mcpplibs::primitives::types::I32<
     mcpplibs::primitives::policy::error::expected>;
 ```
 
+### 工厂函数与 literals
+
+- `with(value)`：从 underlying 值按默认策略构造 `primitive`
+- `with<Policies...>(value)`：构造时显式指定策略集合
+- `with(policies_tuple, value)`：复用已有策略元组
+- `mcpplibs::primitives::literals` 提供带校验的后缀，例如
+  `_u8/_u16/_u32/_u64/_size/_diff`、`_i8/_i16/_i32/_i64`、
+  `_f32/_f32e/_f64/_f64e/_f80/_f80e`，以及
+  `_uchar/_char8/_char16/_char32/_wchar`
+
+示例：
+
+```cpp
+using namespace mcpplibs::primitives;
+using namespace mcpplibs::primitives::literals;
+
+auto value = with<policy::value::checked, policy::error::expected>(42_i32);
+```
+
 ## `operations` API
 
 `operations` 命名空间提供函数式调用接口，统一返回 `std::expected`。
@@ -172,6 +196,56 @@ using namespace mcpplibs::primitives::operators;
 
 重载结果同样是 `std::expected<...>`，不是裸值。
 
+## `conversion` API
+
+`conversion` 命名空间提供 underlying、primitive 以及混合路径之间的统一转换接口。
+
+### 常用结果类型与风险模型
+
+- `cast_result<T> = std::expected<T, conversion::risk::kind>`
+- `conversion::risk::kind`：
+  `none`、`overflow`、`underflow`、`domain_error`、`precision_loss`、
+  `sign_loss`、`invalid_type_combination`
+
+### 转换函数
+
+- `numeric_risk<Dest>(value)`
+- `unchecked_cast<Dest>(value)`
+- `checked_cast<Dest>(value)`
+- `saturating_cast<Dest>(value)`
+- `truncating_cast<Dest>(value)`
+- `exact_cast<Dest>(value)`
+
+说明：
+
+- `checked_cast` 与 `exact_cast` 返回 `cast_result<T>`
+- `saturating_cast` 会对数值溢出/下溢执行钳制
+- `truncating_cast` 适合浮点到整数的截断场景
+- 提供 underlying -> underlying、primitive -> primitive、
+  primitive -> underlying、underlying -> primitive 四类重载
+
+## `algorithms` API
+
+`algorithms` 命名空间提供 limits 元信息与 hash 辅助接口，适用于内置类型和受支持的自定义 underlying。
+
+### Limits
+
+- `limits<T>`
+- `limited_type<T>`
+- `min_value<T>()`
+- `lowest_value<T>()`
+- `max_value<T>()`
+- `epsilon_value<T>()`
+- `infinity_value<T>()`
+- `quiet_nan_value<T>()`
+
+### Hash
+
+- `hash<T>`
+- `hash_result_t<T>`
+- `hashable<T>`
+- `hash_value(value)`
+
 ## policy API
 
 ### 内置策略标签