From 1c6d299efa031b127ff67a6109171697d9a3c7c0 Mon Sep 17 00:00:00 2001 From: lionsoul2014 Date: Wed, 25 Feb 2026 22:21:31 +0800 Subject: [PATCH] add english readme for c++ binding --- README.md | 2 +- README_zh.md | 2 +- binding/cpp/README.md | 164 +++++++++++++++++++++------------------ binding/cpp/README_zh.md | 125 +++++++++++++++++++++++++++++ 4 files changed, 216 insertions(+), 77 deletions(-) create mode 100644 binding/cpp/README_zh.md diff --git a/README.md b/README.md index a181d6f..8f324f2 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ For API introductions, usage documentation, and test programs, please refer to t | [Csharp](binding/csharp) | csharp query client | :white_check_mark: | :white_check_mark: | | [Erlang](binding/erlang/README.md) | erlang query client | :white_check_mark: | :x: | | [Nginx](binding/nginx) | nginx extension query client | :white_check_mark: | :x: | -| [C++](binding/cpp) | C++ query client | :white_check_mark: | :white_check_mark: | +| [C++](binding/cpp/README.md) | C++ query client | :white_check_mark: | :white_check_mark: | The following toolchain implementations are contributed by community developers via third-party repositories: diff --git a/README_zh.md b/README_zh.md index 177988c..4cec751 100644 --- a/README_zh.md +++ b/README_zh.md @@ -48,7 +48,7 @@ API 介绍，使用文档和测试程序请参考对应 `searcher` 查询客户 | [Csharp](binding/csharp) | csharp 查询客户端 | :white_check_mark: | :white_check_mark: | | [Erlang](binding/erlang/README_zh.md) | erlang 查询客户端 | :white_check_mark: | :x: | | [Nginx](binding/nginx) | nginx 扩展查询客户端 | :white_check_mark: | :x: | -| [C++](binding/cpp) | C++ xdb 查询客户端 | :white_check_mark: | :white_check_mark: | +| [C++](binding/cpp/README_zh.md) | C++ 查询客户端 | :white_check_mark: | :white_check_mark: | 以下工具链实现由社区开发者通过第三方仓库贡献： diff --git a/binding/cpp/README.md b/binding/cpp/README.md index a14768c..57e0938 100644 --- a/binding/cpp/README.md +++ b/binding/cpp/README.md @@ -1,51 +1,58 @@ -# ip2region xdb C++ 实现 +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) + +# ip2region C++ query client + +## 0. File Description -## 0. 文件说明 ``` -Makefile --------- 构建 +Makefile --------- Build -src ------------------ 源文件目录 -src/base.* ----------- 常量及工具函数 -src/ip.* ------------- 实现 IP 处理 -src/header.* --------- 实现 xdb 头部解析 -src/search.* --------- 实现 xdb 查找 -src/bench.* ---------- 实现 查找 测速 -src/make.* ----------- 实现 生成 xdb 文件 -src/edit.* ----------- 实现 原始数据编辑 +src ------------------ Source directory +src/base.* ----------- Constants and utility functions +src/ip.* ------------- IP processing implementation +src/header.* --------- xdb header parsing implementation +src/search.* --------- xdb search implementation +src/bench.* ---------- Search benchmarking implementation +src/make.* ----------- xdb file generation implementation +src/edit.* ----------- Raw data editing implementation -test ---------------- 测试目录 -test/header.cc ------ 测试 头部 -test/search.cc ------ 测试 查找 -test/bench.cc ------- 测速 -test/make.cc -------- 生成 xdb 文件 -test/edit_v4.cc ----- 测试 原始数据编辑(ipv4) -test/edit_v6.cc ----- 测试 原始数据编辑(ipv6) +test ---------------- Test directory +test/header.cc ------ Test header +test/search.cc ------ Test search +test/bench.cc ------- Benchmarking +test/make.cc -------- Generate xdb file +test/edit_v4.cc ----- Test raw data editing (ipv4) +test/edit_v6.cc ----- Test raw data editing (ipv6) -bin --------------- 可执行文件目录(通过 make 生成) -bin/header -------- 测试 头部 -bin/search -------- 测试 查找 -bin/bench --------- 测速 -bin/make ---------- 生成 xdb 文件 -bin/edit_v4 ------- 测试 原始数据编辑(ipv4) -bin/edit_v6 ------- 测试 原始数据编辑(ipv6) +bin --------------- Executable directory (generated via make) +bin/header -------- Test header +bin/search -------- Test search +bin/bench --------- Benchmarking +bin/make ---------- Generate xdb file +bin/edit_v4 ------- Test raw data editing (ipv4) +bin/edit_v6 ------- Test raw data editing (ipv6) readme.md --------- readme + ``` -## 1. 编译 +## 1. Compilation + ``` $ make ``` -## 2. 查找 -### 2.1 示例 +## 2. Search + +### 2.1 Example + ```cpp #include "src/search.h" -// IP 版本: xdb::ipv4 xdb::ipv6 -// 策略: xdb::policy_file xdb::policy_vector xdb::policy_content -// 不缓存 部分缓存 全部缓存 +// IP Version: xdb::ipv4 xdb::ipv6 +// Policy: xdb::policy_file xdb::policy_vector xdb::policy_content +// No cache Partial cache Full cache int main() { std::string xdb_name = "../../data/ip2region_v6.xdb"; int version = xdb::ipv6; @@ -57,67 +64,74 @@ int main() { return 0; } -// $ g++ src/*.cc 1.cc --- 编译 -// $ ./a.out ------------- 测试 +// $ g++ src/*.cc 1.cc --- Compile +// $ ./a.out ------------- Test // Japan|Tokyo|Asagaya-minami|WIDE Project|JP ``` -### 2.2 测试 xdb 头部 +### 2.2 Test xdb Header + ``` $ ./bin/header -测试 IPv4 -版本号: 3 -缓存策略: 1 -文件生成时间: 2025-09-06 02:24:16 -索引起始地址: 955933 -索引结束地址: 11042415 -IP版本: 4 -指针字节数: 4 +Test IPv4 +Version: 3 +Cache Policy: 1 +File Generation Time: 2025-09-06 02:24:16 +Index Start Address: 955933 +Index End Address: 11042415 +IP Version: 4 +Pointer Bytes: 4 -测试 IPv6 -版本号: 3 -缓存策略: 1 -文件生成时间: 2025-10-17 04:41:04 -索引起始地址: 3094259 -索引结束地址: 36258303 -IP版本: 6 -指针字节数: 4 +Test IPv6 +Version: 3 +Cache Policy: 1 +File Generation Time: 2025-10-17 04:41:04 +Index Start Address: 3094259 +Index End Address: 36258303 +IP Version: 6 +Pointer Bytes: 4 ``` -### 2.3 测试查找 +### 2.3 Test Search + ``` $ ./bin/search -测试 IPv4 不缓存: 成功 -测试 IPv4 部分缓存: 成功 -测试 IPv4 全部缓存: 成功 -测试 IPv6 不缓存: 成功 -测试 IPv6 部分缓存: 成功 -测试 IPv6 全部缓存: 成功 +Test IPv4 No cache: Success +Test IPv4 Partial cache: Success +Test IPv4 Full cache: Success +Test IPv6 No cache: Success +Test IPv6 Partial cache: Success +Test IPv6 Full cache: Success ``` -## 3. 测速以及检验正确性 +## 3. Benchmarking and Correctness Verification + ``` ./bin/bench -测试 IPv4, 不缓存, total: 3910284, took: 27.60s, cost: 6.59μs/op, io count: 28227147 -测试 IPv4, 部分缓存, total: 3910284, took: 21.85s, cost: 5.15μs/op, io count: 24316863 -测试 IPv4, 全部缓存, total: 3910284, took: 2.26s, cost: 0.25μs/op, io count: 0 -测试 IPv6, 不缓存, total: 4792520, took: 100.40s, cost: 20.22μs/op, io count: 80758866 -测试 IPv6, 部分缓存, total: 4792520, took: 93.06s, cost: 18.71μs/op, io count: 75966346 -测试 IPv6, 全部缓存, total: 4792520, took: 6.24s, cost: 0.81μs/op, io count: 0 +Test IPv4, No cache, total: 3910284, took: 27.60s, cost: 6.59μs/op, io count: 28227147 +Test IPv4, Partial cache, total: 3910284, took: 21.85s, cost: 5.15μs/op, io count: 24316863 +Test IPv4, Full cache, total: 3910284, took: 2.26s, cost: 0.25μs/op, io count: 0 +Test IPv6, No cache, total: 4792520, took: 100.40s, cost: 20.22μs/op, io count: 80758866 +Test IPv6, Partial cache, total: 4792520, took: 93.06s, cost: 18.71μs/op, io count: 75966346 +Test IPv6, Full cache, total: 4792520, took: 6.24s, cost: 0.81μs/op, io count: 0 ``` -## 4. 生成 xdb 文件 -### 4.1 生成 xdb 文件 +## 4. Generate xdb File + +### 4.1 Generate xdb File + ``` $ ./bin/make -生成 ipv4 的 xdb 文件, took: 0.57s -生成 ipv6 的 xdb 文件, took: 1.24s +Generate ipv4 xdb file, took: 0.57s +Generate ipv6 xdb file, took: 1.24s ``` -## 5. 原始数据编辑 -### 5.1. 使用说明 -* 新的IP归属地文件可以包含空行 -* 新的IP归属地文件顺序可以乱序, 程序会自动排序 -* 新的IP归属地文件顺序可以重叠, 只要无二义性, 程序会自动合并 -* 最终的结果会将相邻的且归属地相同的行自动合并 -* 以下测试, 原文件使用仓库自带的数据文件, 新文件使用当前目录下的 1.txt +## 5. Raw Data Editing + +### 5.1. Instructions for Use + +* New IP attribution files can contain empty lines +* New IP attribution files can be out of order; the program will automatically sort them +* New IP attribution files can overlap; as long as there is no ambiguity, the program will automatically merge them +* The final result will automatically merge adjacent lines with the same attribution +* For the following tests, the original file uses the data file provided in the repository, and the new file uses 1.txt in the current directory diff --git a/binding/cpp/README_zh.md b/binding/cpp/README_zh.md new file mode 100644 index 0000000..6d146dd --- /dev/null +++ b/binding/cpp/README_zh.md @@ -0,0 +1,125 @@ +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) + +# ip2region C++ 查询客户端 + +## 0. 文件说明 +``` +Makefile --------- 构建 + +src ------------------ 源文件目录 +src/base.* ----------- 常量及工具函数 +src/ip.* ------------- 实现 IP 处理 +src/header.* --------- 实现 xdb 头部解析 +src/search.* --------- 实现 xdb 查找 +src/bench.* ---------- 实现 查找 测速 +src/make.* ----------- 实现 生成 xdb 文件 +src/edit.* ----------- 实现 原始数据编辑 + +test ---------------- 测试目录 +test/header.cc ------ 测试 头部 +test/search.cc ------ 测试 查找 +test/bench.cc ------- 测速 +test/make.cc -------- 生成 xdb 文件 +test/edit_v4.cc ----- 测试 原始数据编辑(ipv4) +test/edit_v6.cc ----- 测试 原始数据编辑(ipv6) + + +bin --------------- 可执行文件目录(通过 make 生成) +bin/header -------- 测试 头部 +bin/search -------- 测试 查找 +bin/bench --------- 测速 +bin/make ---------- 生成 xdb 文件 +bin/edit_v4 ------- 测试 原始数据编辑(ipv4) +bin/edit_v6 ------- 测试 原始数据编辑(ipv6) + +readme.md --------- readme +``` + +## 1. 编译 +``` +$ make +``` + +## 2. 查找 +### 2.1 示例 +```cpp +#include "src/search.h" + +// IP 版本: xdb::ipv4 xdb::ipv6 +// 策略: xdb::policy_file xdb::policy_vector xdb::policy_content +// 不缓存 部分缓存 全部缓存 +int main() { + std::string xdb_name = "../../data/ip2region_v6.xdb"; + int version = xdb::ipv6; + int policy = xdb::policy_content; + std::string ip = "2001:200:124::"; + + xdb::search_t s(xdb_name, version, policy); + std::cout << s.search(ip) << std::endl; + return 0; +} + +// $ g++ src/*.cc 1.cc --- 编译 +// $ ./a.out ------------- 测试 +// Japan|Tokyo|Asagaya-minami|WIDE Project|JP +``` + +### 2.2 测试 xdb 头部 +``` +$ ./bin/header +测试 IPv4 +版本号: 3 +缓存策略: 1 +文件生成时间: 2025-09-06 02:24:16 +索引起始地址: 955933 +索引结束地址: 11042415 +IP版本: 4 +指针字节数: 4 + +测试 IPv6 +版本号: 3 +缓存策略: 1 +文件生成时间: 2025-10-17 04:41:04 +索引起始地址: 3094259 +索引结束地址: 36258303 +IP版本: 6 +指针字节数: 4 +``` + +### 2.3 测试查找 +``` +$ ./bin/search +测试 IPv4 不缓存: 成功 +测试 IPv4 部分缓存: 成功 +测试 IPv4 全部缓存: 成功 +测试 IPv6 不缓存: 成功 +测试 IPv6 部分缓存: 成功 +测试 IPv6 全部缓存: 成功 +``` + +## 3. 测速以及检验正确性 +``` +./bin/bench +测试 IPv4, 不缓存, total: 3910284, took: 27.60s, cost: 6.59μs/op, io count: 28227147 +测试 IPv4, 部分缓存, total: 3910284, took: 21.85s, cost: 5.15μs/op, io count: 24316863 +测试 IPv4, 全部缓存, total: 3910284, took: 2.26s, cost: 0.25μs/op, io count: 0 +测试 IPv6, 不缓存, total: 4792520, took: 100.40s, cost: 20.22μs/op, io count: 80758866 +测试 IPv6, 部分缓存, total: 4792520, took: 93.06s, cost: 18.71μs/op, io count: 75966346 +测试 IPv6, 全部缓存, total: 4792520, took: 6.24s, cost: 0.81μs/op, io count: 0 +``` + +## 4. 生成 xdb 文件 +### 4.1 生成 xdb 文件 +``` +$ ./bin/make +生成 ipv4 的 xdb 文件, took: 0.57s +生成 ipv6 的 xdb 文件, took: 1.24s +``` + +## 5. 原始数据编辑 +### 5.1. 使用说明 +* 新的IP归属地文件可以包含空行 +* 新的IP归属地文件顺序可以乱序, 程序会自动排序 +* 新的IP归属地文件顺序可以重叠, 只要无二义性, 程序会自动合并 +* 最终的结果会将相邻的且归属地相同的行自动合并 +* 以下测试, 原文件使用仓库自带的数据文件, 新文件使用当前目录下的 1.txt