Merge pull request #21 from mcpplibs/pump-0.4.0

Pump 0.4.0

Author: FrozenLemonTee

.agents/docs/plans/implementation-plan.md

@@ -1,102 +1,125 @@
-# Primitives 下一步实现计划清单（2026-03-26）
-
-## 总体原则
-
-- [ ] 先定义稳定 API 边界，再落地实现
-- [ ] 每个能力都配套 tests + examples + docs
-- [ ] 高风险转换默认禁止隐式触发，只允许显式 API
-- [ ] 明确分层职责：`algorithms` 负责值域/排序/边界元信息与值算法；`conversion` 负责显式类型变换
-- [ ] 明确依赖方向：`conversion` 可依赖 `algorithms`，`algorithms` 不反向依赖 `conversion`
-
-## M1. C API 互操作层（双向）
-
-### 工作清单
-
-- [ ] 定义稳定 C ABI（命名规范、导出宏、版本策略）
-- [ ] 设计双向能力：C 调用 primitives；primitives 适配并调用 C API
-- [ ] 统一错误模型（error code + 可选 message buffer）
-- [ ] 提供最小可用头文件：`include/mcpplibs/primitives/c_api.h`
-- [ ] 增加 C/C++ 混合构建测试（C 编译器 + C++ 链接）
-- [ ] 增加示例：`examples/c/basic.c`、`examples/cpp/use_c_api.cpp`
-
-### 验收标准
-
-- [ ] 纯 C 工程可链接并完成基础能力调用
-- [ ] C++ 对外部 C API 的适配调用行为可控、无未定义行为
-
-## M2. Concept/Traits 体系增强与元信息 API
-
-### 工作清单
-
-- [ ] 扩展 concept 分层（category/representation/policy-capability）
-- [ ] 明确 `underlying::traits<T>` 与 `algorithms::traits<T>` 的职责边界：前者描述表示层；后者描述值算法层
-- [ ] 完善 `traits<T>` 元信息（`kind`、`rep_type`、policy tags）
-- [ ] 设计 `algorithms::traits<T>`，内容参考 `std::numeric_limits`，但只保留算法/比较所需子集：
-- [ ] `min()` / `lowest()` / `max()` / `epsilon()` / `infinity()` / `quiet_nan()`
-- [ ] `is_bounded` / `is_exact` / `is_signed` / `is_integer` / `is_iec559`
-- [ ] `has_infinity` / `has_quiet_nan` / `digits` / `digits10` / `radix`
-- [ ] 增加排序能力元信息：`comparison_category`、`totally_ordered`、`partially_ordered`、`unordered_possible`
-- [ ] 提供双参聚合元信息：`algorithms::common_traits<Lhs, Rhs>`，统一暴露 `common_rep`、可比较性、边界查询与策略兼容性
-- [ ] 提供检测类 API（可比较性/可裁剪性/可转换性/是否有损/错误模型能力）
-- [ ] 统一 `constexpr` 查询入口，减少分散 traits 访问
-- [ ] 增加编译期测试矩阵（`static_assert` 覆盖）
-
-### 验收标准
-
-- [ ] 上层模块仅依赖公开 concept/traits，不依赖 `details::*`
-- [ ] `algorithms::traits` 可直接支撑算法层判定，并作为 conversion 的元信息依赖
-- [ ] `std::numeric_limits` 相关逻辑不再散落在 `conversion`/`operations` 内部
-
-## M3. 显式转换层（任意策略组适用）
-
-### 工作清单
-
-- [ ] 设计统一接口族（建议）：`explicit_cast`、`try_cast`、`checked_cast`
-- [ ] 将边界、NaN、无穷大、精度与排序相关判定统一改为依赖 `algorithms::traits` / `algorithms::common_traits`
-- [ ] 支持任意策略组组合，不绑定特定策略实现
-- [ ] 风险可见化（截断/溢出/精度损失）并可程序化读取
-- [ ] 定义失败语义（错误码或 expected 风格，按策略可配置）
-- [ ] 建立转换矩阵测试（同类/跨类/跨策略组）
-
-### 验收标准
-
-- [ ] 所有跨类高风险转换必须走显式 API
-- [ ] 风险信息可在编译期或运行期被确定性获取
-- [ ] `conversion` 模块仅消费 `algorithms` 提供的元信息，不反向定义算法层协议
-
-## M4. 算法层（traits 先行，以 max/min 为起点）
-
-### 工作清单
-
-- [ ] 确定模块结构：`mcpplibs.primitives.algorithms`、`mcpplibs.primitives.algorithms.traits`、`mcpplibs.primitives.algorithms.compare`、`mcpplibs.primitives.algorithms.minmax`
-- [ ] 先实现 `algorithms::traits` 与 `algorithms::common_traits`，作为整个算法层与 conversion 的基础依赖
-- [ ] 约束算法职责只涉及值的比较、选择、裁剪与边界处理，不提供目标类型导向的 cast API
-- [ ] `max`/`min` 内部仅允许做 `common_rep` 归一化或排序语义协商，不绕回 conversion 层
-- [ ] 实现 `max`/`min`，并预留 `clamp`/`compare` 扩展位
-- [ ] 支持同类输入与受约束的异类输入；异类场景必须满足 `common_rep`、排序能力与策略组约束
-- [ ] 明确 `partial_ordering` / `unordered` 语义，尤其是浮点 `NaN` 路径
-- [ ] 为 `clamp`/`compare` 抽出复用内核：公共比较、边界判定、值选择
-- [ ] 在可行范围保持 `constexpr`/`noexcept` 特性
-- [ ] 增加边界测试（极值、NaN、有符号/无符号混合、不同 `comparison_category`）
-
-### 验收标准
-
-- [ ] 算法行为与策略约束一致
-- [ ] 风险路径始终显式、可审计
-- [ ] `algorithms` 可独立编译并被 `conversion` 依赖，不形成反向模块耦合
-- [ ] 算法层实现不通过“显式转换 API”间接完成值比较
-
-## 建议推进顺序
-
-1. M2（先夯实约束与元信息基础）
-2. M4 前半：`algorithms::traits` / `common_traits` / 排序能力查询
-3. M3（让 conversion 改为依赖 algorithms 元信息）
-4. M4 后半：`max` / `min` / `clamp` / `compare`
-5. M1（建立跨语言边界，可按需求并行推进）
-
-## 总体完成跟踪
-
-- [ ] M1 完成
-- [ ] M2 完成
-- [ ] M3 完成
-- [ ] M4 完成
+# Primitives 下一步实现计划清单（2026-03-27）
+
+## 当前状态
+
+- [ ] M1 完成：C API 互操作层（双向）
+- [x] M2 完成：Concept/Traits 体系增强与元信息 API
+- [x] M3 完成：显式转换层（任意策略组适用）
+- [x] M4 完成：算法层（traits 先行，以 max/min 为起点）
+
+## 持续约束
+
+- 先定义稳定 API 边界，再落地实现。
+- 每个能力都配套 `tests + examples + docs`。
+- 高风险转换默认禁止隐式触发，只允许显式 API。
+- 明确分层职责：`algorithms` 负责值域/排序/边界元信息与值算法；`conversion` 负责显式类型变换。
+- 明确依赖方向：`conversion` 可依赖 `algorithms`，`algorithms` 不反向依赖 `conversion`。
+- C ABI 只暴露稳定、可版本化的边界；不直接泄露模板、模块实现细节或未稳定的策略矩阵。
+
+## M1. C API 互操作层（最后剩余部分）
+
+### M1-0. 范围冻结与接口裁剪
+
+- [ ] 冻结 `M1 v1` 范围：仅支持 `int32_t` / `uint32_t` / `double` 三类基础值。
+- [ ] 冻结 `M1 v1` 能力面：仅提供 `add` / `sub` / `mul` / `div`、基础比较、显式转换、版本查询。
+- [ ] 明确第一版不纳入 ABI 的内容：`char` 系列、`long double`、自定义 underlying、完整策略组合、完整 operator 集。
+- [ ] 统一第一版语义映射为“显式调用 + checked 路径 + 错误码返回”，不允许异常跨越 C ABI。
+- [ ] 输出一份最小公共命名规范：`mcpplibs_primitives_{type}_{op}`。
+
+### M1-1. 稳定 C ABI 与头文件
+
+- [ ] 新增最小公共头文件：`include/mcpplibs/primitives/c_api.h`。
+- [ ] 定义导出宏：`MCPPLIBS_PRIMITIVES_C_API`、`MCPPLIBS_PRIMITIVES_EXTERN_C`。
+- [ ] 定义 C API 版本宏：`MCPPLIBS_PRIMITIVES_C_API_VERSION_MAJOR` / `MINOR` / `PATCH`。
+- [ ] 定义统一错误码枚举，至少覆盖：
+- [ ] `ok`
+- [ ] `invalid_argument`
+- [ ] `overflow`
+- [ ] `underflow`
+- [ ] `divide_by_zero`
+- [ ] `domain_error`
+- [ ] `unsupported`
+- [ ] `internal_error`
+- [ ] 定义统一消息缓冲区协议：`char* message` + `size_t message_size`，支持空指针与零长度缓冲区。
+- [ ] 定义统一返回约定：函数返回错误码，业务结果通过 `out` 参数返回。
+- [ ] 提供版本查询函数与能力探测函数，确保后续 ABI 演进可协商。
+
+### M1-2. C -> primitives 调用桥
+
+- [ ] 在 `src/c_api/` 下建立实现目录。
+- [ ] 拆分实现文件，建议至少包含：
+- [ ] `src/c_api/abi.cpp`
+- [ ] `src/c_api/arithmetic.cpp`
+- [ ] `src/c_api/compare.cpp`
+- [ ] `src/c_api/conversion.cpp`
+- [ ] 以公开模块能力为唯一实现入口：只调用 `mcpplibs.primitives` 已导出的 `types`、`operations`、`conversion`。
+- [ ] 为每个 ABI 入口补齐参数校验：`out == nullptr`、非法 buffer、除零、溢出、域错误。
+- [ ] 建立统一错误翻译层：将 `policy::error::kind` 与转换风险映射到 C 错误码。
+- [ ] 在 ABI 边界统一拦截异常并映射为 `internal_error`，禁止任何 C++ 异常穿透到 C 侧。
+- [ ] 保证所有导出函数不暴露 `std::expected`、模板实例、模块内部类型或 STL 容器布局。
+
+### M1-3. primitives -> 外部 C API 适配桥
+
+- [ ] 新增 C++ 适配层，建议文件：
+- [ ] `src/c_api/adapter.cppm`
+- [ ] `src/c_api/adapter.cpp`
+- [ ] 用“函数表 + `void* context`”建模外部 C API，而不是散落裸函数指针。
+- [ ] 第一版只适配与 `M1 v1` 对称的能力：四则、比较、显式 cast。
+- [ ] 明确适配协议：
+- [ ] 适配层不拥有 `context`
+- [ ] 回调必须是 `noexcept` 语义约束
+- [ ] 返回码必须可映射到 `policy::error::kind`
+- [ ] 外部 C API 回传值必须再经过 primitives 的范围与错误检查，不能绕开现有风险路径。
+- [ ] 为适配层建立最小公共抽象，避免未来直接把外部 C API 绑定死到具体函数签名。
+
+### M1-4. 构建系统与安装集成
+
+- [ ] 更新 `CMakeLists.txt`：将 `project(... LANGUAGES CXX)` 扩展为 `project(... LANGUAGES C CXX)`。
+- [ ] 为 C API 头文件添加安装与导出规则，确保 `include/mcpplibs/primitives/c_api.h` 进入安装产物。
+- [ ] 决定 C ABI 的产物形态：
+- [ ] 方案 A：并入现有 `mcpplibs-primitives` 静态库
+- [ ] 方案 B：新增单独目标 `mcpplibs-primitives-capi`
+- [ ] 更新 `xmake.lua`，确保 C 示例与 C 测试能参与构建。
+- [ ] 更新 `examples/CMakeLists.txt` 与 `examples/xmake.lua`，纳入 C 示例和 C++ 适配示例。
+- [ ] 更新 `tests/CMakeLists.txt`、`tests/basic/CMakeLists.txt`、`tests/xmake.lua`，纳入 C/C++ 混合验证目标。
+
+### M1-5. 测试、示例与文档
+
+- [ ] 新增纯 C 示例：`examples/c/basic.c`。
+- [ ] 新增 C++ 调用 C API 示例：`examples/cpp/use_c_api.cpp`。
+- [ ] 新增纯 C smoke test，验证：
+- [ ] 头文件可被 C 编译器独立包含
+- [ ] C 目标可链接库产物
+- [ ] `int32 add`、`double div` 成功路径可运行
+- [ ] 除零或溢出错误路径可观测
+- [ ] 新增 C++ 适配层测试，验证：
+- [ ] 外部 C API 成功路径映射正确
+- [ ] 错误码映射正确
+- [ ] 空指针/非法参数会被拒绝
+- [ ] 回调异常或非法返回不会引入未定义行为
+- [ ] 新增 ABI 边界测试，覆盖消息 buffer 截断、空 buffer、空 `out` 参数、版本查询。
+- [ ] 更新 `README.md` / `README.zh.md`，补充 C API 简介、边界约束与示例入口。
+- [ ] 更新 `docs/api/en` / `docs/api/zh`，补充错误模型、版本策略和双向互操作说明。
+
+### M1-6. 收口与验收
+
+- [ ] 纯 C 工程可独立包含 `c_api.h`、成功链接并调用基础能力。
+- [ ] C API 成功路径、错误路径、异常隔离路径全部可回归测试。
+- [ ] C++ 对外部 C API 的适配调用行为可控、无未定义行为。
+- [ ] ABI 命名、导出宏、版本查询、错误码模型在文档中有明确承诺。
+- [ ] `M1 v1` 中未纳入 ABI 的能力在文档中明确标注为“未稳定/不承诺”。
+
+## 建议推进顺序（按 PR / 工作包）
+
+1. `M1-0 + M1-1`：先冻结第一版范围，并提交 `c_api.h` 与 ABI 契约。
+2. `M1-2`：实现 C 调用 primitives 的最小闭环，先跑通 `int32_t` 和 `double`。
+3. `M1-4`：补齐 CMake/xmake/安装规则，让 C 目标进入正式构建链路。
+4. `M1-5`：补齐 `examples/c/basic.c`、`examples/cpp/use_c_api.cpp` 和混合测试。
+5. `M1-3`：实现 primitives 对外部 C API 的适配桥，并补齐适配测试。
+6. `M1-6`：统一收口文档、版本策略与验收项，准备关闭 M1。
+
+## 已完成里程碑归档
+
+- [x] M2 已完成，后续不再作为阻塞项跟踪。
+- [x] M3 已完成，后续仅在 M1 适配中复用已有显式转换能力。
+- [x] M4 已完成，后续仅在 M1 实现中复用已有算法层与 traits 元信息。

CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
-project(mcpplibs-primitives VERSION 0.3.0 LANGUAGES CXX)
+project(mcpplibs-primitives VERSION 0.4.0 LANGUAGES CXX)
 
 find_package(Threads REQUIRED)
 

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.
 
@@ -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,17 +153,22 @@ 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
 ```
 
-**Using CMake**
+**Using CMake** (`CMake >= 3.31`)
 
 ```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
 ```