add english readme for c++ binding
This commit is contained in:
lionsoul2014
parent
dce0bb582f
commit
1c6d299efa
|
|
@ -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:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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: |
|
||||||
|
|
||||||
|
|
||||||
以下工具链实现由社区开发者通过第三方仓库贡献：
|
以下工具链实现由社区开发者通过第三方仓库贡献：
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
Loading…
Reference in New Issue