Skip to content

README.md

Latest commit

 

History

History
149 lines (116 loc) · 4.36 KB

README.md

File metadata and controls

149 lines (116 loc) · 4.36 KB
Raw

🌐 中文简体 | English

ip2region C++ query client

0. File Description

Makefile --------- Build

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 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 --------------- 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. Build and Test

The C++ binding uses CMake 3.16 or later and supports GCC, Clang, Apple Clang, and Microsoft Visual C++.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failure

On Linux and macOS, make and make test are equivalent convenience entry points. On Windows, run the commands above from a Visual Studio Developer PowerShell. CMake links the required Windows Sockets library automatically.

The test suite validates IPv4 and IPv6 address conversion, xdb headers, every search cache policy, and queries against freshly generated xdb files.

2. Search

2.1 Example

#include "src/search.h"

// 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;
    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 --- Compile
// $ ./a.out ------------- Test
// Japan|Tokyo|Asagaya-minami|WIDE Project|JP

2.2 Test xdb Header

$ ./bin/header
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

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 Test Search

$ ./bin/search
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. Benchmarking and Correctness Verification

./bin/bench
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. Generate xdb File

4.1 Generate xdb File

$ ./bin/make
Generate ipv4 xdb file, took: 0.57s
Generate ipv6 xdb file, took: 1.24s

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