feat: Add literals module with numeric literal support and range checks

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

Author: FrozenLemonTee

docs/api/en/README.md

@@ -13,6 +13,7 @@ import mcpplibs.primitives;
 This module exports:
 
 - `mcpplibs.primitives.underlying`
+- `mcpplibs.primitives.literals`
 - `mcpplibs.primitives.policy`
 - `mcpplibs.primitives.primitive`
 - `mcpplibs.primitives.operations`
@@ -126,6 +127,9 @@ using value_t = mcpplibs::primitives::types::I32<
 Example:
 
 ```cpp
+import mcpplibs.primitives;
+import mcpplibs.primitives.literals;
+
 using namespace mcpplibs::primitives;
 using namespace mcpplibs::primitives::literals;
 

docs/api/zh/README.md

@@ -1,18 +1,19 @@
 # primitives API 文档
 
-> 适用模块：`import mcpplibs.primitives;`
+> 模块入口：`import mcpplibs.primitives;`
 
 ## 模块入口
 
-顶层模块：
+顶层导入：
 
 ```cpp
 import mcpplibs.primitives;
 ```
 
-该模块导出以下子模块：
+该模块会导出以下子模块：
 
 - `mcpplibs.primitives.underlying`
+- `mcpplibs.primitives.literals`
 - `mcpplibs.primitives.policy`
 - `mcpplibs.primitives.primitive`
 - `mcpplibs.primitives.operations`
@@ -21,20 +22,20 @@ import mcpplibs.primitives;
 
 ## 命名空间总览
 
-- `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 别名。
+- `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 别名。
 
 ## 核心概念与元信息
 
-### underlying 相关概念
+### underlying 概念
 
 - `underlying_type<T>`
 - `boolean_underlying_type<T>`
@@ -45,7 +46,7 @@ import mcpplibs.primitives;
 - `has_common_rep<LhsRep, RhsRep>`
 - `common_rep_t<LhsRep, RhsRep>`
 
-### policy 相关概念
+### policy 概念
 
 - `policy::policy_type<P>`
 - `policy::value_policy<P>`
@@ -56,7 +57,7 @@ import mcpplibs.primitives;
 
 ### primitive 元信息
 
-- `meta::traits<primitive<...>>`  
+- `meta::traits<primitive<...>>`
   暴露 `value_type / policies / value_policy / type_policy / error_policy / concurrency_policy`
 - `meta::make_primitive_t<T, PoliciesTuple>`
 
@@ -72,12 +73,12 @@ class primitive;
 - `value_type = T`
 - `policies = std::tuple<Policies...>`
 
-### 主要构造与赋值
+### 构造与赋值
 
 - `explicit primitive(T)`：同 underlying 构造。
-- `explicit primitive(U)`：跨 underlying 构造（是否允许由 type 策略决定）。
-- 支持同策略组下的拷贝/移动构造与赋值。
-- 支持同策略组、不同 underlying 的 primitive 互构造/赋值（受 type 策略约束）。
+- `explicit primitive(U)`：跨 underlying 构造，是否允许由 type policy 决定。
+- 支持同一 policy 集合下的拷贝/移动构造与赋值。
+- 当 type policy 允许时，支持跨 underlying primitive 的构造与赋值。
 
 ### 值访问与并发访问 API
 
@@ -89,23 +90,23 @@ class primitive;
 
 说明：
 
-- `store/compare_exchange` 支持同 underlying。
-- 在 type 策略允许时，`store/compare_exchange` 也支持跨 underlying 参数。
-- 并发访问能力由 `policy::concurrency::handler<..., void, ...>` 提供。
+- `store/compare_exchange` 始终支持同 underlying 类型。
+- 只有在 type policy 允许时，`store/compare_exchange` 才支持跨 underlying 参数。
+- 访问 API 由 `policy::concurrency::handler<..., void, ...>` 提供。
 
-### type 策略对跨 underlying 行为的影响
+### type policy 对跨 underlying 行为的影响
 
-- `policy::type::strict`：仅同类型允许，跨 underlying 构造/存储/CAS 不可用。
-- `policy::type::compatible`：要求同 underlying category 且可协商 `common_rep`。
-- `policy::type::transparent`：只要求可协商 `common_rep`。
+- `policy::type::strict`：只允许完全相同的类型。
+- `policy::type::compatible`：要求 underlying category 相同且存在有效的 `common_rep`。
+- `policy::type::transparent`：只要求存在有效的 `common_rep`。
 
-### 预定义别名（`types`）
+### 便捷别名（`types`）
 
 - 整型：`U8/U16/U32/U64`、`Size`、`Diff`、`I8/I16/I32/I64`
 - 浮点：`F32/F64/F80`
 - 布尔/字符：`Bool/UChar/Char8/Char16/Char32/WChar`
 
-用法示例：
+示例：
 
 ```cpp
 using value_t = mcpplibs::primitives::types::I32<
@@ -115,17 +116,20 @@ using value_t = mcpplibs::primitives::types::I32<
 
 ### 工厂函数与 literals
 
-- `with(value)`：从 underlying 值按默认策略构造 `primitive`
-- `with<Policies...>(value)`：构造时显式指定策略集合
-- `with(policies_tuple, value)`：复用已有策略元组
+- `with(value)`：从 underlying 值按默认 policy 构造 `primitive`。
+- `with<Policies...>(value)`：构造时显式指定 policy 集合。
+- `with(policies_tuple, value)`：复用已有的 policy tuple。
 - `mcpplibs::primitives::literals` 提供带校验的后缀，例如
   `_u8/_u16/_u32/_u64/_size/_diff`、`_i8/_i16/_i32/_i64`、
-  `_f32/_f32e/_f64/_f64e/_f80/_f80e`，以及
-  `_uchar/_char8/_char16/_char32/_wchar`
+  `_f32/_f32e/_f64/_f64e/_f80/_f80e`，以及字符后缀
+  `_uchar/_char8/_char16/_char32/_wchar`。
 
 示例：
 
 ```cpp
+import mcpplibs.primitives;
+import mcpplibs.primitives.literals;
+
 using namespace mcpplibs::primitives;
 using namespace mcpplibs::primitives::literals;
 
@@ -180,25 +184,25 @@ auto value = with<policy::value::checked, policy::error::expected>(42_i32);
 
 ### 混合操作支持
 
-对多数二元操作，支持以下三种形式：
+大多数二元操作支持：
 
 - `primitive op primitive`
 - `primitive op underlying`
 - `underlying op primitive`
 
-## `operators` 运算符重载
+## `operators` 重载
 
-若需要 `+ - * / % ...` 运算符语法，请引入：
+如果要使用 `+ - * / % ...` 语法，请引入：
 
 ```cpp
 using namespace mcpplibs::primitives::operators;
 ```
 
-重载结果同样是 `std::expected<...>`，不是裸值。
+运算符结果依然是 `std::expected<...>`，不是裸值。
 
 ## `conversion` API
 
-`conversion` 命名空间提供 underlying、primitive 以及混合路径之间的统一转换接口。
+`conversion` 命名空间提供 underlying、primitive 以及混合源/目标之间的统一转换接口。
 
 ### 常用结果类型与风险模型
 
@@ -218,15 +222,14 @@ using namespace mcpplibs::primitives::operators;
 
 说明：
 
-- `checked_cast` 与 `exact_cast` 返回 `cast_result<T>`
-- `saturating_cast` 会对数值溢出/下溢执行钳制
-- `truncating_cast` 适合浮点到整数的截断场景
-- 提供 underlying -> underlying、primitive -> primitive、
-  primitive -> underlying、underlying -> primitive 四类重载
+- `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。
+`algorithms` 命名空间提供 limits 元信息和 hash 辅助接口，适用于内建类型和受支持的自定义 underlying。
 
 ### Limits
 
@@ -248,21 +251,21 @@ using namespace mcpplibs::primitives::operators;
 
 ## policy API
 
-### 内置策略标签
+### 内建 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}`
 
-### 默认策略
+### 默认值
 
 - `policy::defaults::value = policy::value::checked`
 - `policy::defaults::type = policy::type::strict`
 - `policy::defaults::error = policy::error::throwing`
 - `policy::defaults::concurrency = policy::concurrency::none`
 
-### 错误码
+### 错误种类
 
 `policy::error::kind`：
 
@@ -278,7 +281,7 @@ using namespace mcpplibs::primitives::operators;
 
 ### 1) 注册 `underlying::traits<T>`
 
-需要提供：
+必须提供：
 
 - `value_type`
 - `rep_type`
@@ -288,15 +291,15 @@ using namespace mcpplibs::primitives::operators;
 - `from_rep(rep)`
 - `is_valid_rep(rep)`
 
-### 2) 自定义 common rep 协商
+### 2) 自定义 common-rep 协商
 
-可特化 `underlying::common_rep_traits<LhsRep, RhsRep>`，以覆盖默认 `std::common_type_t` 规则。
+可以特化 `underlying::common_rep_traits<LhsRep, RhsRep>`，覆盖默认的 `std::common_type_t` 行为。
 
-## 返回模型与错误处理模型
+## 返回值与错误模型
 
-- 绝大多数 operations/operators API 返回 `std::expected<...>`。
-- 当错误策略为 `policy::error::expected` 时，错误通过 `unexpected(policy::error::kind)` 返回。
-- 当错误策略为 `policy::error::throwing` 时，运行期错误会抛出异常（签名仍保持 `std::expected`）。
+- 大多数 operations/operators API 返回 `std::expected<...>`。
+- 使用 `policy::error::expected` 时，失败通过 `unexpected(policy::error::kind)` 返回。
+- 使用 `policy::error::throwing` 时，运行期失败会抛出异常，而 API 签名仍保持 `std::expected`。
 
 ## 最小示例
 

src/algorithms/limits.cppm

@@ -6,7 +6,7 @@ module;
 
 export module mcpplibs.primitives.algorithms.limits;
 
-import mcpplibs.primitives.underlying;
+import mcpplibs.primitives.underlying.traits;
 
 namespace mcpplibs::primitives::algorithms::details {