# encconv

**Repository Path**: arhunn/encconv

## Basic Information

- **Project Name**: encconv
- **Description**: No description available
- **Primary Language**: C/C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EncConv - 文本编码转换工具

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![C++17](https://img.shields.io/badge/C%2B%2B-17-blue.svg)](https://isocpp.org/)
[![Build: CMake](https://img.shields.io/badge/Build-CMake-green.svg)](https://cmake.org/)
[![CI](https://github.com/yourname/encconv/workflows/CI/badge.svg)](.github/workflows/ci.yml)
[![Tests: 89/89](https://img.shields.io/badge/Tests-89%2F89%20passing-brightgreen.svg)](tests/)

---

**English** | [中文](#中文说明)

---

## Features

- **Auto Detection**: Based on libchardet (Mozilla charset detection engine), supports 40+ encodings with confidence score
- **Bidirectional Conversion**: Based on libiconv, supports UTF-8/GBK/GB2312/GB18030/Big5/Shift_JIS and more
- **Batch Processing**: Scan directories and batch detect/convert all matching text files
- **Dual Interface**: CLI for scripting, Qt5 GUI with visual file tree and real-time log
- **Cross-Platform**: Core library is pure C++17 with zero Qt dependency
- **pimpl Design**: Detector/Converter use pimpl for dependency isolation; EncConv uses composition

## Supported Encodings

| Category | Encodings |
|----------|-----------|
| Unicode | UTF-8, UTF-8-BOM, UTF-16LE, UTF-16BE |
| Chinese | GB2312, GBK, GB18030, Big5 |
| Japanese | Shift_JIS |
| Western | ISO-8859-1, Windows-1252 |

## Quick Start

### Prerequisites

- CMake 3.20+
- MSVC 2022 (Windows) or GCC (Linux)
- vcpkg (for libiconv, GTest)
- Qt5 (GUI only)
- Ninja (recommended)

### Build

```bash
# Clone with submodules
git clone --recursive https://gitee.com/yourname/encconv.git
cd encconv

# Configure (set environment variables first)
# Windows PowerShell:
$env:VCPKG_ROOT = "D:/vcpkg"
$env:QT_DIR = "C:/Qt/5.15.2/msvc2019_64"
cmake --preset windows-debug

# Or Linux:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -G Ninja

# Build
cmake --build build/windows-debug

# Run tests
cd build/windows-debug && ctest --output-on-failure
```

### Usage

```bash
# CLI - Detect mode (default)
encconv /path/to/directory

# CLI - Convert mode
encconv -c utf8 /path/to/directory

# CLI - With options
encconv -c utf8 -o /output/dir --ext .cpp --ext .h /path/to/directory

# GUI
encconv_gui
```

## Project Structure

```
encconv/
├── apps/cli/          # CLI application
├── apps/gui/          # Qt5 GUI application
├── lib/               # Core library
├── tests/             # Unit & integration tests
├── third_party/       # git submodule (libchardet)
├── docs/              # Documentation
├── CMakeLists.txt
├── CMakePresets.json
└── README.md
```

## Documentation

- [Architecture](ARCHITECTURE.md) - Module design, data flow
- [Build Guide](docs/BUILD.md) - Detailed build instructions
- [User Manual](docs/USAGE.md) - CLI parameters, GUI operations
- [API Reference](docs/API.md) - Library API with examples
- [Contributing](docs/CONTRIBUTING.md) - Code style, test requirements

## Tests

82/82 tests passing (100%), covering types, detection, conversion, CLI args parsing, and integration tests.

## License

MIT License

---

<a id="中文说明"></a>

## 特性

- **自动检测**：基于 libchardet（Mozilla 字符集检测引擎），支持 40+ 编码自动识别，返回置信度评分
- **双向转换**：基于 libiconv，支持 UTF-8/GBK/GB2312/GB18030/Big5/Shift_JIS 等编码互转
- **批量处理**：一键扫描目录，批量检测/转换所有匹配的文本文件
- **双界面**：CLI 适合脚本集成，Qt5 GUI 提供可视化文件树和实时日志
- **跨平台**：核心库纯 C++17，零 Qt 依赖，可嵌入任意 C++ 项目
- **组合设计**：Detector/Converter 使用 pimpl 隔离依赖；EncConv 使用组合模式

## 支持的编码

| 类别 | 编码 |
|------|------|
| Unicode | UTF-8, UTF-8-BOM, UTF-16LE, UTF-16BE |
| 中文 | GB2312, GBK, GB18030, Big5 |
| 日文 | Shift_JIS |
| 西欧 | ISO-8859-1, Windows-1252 |

## 快速开始

### 环境要求

- CMake 3.20+
- MSVC 2022（Windows）或 GCC（Linux）
- vcpkg（用于 libiconv、GTest）
- Qt5（仅 GUI 需要）
- Ninja（推荐构建后端）

### 编译

```bash
# 克隆项目（包含子模块）
git clone --recursive https://gitee.com/yourname/encconv.git
cd encconv

# 配置（先设置环境变量）
# Windows PowerShell:
$env:VCPKG_ROOT = "D:/vcpkg"
$env:QT_DIR = "C:/Qt/5.15.2/msvc2019_64"
cmake --preset windows-debug

# 或 Linux:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -G Ninja

# 编译
cmake --build build/windows-debug

# 运行测试
cd build/windows-debug && ctest --output-on-failure
```

### 使用

```bash
# CLI - 检测模式（默认）
encconv /path/to/directory

# CLI - 转换模式
encconv -c utf8 /path/to/directory

# CLI - 带选项
encconv -c utf8 -o /output/dir --ext .cpp --ext .h /path/to/directory

# GUI
encconv_gui
```

## 项目结构

```
encconv/
├── apps/cli/          # 命令行工具
├── apps/gui/          # Qt5 图形界面
├── lib/               # 核心库
├── tests/             # 单元和集成测试
├── third_party/       # git 子模块 (libchardet)
├── docs/              # 文档
├── CMakeLists.txt
├── CMakePresets.json
└── README.md
```

## 文档

- [架构设计](ARCHITECTURE.md) - 模块设计、数据流
- [构建指南](docs/BUILD.md) - 详细编译步骤
- [使用手册](docs/USAGE.md) - CLI 参数、GUI 操作
- [API 参考](docs/API.md) - 库 API 文档和示例
- [开发指南](docs/CONTRIBUTING.md) - 代码规范、测试要求

## 测试

82/82 测试全部通过（100%），涵盖类型、检测、转换、CLI 参数解析和集成测试。

## 许可证

MIT License