Skip to content

Commit 8b8928b

Browse files
docs: Update README for improved clarity and add Chinese translation
Signed-off-by: FrozenlemonTee <1115306170@qq.com>
1 parent f2f2b7f commit 8b8928b

File tree

2 files changed

+247
-56
lines changed

2 files changed

+247
-56
lines changed

README.md

Lines changed: 56 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# mcpplibs primitives
22

3-
> C++23 模块化原语库 - `import mcpplibs.primitives;`
3+
> C++23 modular primitives library - `import mcpplibs.primitives;`
44
55
[![d2x](https://img.shields.io/badge/d2x-ok-green.svg)](https://github.com/d2learn/d2x)
66
[![Online-ebook](https://img.shields.io/badge/online-ebook-orange.svg)](https://github.com/d2learn/d2x)
@@ -10,28 +10,28 @@
1010
| --- |
1111
| [d2x Tool](https://github.com/d2learn/d2x) - [Docs](https://mcpp-community.github.io/d2mystl) - [Forum](https://mcpp.d2learn.org/forum) |
1212

13-
本仓库提供可配置的 `primitive` 基础设施(`underlying traits``policy``operations/dispatcher`),用于统一约束数值计算、错误处理与并发访问语义。
13+
This repository provides configurable `primitive` infrastructure (`underlying traits`, `policy`, and `operations/dispatcher`) to unify numeric behavior, error handling, and concurrency access semantics.
1414

1515
> [!WARNING]
16-
> 当前项目仍在快速演进中,API 可能发生变更。
16+
> The project is still evolving quickly, and APIs may change.
1717
18-
## 特性
18+
## Features
1919

20-
- **C++23 模块**`import mcpplibs.primitives;`
21-
- **双构建系统**同时支持 xmake CMake
22-
- **策略驱动行为**值/类型/错误/并发策略可组合配置
23-
- **混合运算支持**支持 `primitive` `underlying` 的混合二元运算
24-
- **并发访问接口**`primitive::load/store/compare_exchange`
20+
- **C++23 modules**`import mcpplibs.primitives;`
21+
- **Dual build systems**both xmake and CMake are supported
22+
- **Policy-driven behavior**value/type/error/concurrency policies are composable
23+
- **Mixed operations support**binary operations between `primitive` and `underlying` are supported
24+
- **Concurrency access APIs**`primitive::load/store/compare_exchange`
2525

2626
## Operators
2727

28-
该库为 `primitive` 提供了常见的一元、算术、位运算与比较操作。
29-
算术结果通过统一分发链路返回 `std::expected<..., policy::error::kind>`
28+
The library provides unary, arithmetic, bitwise, and comparison operations for `primitive`.
29+
Arithmetic paths are dispatched through a unified pipeline and return `std::expected<..., policy::error::kind>`.
3030

31-
- 值策略(`policy::value::checked` / `policy::value::saturating` / `policy::value::unchecked`)决定溢出行为;
32-
- 错误策略(`policy::error::throwing` / `policy::error::expected` / `policy::error::terminate`)决定错误传播方式。
31+
- Value policies (`policy::value::checked` / `policy::value::saturating` / `policy::value::unchecked`) define overflow behavior.
32+
- Error policies (`policy::error::throwing` / `policy::error::expected` / `policy::error::terminate`) define how errors are propagated.
3333

34-
示例:
34+
Example:
3535

3636
```cpp
3737
import std;
@@ -50,29 +50,29 @@ auto maybe_overflow =
5050
checked_t{std::numeric_limits<int>::max()} + checked_t{1};
5151
```
5252
53-
## Policy 协议命名空间
53+
## Policy Protocol Namespaces
5454
55-
自定义 policy 时,协议入口按职责拆分到子命名空间:
55+
When implementing custom policies, protocol entry points are split by responsibility:
5656
5757
- `policy::type::handler` / `policy::type::handler_available`
5858
- `policy::concurrency::handler` / `policy::concurrency::injection`
5959
- `policy::value::handler` / `policy::value::decision`
6060
- `policy::error::handler` / `policy::error::request` / `policy::error::kind`
6161
62-
预设 policy 标签:
62+
Built-in policy tags:
6363
6464
- `policy::value::{checked, unchecked, saturating}`
6565
- `policy::type::{strict, compatible, transparent}`
6666
- `policy::error::{throwing, expected, terminate}`
6767
- `policy::concurrency::{none, fenced, fenced_relaxed, fenced_acq_rel, fenced_seq_cst}`
6868
69-
并发策略说明:
69+
Concurrency notes:
7070
71-
- `fenced*` 系列是操作级并发语义,通过策略注入内存序 fence;
72-
- `primitive` 存储仍保持统一、零额外存储抽象;
73-
- `primitive::load/store/compare_exchange` 由并发策略协议提供,若策略未实现会在编译期报错。
71+
- `fenced*` policies provide operation-level concurrency semantics with injected memory-order fences.
72+
- `primitive` storage keeps a uniform, zero-extra-storage abstraction.
73+
- `primitive::load/store/compare_exchange` are provided by concurrency policy protocols and fail at compile time if unsupported.
7474
75-
示例(并发访问 API):
75+
Example (concurrent access APIs):
7676
7777
```cpp
7878
using shared_t = primitive<int, policy::value::checked,
@@ -88,42 +88,42 @@ if (v.compare_exchange(expected, 3)) {
8888
}
8989
```
9090

91-
默认策略位于 `policy::defaults`
91+
Default policies are available under `policy::defaults`:
9292

9393
- `policy::defaults::value`
9494
- `policy::defaults::type`
9595
- `policy::defaults::error`
9696
- `policy::defaults::concurrency`
9797

98-
## 示例程序
98+
## Examples
9999

100-
- `ex01_default_arithmetic`: 默认策略下的基础算术运算示例。
101-
- `ex02_type_policy`: 展示 `strict/compatible` 的类型协商差异,并包含 `underlying` 构造路径对 type 策略的影响。
102-
- `ex03_value_policy`: 展示 `checked/unchecked/saturating`,并包含与 `underlying` 的混合二元运算行为。
103-
- `ex04_error_policy`: 展示不同 error 策略的处理方式。
104-
- `ex05_concurrency_policy`: 读写组合并发场景(writer `store` + reader `add/sub` + `CAS`)示例。
105-
- `ex06_custom_underlying`: 自定义 underlying traitsrep 校验与 common rep 扩展。
106-
- `ex07_custom_policy`: 自定义策略协议实现示例。
107-
- `ex08_custom_operation`: 自定义 operation 扩展示例。
100+
- `ex01_default_arithmetic`: Basic arithmetic under default policies.
101+
- `ex02_type_policy`: Type negotiation with `strict/compatible`, including how type policy affects construction from `underlying`.
102+
- `ex03_value_policy`: `checked/unchecked/saturating` behavior, including mixed binary operations with `underlying`.
103+
- `ex04_error_policy`: Error-handling behavior across different error policies.
104+
- `ex05_concurrency_policy`: Representative mixed read/write concurrency workload (writer `store` + reader `add/sub` + `CAS`).
105+
- `ex06_custom_underlying`: Custom underlying traits, rep validation, and common-rep extension.
106+
- `ex07_custom_policy`: Custom policy protocol implementation.
107+
- `ex08_custom_operation`: Custom operation extension.
108108

109-
## 项目结构
109+
## Project Layout
110110

111111
```
112112
mcpplibs-primitives/
113-
├── src/ # 模块源码
114-
│ ├── primitives.cppm # 顶层聚合模块
115-
│ ├── primitive/ # primitive 定义与 traits
116-
│ ├── policy/ # policy 标签与协议实现
113+
├── src/ # module sources
114+
│ ├── primitives.cppm # top-level aggregate module
115+
│ ├── primitive/ # primitive definitions and traits
116+
│ ├── policy/ # policy tags and protocol implementations
117117
│ ├── operations/ # operation tags / dispatcher / operators
118-
│ └── underlying/ # underlying traits common_rep
119-
├── examples/ # ex01 ~ ex08 示例
120-
├── tests/ # 测试入口与 basic 测试集
121-
├── xmake.lua # xmake 构建脚本
122-
├── CMakeLists.txt # CMake 构建脚本
123-
└── .xlings.json # xlings 包描述文件
118+
│ └── underlying/ # underlying traits and common_rep
119+
├── examples/ # ex01 ~ ex08 examples
120+
├── tests/ # test entry and basic test suite
121+
├── xmake.lua # xmake build script
122+
├── CMakeLists.txt # CMake build script
123+
└── .xlings.json # xlings package descriptor
124124
```
125125

126-
## 快速开始
126+
## Quick Start
127127

128128
```cpp
129129
import std;
@@ -138,24 +138,24 @@ int main() {
138138
}
139139
```
140140

141-
## 安装与配置
141+
## Installation and Setup
142142

143143
```bash
144144
xlings install
145145
```
146146

147-
## 构建与运行
147+
## Build and Run
148148

149-
**使用 xmake**
149+
**Using xmake**
150150

151151
```bash
152152
xmake build mcpplibs-primitives
153-
xmake run basic # 等价于 ex01_default_arithmetic
153+
xmake run basic # equivalent to ex01_default_arithmetic
154154
xmake run ex05_concurrency_policy
155155
xmake run primitives_test
156156
```
157157

158-
**使用 CMake**
158+
**Using CMake**
159159

160160
```bash
161161
cmake -B build -G Ninja
@@ -165,7 +165,7 @@ cmake --build build --target basic_tests
165165
ctest --test-dir build --output-on-failure
166166
```
167167

168-
## 集成到构建工具
168+
## Build System Integration
169169

170170
### xmake
171171

@@ -182,10 +182,10 @@ target("myapp")
182182
set_policy("build.c++.modules", true)
183183
```
184184

185-
## 相关链接
185+
## Related Links
186186

187-
- [mcpp-style-ref | 现代 C++ 编码/项目风格参考](https://github.com/mcpp-community/mcpp-style-ref)
188-
- [d2mystl | 从零实现一个迷你STL库](https://github.com/mcpp-community/d2mystl)
189-
- [mcpp 社区官网](https://mcpp.d2learn.org)
190-
- [mcpp | 现代 C++ 爱好者论坛](https://mcpp.d2learn.org/forum)
191-
- [入门教程: 动手学现代 C++](https://github.com/Sunrisepeak/mcpp-standard)
187+
- [mcpp-style-ref | Modern C++ coding and project style reference](https://github.com/mcpp-community/mcpp-style-ref)
188+
- [d2mystl | Build a mini STL from scratch](https://github.com/mcpp-community/d2mystl)
189+
- [mcpp community website](https://mcpp.d2learn.org)
190+
- [mcpp forum](https://mcpp.d2learn.org/forum)
191+
- [Getting Started: Learn Modern C++ by Building](https://github.com/Sunrisepeak/mcpp-standard)

0 commit comments

Comments
 (0)