xinb
/
ip2region_private
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #446 from lionsoul2014/i18n_cpp_readme 

add english readme for c++ binding
This commit is contained in:
Leon / 狮子的魂 2026-02-25 22:24:19 +08:00 committed by GitHub
parent dce0bb582f 1c6d299efa
commit 30e5f2732d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 216 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -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: | | [Csharp](binding/csharp) | csharp query client | :white_check_mark: | :white_check_mark: |
| [Erlang](binding/erlang/README.md) | erlang query client | :white_check_mark: | :x: | | [Erlang](binding/erlang/README.md) | erlang query client | :white_check_mark: | :x: |
| [Nginx](binding/nginx) | nginx extension 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: The following toolchain implementations are contributed by community developers via third-party repositories:

2
README_zh.md
View File

@ -48,7 +48,7 @@ API 介绍，使用文档和测试程序请参考对应 `searcher` 查询客户
| [Csharp](binding/csharp) | csharp 查询客户端 | :white_check_mark: | :white_check_mark: | | [Csharp](binding/csharp) | csharp 查询客户端 | :white_check_mark: | :white_check_mark: |
| [Erlang](binding/erlang/README_zh.md) | erlang 查询客户端 | :white_check_mark: | :x: | | [Erlang](binding/erlang/README_zh.md) | erlang 查询客户端 | :white_check_mark: | :x: |
| [Nginx](binding/nginx) | nginx 扩展查询客户端 | :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: |
以下工具链实现由社区开发者通过第三方仓库贡献： 以下工具链实现由社区开发者通过第三方仓库贡献：

164
binding/cpp/README.md
View File

@ -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 ------------------ Source directory
src/base.* ----------- 常量及工具函数 src/base.* ----------- Constants and utility functions
src/ip.* ------------- 实现 IP 处理 src/ip.* ------------- IP processing implementation
src/header.* --------- 实现 xdb 头部解析 src/header.* --------- xdb header parsing implementation
src/search.* --------- 实现 xdb 查找 src/search.* --------- xdb search implementation
src/bench.* ---------- 实现 查找 测速 src/bench.* ---------- Search benchmarking implementation
src/make.* ----------- 实现 生成 xdb 文件 src/make.* ----------- xdb file generation implementation
src/edit.* ----------- 实现 原始数据编辑 src/edit.* ----------- Raw data editing implementation
test ---------------- 测试目录 test ---------------- Test directory
test/header.cc ------ 测试 头部 test/header.cc ------ Test header
test/search.cc ------ 测试 查找 test/search.cc ------ Test search
test/bench.cc ------- 测速 test/bench.cc ------- Benchmarking
test/make.cc -------- 生成 xdb 文件 test/make.cc -------- Generate xdb file
test/edit_v4.cc ----- 测试 原始数据编辑(ipv4) test/edit_v4.cc ----- Test raw data editing (ipv4)
test/edit_v6.cc ----- 测试 原始数据编辑(ipv6) test/edit_v6.cc ----- Test raw data editing (ipv6)
bin --------------- 可执行文件目录(通过 make 生成) bin --------------- Executable directory (generated via make)
bin/header -------- 测试 头部 bin/header -------- Test header
bin/search -------- 测试 查找 bin/search -------- Test search
bin/bench --------- 测速 bin/bench --------- Benchmarking
bin/make ---------- 生成 xdb 文件 bin/make ---------- Generate xdb file
bin/edit_v4 ------- 测试 原始数据编辑(ipv4) bin/edit_v4 ------- Test raw data editing (ipv4)
bin/edit_v6 ------- 测试 原始数据编辑(ipv6) bin/edit_v6 ------- Test raw data editing (ipv6)
readme.md --------- readme readme.md --------- readme
``` ```
## 1. 编译 ## 1. Compilation
``` ```
$ make $ make
``` ```
## 2. 查找 ## 2. Search
### 2.1 示例
### 2.1 Example
```cpp ```cpp
#include "src/search.h" #include "src/search.h"
// IP 版本: xdb::ipv4 xdb::ipv6 // IP Version: xdb::ipv4 xdb::ipv6
// 策略: xdb::policy_file xdb::policy_vector xdb::policy_content // Policy: xdb::policy_file xdb::policy_vector xdb::policy_content
// 不缓存 部分缓存 全部缓存 // No cache Partial cache Full cache
int main() { int main() {
std::string xdb_name = "../../data/ip2region_v6.xdb"; std::string xdb_name = "../../data/ip2region_v6.xdb";
int version = xdb::ipv6; int version = xdb::ipv6;
@ -57,67 +64,74 @@ int main() {
return 0; return 0;
} }
// $ g++ src/*.cc 1.cc --- 编译 // $ g++ src/*.cc 1.cc --- Compile
// $ ./a.out ------------- 测试 // $ ./a.out ------------- Test
// Japan|Tokyo|Asagaya-minami|WIDE Project|JP // Japan|Tokyo|Asagaya-minami|WIDE Project|JP
``` ```
### 2.2 测试 xdb 头部 ### 2.2 Test xdb Header
``` ```
$ ./bin/header $ ./bin/header
测试 IPv4 Test IPv4
版本号: 3 Version: 3
缓存策略: 1 Cache Policy: 1
文件生成时间: 2025-09-06 02:24:16 File Generation Time: 2025-09-06 02:24:16
索引起始地址: 955933 Index Start Address: 955933
索引结束地址: 11042415 Index End Address: 11042415
IP版本: 4 IP Version: 4
指针字节数: 4 Pointer Bytes: 4
测试 IPv6 Test IPv6
版本号: 3 Version: 3
缓存策略: 1 Cache Policy: 1
文件生成时间: 2025-10-17 04:41:04 File Generation Time: 2025-10-17 04:41:04
索引起始地址: 3094259 Index Start Address: 3094259
索引结束地址: 36258303 Index End Address: 36258303
IP版本: 6 IP Version: 6
指针字节数: 4 Pointer Bytes: 4
``` ```
### 2.3 测试查找 ### 2.3 Test Search
``` ```
$ ./bin/search $ ./bin/search
测试 IPv4 不缓存: 成功 Test IPv4 No cache: Success
测试 IPv4 部分缓存: 成功 Test IPv4 Partial cache: Success
测试 IPv4 全部缓存: 成功 Test IPv4 Full cache: Success
测试 IPv6 不缓存: 成功 Test IPv6 No cache: Success
测试 IPv6 部分缓存: 成功 Test IPv6 Partial cache: Success
测试 IPv6 全部缓存: 成功 Test IPv6 Full cache: Success
``` ```
## 3. 测速以及检验正确性 ## 3. Benchmarking and Correctness Verification
``` ```
./bin/bench ./bin/bench
测试 IPv4, 不缓存, total: 3910284, took: 27.60s, cost: 6.59μs/op, io count: 28227147 Test IPv4, No cache, 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 Test IPv4, Partial cache, 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 Test IPv4, Full cache, 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 Test IPv6, No cache, 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 Test IPv6, Partial cache, 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 IPv6, Full cache, total: 4792520, took: 6.24s, cost: 0.81μs/op, io count: 0
``` ```
## 4. 生成 xdb 文件 ## 4. Generate xdb File
### 4.1 生成 xdb 文件
### 4.1 Generate xdb File
``` ```
$ ./bin/make $ ./bin/make
生成 ipv4 的 xdb 文件, took: 0.57s Generate ipv4 xdb file, took: 0.57s
生成 ipv6 的 xdb 文件, took: 1.24s Generate ipv6 xdb file, took: 1.24s
``` ```
## 5. 原始数据编辑 ## 5. Raw Data Editing
### 5.1. 使用说明
* 新的IP归属地文件可以包含空行 ### 5.1. Instructions for Use
* 新的IP归属地文件顺序可以乱序, 程序会自动排序
* 新的IP归属地文件顺序可以重叠, 只要无二义性, 程序会自动合并 * New IP attribution files can contain empty lines
* 最终的结果会将相邻的且归属地相同的行自动合并 * New IP attribution files can be out of order; the program will automatically sort them
* 以下测试, 原文件使用仓库自带的数据文件, 新文件使用当前目录下的 1.txt * 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

125
binding/cpp/README_zh.md Normal file
View File

@ -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