Skip to content

Commit 0788914

Browse files
LessUpLessUp
committed
docs: 重构文档信息架构以分离仓库入口与文档首页
- 将 README 文件精简为纯仓库入口，仅保留项目定位和最短命令示例 - 将 docs/index.md 改为完整的文档首页，包含项目定位、目标读者和阅读路径 - 重构导航栏为"概览、快速开始、使用指南、参考、归档"的清晰结构 - 统一侧边栏层级，避免混用不同语义的导航分类 - 更新元数据描述和社交媒体标签以匹配新的文档定位
1 parent 3767288 commit 0788914

5 files changed

Lines changed: 156 additions & 349 deletions

File tree

‎README.md‎

Lines changed: 21 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Encoding Algorithms Collection
1+
# Encoding
22

33
[![CI](https://github.com/LessUp/encoding/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/encoding/actions/workflows/ci.yml)
44
[![Deploy Docs](https://github.com/LessUp/encoding/actions/workflows/pages.yml/badge.svg)](https://github.com/LessUp/encoding/actions/workflows/pages.yml)
@@ -7,75 +7,41 @@
77
![Go](https://img.shields.io/badge/Go-1.21+-00ADD8.svg)
88
![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)
99

10-
English | [简体中文](README.zh-CN.md)
10+
English | [简体中文](README.zh-CN.md) | [Docs](https://lessup.github.io/encoding/)
1111

12-
> 📖 **Docs**: [https://lessup.github.io/encoding/](https://lessup.github.io/encoding/)
12+
Encoding is a multi-language collection of classic compression algorithms for learning, implementation comparison, and cross-language verification.
1313

14-
A multi-language implementation of classic compression encoding algorithms for learning and comparison.
14+
## Repository Overview
1515

16-
## Algorithms
17-
18-
| Algorithm | C++ | Go | Rust | Description |
19-
|-----------|-----|-----|------|-------------|
20-
| **Arithmetic Coding** | ✅ | ✅ | ✅ | Entropy-optimal encoding with fractional bit precision |
21-
| **Huffman Coding** | ✅ | ✅ | ✅ | Classic prefix-free variable-length encoding |
22-
| **Range Coder** | ✅ | ✅ | ✅ | Arithmetic coding variant, balanced speed & ratio |
23-
| **Run-Length Encoding** | ✅ | ✅ | ✅ | Simple repeated symbol compression |
24-
25-
## Features
26-
27-
- **Multi-Language**: Same algorithms in C++17, Go, and Rust for cross-language comparison
28-
- **Cross-Platform**: Verified on Linux, macOS, and Windows
29-
- **Benchmarked**: Performance comparison across implementations
30-
- **Well-Tested**: Unit tests, property tests, and cross-language verification
31-
- **Educational**: Clear, documented implementations focused on learning
16+
- Four algorithms: Huffman, Arithmetic Coding, Range Coder, and RLE
17+
- Three language tracks: C++17, Go, and Rust
18+
- Unified CLI conventions and shared binary formats for cross-language validation
19+
- Dedicated docs site for getting started, algorithm guides, and project structure
3220

3321
## Quick Start
3422

35-
### C++ (Arithmetic Coding)
36-
37-
```bash
38-
cd arithmetic/cpp
39-
mkdir build && cd build
40-
cmake .. && make
41-
./arithmetic_codec encode input.txt output.bin
42-
./arithmetic_codec decode output.bin restored.txt
43-
```
44-
45-
### Go
46-
4723
```bash
48-
cd arithmetic/go
49-
go build ./...
50-
go test ./...
24+
make build
25+
make test
26+
make bench
5127
```
5228

53-
### Rust
29+
If you want to start from a single algorithm first:
5430

5531
```bash
56-
cd arithmetic/rust
57-
cargo build --release
58-
cargo test
59-
```
60-
61-
## Project Structure
62-
63-
```
64-
encoding/
65-
├── arithmetic/ # Arithmetic coding (C++, Go, Rust)
66-
├── huffman/ # Huffman coding (C++, Go, Rust)
67-
├── range/ # Range coder (C++, Go, Rust)
68-
├── rle/ # Run-length encoding (C++, Go, Rust)
69-
├── docs/ # Documentation
70-
└── .github/workflows/ # CI
32+
cd huffman/cpp
33+
g++ -std=c++17 -O2 main.cpp -o huffman_cpp
34+
./huffman_cpp encode input.bin output.huf
35+
./huffman_cpp decode output.huf restored.bin
7136
```
7237

73-
## Documentation
38+
## Read Next
7439

75-
- [Online Docs](https://lessup.github.io/encoding/)
76-
- [Algorithm Deep Dives](https://lessup.github.io/encoding/guide/algorithms)
40+
- [Documentation Home](https://lessup.github.io/encoding/)
41+
- [Getting Started](https://lessup.github.io/encoding/guide/getting-started)
42+
- [Algorithms Guide](https://lessup.github.io/encoding/guide/algorithms)
7743
- [Project Structure](https://lessup.github.io/encoding/guide/project-structure)
7844

7945
## License
8046

81-
MIT License
47+
MIT License.

‎README.zh-CN.md‎

Lines changed: 22 additions & 239 deletions
Original file line numberDiff line numberDiff line change
@@ -1,264 +1,47 @@
1-
# encoding 编码算法集合 | Encoding Algorithms Collection
1+
# Encoding —— 编码算法集合
22

33
[![CI](https://github.com/LessUp/encoding/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/encoding/actions/workflows/ci.yml)
44
[![Deploy Docs](https://github.com/LessUp/encoding/actions/workflows/pages.yml/badge.svg)](https://github.com/LessUp/encoding/actions/workflows/pages.yml)
55
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6-
7-
[English](README.md) | 简体中文
86
![C++](https://img.shields.io/badge/C++-17-blue.svg)
97
![Go](https://img.shields.io/badge/Go-1.21+-00ADD8.svg)
108
![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)
119

12-
> 📖 **文档站 | Docs**：[https://lessup.github.io/encoding/](https://lessup.github.io/encoding/)
13-
14-
> 🎓 一个用多种语言实现经典压缩编码算法的学习与对比项目
15-
>
16-
> 🎓 A multi-language implementation of classic compression encoding algorithms for learning and comparison
17-
18-
---
19-
20-
## 🎯 Why This Project | 为什么做这个项目
21-
22-
**中文**：
23-
- 📚 **学习导向**：通过阅读和对比不同语言的实现，深入理解压缩算法原理
24-
- 🔬 **性能对比**：在相同算法下对比 C++、Go、Rust 的性能差异
25-
- 🔄 **跨语言兼容**：所有实现使用相同的文件格式，支持交叉验证
26-
- 🛠️ **实践友好**：简单一致的 CLI 接口，便于快速上手和实验
27-
28-
**English**:
29-
- 📚 **Learning-oriented**: Understand compression algorithms by reading and comparing implementations across languages
30-
- 🔬 **Performance comparison**: Compare C++, Go, and Rust performance for the same algorithms
31-
- 🔄 **Cross-language compatible**: All implementations use the same file format for cross-validation
32-
- 🛠️ **Practice-friendly**: Simple and consistent CLI interface for quick experimentation
33-
34-
---
35-
36-
## 📊 Algorithm Comparison | 算法对比
37-
38-
| Algorithm | Best For | Compression Ratio | Speed | Languages |
39-
|-----------|----------|-------------------|-------|-----------|
40-
| **Huffman** | General purpose, text | Medium | Fast | C++, Go, Rust |
41-
| **Arithmetic** | Maximum compression | High | Medium | C++, Go, Rust |
42-
| **Range Coder** | Balanced performance | High | Fast | C++, Go, Rust |
43-
| **RLE** | Repetitive data | Variable* | Very Fast | C++, Go, Rust |
44-
45-
\* RLE compression ratio depends heavily on input data characteristics
10+
[English](README.md) | 简体中文 | [文档站](https://lessup.github.io/encoding/)
4611

47-
| 算法 | 适用场景 | 压缩率 | 速度 | 支持语言 |
48-
|------|----------|--------|------|----------|
49-
| **Huffman** | 通用、文本 | 中等 | 快 | C++, Go, Rust |
50-
| **Arithmetic** | 追求最大压缩 | 高 | 中等 | C++, Go, Rust |
51-
| **Range Coder** | 平衡性能 | 高 | 快 | C++, Go, Rust |
52-
| **RLE** | 重复数据 | 可变* | 非常快 | C++, Go, Rust |
12+
Encoding 是一个面向学习、实现对比与跨语言验证的经典压缩算法集合，使用 C++17、Go 和 Rust 提供对应实现。
5313

54-
\* RLE 压缩率高度依赖输入数据特征
14+
## 仓库入口
5515

56-
---
16+
- 覆盖 Huffman、算术编码、区间编码、RLE 四类经典算法
17+
- 每种算法同时提供 C++17、Go、Rust 三套实现
18+
- 统一 CLI 约定与二进制格式，便于跨语言互相编码/解码验证
19+
- 详细使用说明、算法导读和目录结构统一放在文档站维护
5720

58-
## 🚀 Quick Start | 快速开始
21+
## 快速开始
5922

60-
### Prerequisites | 前置要求
61-
62-
- C++ compiler (g++ 9+ or clang++ 10+)
63-
- Go 1.21+
64-
- Rust 1.70+
65-
- Python 3.8+ (for benchmarks)
23+
```bash
24+
make build
25+
make test
26+
make bench
27+
```
6628

67-
### Build & Run | 构建与运行
29+
如果你想先从单个算法开始：
6830

6931
```bash
70-
# Clone the repository | 克隆仓库
71-
git clone https://github.com/LessUp/encoding.git
72-
cd encoding
73-
74-
# Example: Huffman encoding | 示例：Huffman 编码
7532
cd huffman/cpp
7633
g++ -std=c++17 -O2 main.cpp -o huffman_cpp
77-
78-
# Encode | 编码
7934
./huffman_cpp encode input.bin output.huf
80-
81-
# Decode | 解码
8235
./huffman_cpp decode output.huf restored.bin
8336
```
8437

85-
### Run Benchmarks | 运行基准测试
86-
87-
```bash
88-
# Generate test data and run all benchmarks
89-
# 生成测试数据并运行所有基准测试
90-
python3 scripts/run_all_bench.py
91-
```
92-
93-
---
94-
95-
## 📁 Project Structure | 项目结构
96-
97-
```
98-
encoding/
99-
├── huffman/ # Huffman encoding | Huffman 编码
100-
│ ├── cpp/ # C++ implementation
101-
│ ├── go/ # Go implementation
102-
│ ├── rust/ # Rust implementation
103-
│ └── benchmark/ # Cross-language benchmark
104-
├── arithmetic/ # Arithmetic coding | 算术编码
105-
│ ├── cpp/ # C++ implementation
106-
│ ├── go/ # Go implementation
107-
│ ├── rust/ # Rust implementation
108-
│ └── benchmark/ # Cross-language benchmark
109-
├── range/ # Range coder | 区间编码
110-
│ ├── cpp/ # C++ implementation
111-
│ ├── go/ # Go implementation (library + CLI)
112-
│ ├── rust/ # Rust implementation (library + CLI)
113-
│ └── benchmark/ # Cross-language benchmark
114-
├── rle/ # RLE encoding | 游程编码
115-
│ ├── cpp/ # C++ implementation
116-
│ ├── go/ # Go implementation
117-
│ ├── rust/ # Rust implementation
118-
│ └── benchmark/ # Cross-language benchmark
119-
├── scripts/ # Utility scripts | 工具脚本
120-
└── tests/ # Test data generation | 测试数据生成
121-
```
122-
123-
---
124-
125-
## 📖 Algorithm Details | 算法详解
126-
127-
### Huffman Encoding | Huffman 编码
128-
129-
基于前缀码的无损压缩算法。实现中先扫描输入统计频率，构建 Huffman 树，再按位写入编码结果。
130-
131-
A lossless compression algorithm based on prefix codes. The implementation scans input to build frequency statistics, constructs a Huffman tree, and writes bit-encoded output.
132-
133-
**File Format | 文件格式**:
134-
- Magic: `HFMN` (4 bytes)
135-
- Frequency table (257 × 4 bytes, little-endian)
136-
- Encoded data (bit stream)
137-
138-
### Arithmetic Coding | 算术编码
139-
140-
使用区间逐步细分表示整段消息的概率，压缩效率更接近信息熵上界。
141-
142-
Uses interval subdivision to represent message probability, achieving compression efficiency closer to the entropy limit.
143-
144-
### Range Coder | 区间编码
145-
146-
一种等价于算术编码的实现方式，但常在实践中更高效。
147-
148-
An implementation equivalent to arithmetic coding but often more efficient in practice.
149-
150-
**API (library)**:
151-
- Go: `rangecoder.Encode(data []byte) ([]byte, error)`
152-
- Rust: `rangecoder::encode(input: &[u8]) -> Result<Vec<u8>, RangeError>`
153-
154-
**CLI**:
155-
```bash
156-
# C++
157-
./rangecoder_cpp encode input.bin output.rcnc
158-
# Go
159-
./rangecoder_go encode input.bin output.rcnc
160-
# Rust
161-
cargo run --bin rangecoder -- encode input.bin output.rcnc
162-
```
163-
164-
### Run-Length Encoding (RLE) | 游程编码
165-
166-
适用于包含大量相同字节连续重复的数据。
167-
168-
Suitable for data with many consecutive repeated bytes.
169-
170-
**File Format | 文件格式**:
171-
- Repeated `(count, value)` pairs
172-
- `count`: 4 bytes, little-endian, unsigned integer
173-
- `value`: 1 byte
174-
175-
---
176-
177-
## 🧪 Testing | 测试
178-
179-
### Correctness Verification | 正确性验证
180-
181-
All implementations pass encode-decode round-trip tests:
182-
183-
所有实现都通过编码-解码往返测试：
184-
185-
```bash
186-
# Encode with C++, decode with Go (cross-language test)
187-
./huffman_cpp encode input.bin encoded.huf
188-
./huffman_go decode encoded.huf decoded.bin
189-
diff input.bin decoded.bin # Should produce no output
190-
```
191-
192-
### Benchmark Results | 基准测试结果
193-
194-
Run `python scripts/run_all_bench.py` to generate benchmark reports in `reports/` directory.
195-
196-
运行 `python scripts/run_all_bench.py` 在 `reports/` 目录生成基准测试报告。
197-
198-
---
199-
200-
## 🤝 Contributing | 贡献
201-
202-
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
203-
204-
欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。
205-
206-
### Quick Contribution Guide | 快速贡献指南
207-
208-
1. Fork the repository | Fork 仓库
209-
2. Create a feature branch | 创建功能分支
210-
3. Make your changes | 进行修改
211-
4. Run tests | 运行测试
212-
5. Submit a PR | 提交 PR
213-
214-
---
215-
216-
## 📜 Code of Conduct | 行为准则
217-
218-
This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
219-
220-
本项目遵循 [Contributor Covenant 行为准则](CODE_OF_CONDUCT.md)。
221-
222-
---
223-
224-
## 🔒 Security | 安全
225-
226-
For security issues, please see [SECURITY.md](SECURITY.md).
227-
228-
安全问题请查看 [SECURITY.md](SECURITY.md)。
229-
230-
---
231-
232-
## 📄 License | 许可证
233-
234-
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
235-
236-
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
237-
238-
---
239-
240-
## 🙏 Acknowledgments | 致谢
241-
242-
- Classic compression algorithm literature and textbooks
243-
- The open source community for inspiration and best practices
244-
245-
---
246-
247-
## 📈 Roadmap | 路线图
38+
## 接下来读什么
24839

249-
- [x] All 4 algorithms implemented in C++, Go, Rust
250-
- [x] Cross-language encode/decode compatibility for all algorithms
251-
- [x] Unified CLI interface and cross-language benchmarks
252-
- [ ] Add more compression algorithms (LZ77, LZ78, LZSS)
253-
- [ ] Add Python implementations
254-
- [ ] Add WebAssembly builds for browser demos
255-
- [ ] Add interactive visualization of compression process
256-
- [ ] Add more real-world test datasets
40+
- [文档首页](https://lessup.github.io/encoding/)
41+
- [快速开始](https://lessup.github.io/encoding/guide/getting-started)
42+
- [算法详解](https://lessup.github.io/encoding/guide/algorithms)
43+
- [项目结构](https://lessup.github.io/encoding/guide/project-structure)
25744

258-
---
45+
## 许可证
25946

260-
<p align="center">
261-
Made with ❤️ for learning compression algorithms
262-
<br>
263-
用 ❤️ 制作，为了学习压缩算法
264-
</p>
47+
MIT License。

0 commit comments

Comments
 (0)