Merge pull request #442 from lionsoul2014/i18n_rust_readme

add english readme for rust binding

README.md

@@ -43,7 +43,7 @@ For API introductions, usage documentation, and test programs, please refer to t
 | [C](binding/c/README.md)           | POSIX C xdb query client         | :white_check_mark: | :white_check_mark: |
 | [Lua_c](binding/lua_c/README.md)   | lua c extension xdb query client | :white_check_mark: | :white_check_mark: |
 | [Lua](binding/lua/README.md)       | lua xdb query client             | :white_check_mark: | :white_check_mark: |
-| [Rust](binding/rust)               | rust xdb query client            | :white_check_mark: | :white_check_mark: |
+| [Rust](binding/rust/README.md)     | rust xdb query client            | :white_check_mark: | :white_check_mark: |
 | [Python](binding/python)           | python xdb query client          | :white_check_mark: | :white_check_mark: |
 | [Javascript](binding/javascript)   | javascript xdb query client      | :white_check_mark: | :white_check_mark: |
 | [Csharp](binding/csharp)           | csharp xdb query client          | :white_check_mark: | :white_check_mark: |

README_zh.md

@@ -42,7 +42,7 @@ API 介绍，使用文档和测试程序请参考对应 `searcher` 查询客户
 | [C](binding/c/README_zh.md)           | POSIX C xdb 查询客户端      | :white_check_mark: | :white_check_mark: |
 | [Lua_c](binding/lua_c/README_zh.md)   | lua c 扩展 xdb 查询客户端   | :white_check_mark: | :white_check_mark: |
 | [Lua](binding/lua/README_zh.md)       | lua xdb 查询客户端          | :white_check_mark: | :white_check_mark: |
-| [Rust](binding/rust)                  | rust xdb 查询客户端         | :white_check_mark: | :white_check_mark: |
+| [Rust](binding/rust/README_zh.md)     | rust xdb 查询客户端         | :white_check_mark: | :white_check_mark: |
 | [Python](binding/python)              | python xdb 查询客户端       | :white_check_mark: | :white_check_mark: |
 | [Javascript](binding/javascript)      | javascript xdb 查询客户端   | :white_check_mark: | :white_check_mark: |
 | [Csharp](binding/csharp)              | csharp xdb 查询客户端       | :white_check_mark: | :white_check_mark: |

binding/rust/README.md

@@ -1,36 +1,41 @@
-## `ip2region xdb rust` 查询客户端实现
+:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md)
+
+## `ip2region rust` Query Client
 
 ## Features
-- 支持`ip`字符串和`u32`/`u28` 数字两种类型的查询
-- 支持 IPv4 和 IPv6
-- 支持无缓存，Vector 索引缓存，全部数据缓存三种模式
 
-## 缓存策略对比与说明
+* Supports queries using both `ip` strings and `u32`/`u28` numeric types
-| 缓存模式     | IPv4 数据内存占用 | IPv6 数据内存占用 | IPv4 benchmark 查询耗时 | IPv6 benchmark 查询耗时 |
+* Supports IPv4 and IPv6
-| ------------ | ----------- | ----------- | ------------------- |---------------------|
+* Supports three modes: No Cache, Vector Index Cache, and Full Data Cache
-| 无缓存       | 1-2MB       | 1-2MB       | 54 us               | 122us               |
-| vector index | 1-2MB       | 1-2MB       | 27 us               | 100us               |
-| 全部缓存     | 20 MB       | 200 MB      | 120 ns              | 178 ns              |
 
-- 在 `ip2region::Searcher` 初始化的时候会产生一次 IO, 读取 `xdb` 的 header 信息以初始化 `Searcher`，header 信息主要包含了 `xdb` 的 IP 版本，该操作对后续 IP 的查询不产生性能，耗时影响，多占用约 20 Byte 的内存
+## Cache Policy Comparison and Description
-- 在无缓存模式与 `vector index` 缓存模式下，所有 `xdb` 的 IO 读取都是按需（按照 bytes offset, bytes length）读取少量信息, 都是线程安全的，可以 benchmark 测试验证
-- 在全部缓存模式下，`xdb` 文件会一次读取，加载到内存中，测试 `IPv6 xdb` 文件大约占用内存 200MB 左右，查询不频繁的话，占用内存会逐渐降低
-- 所有缓存模式下，包括初始化 `ip2region::Searcher` 过程当中，程序都是线程安全的，不存在某个全局可修改的中间变量，`ip2region::Searcher` 初始化完成以后，调用函数`search`都是使用不可变引用，同时 `ip2region::Searcher` 也可以通过 `Arc` 方式传递给不同线程使用
 
-## 使用方式
+| Cache Mode | IPv4 Memory Usage | IPv6 Memory Usage | IPv4 benchmark query time | IPv6 benchmark query time |
+| --- | --- | --- | --- | --- |
+| No Cache | 1-2MB | 1-2MB | 54 us | 122us |
+| vector index | 1-2MB | 1-2MB | 27 us | 100us |
+| Full Cache | 20 MB | 200 MB | 120 ns | 178 ns |
 
-使用`cargo`新建一个项目，比如`cargo new ip-test`
+* During the initialization of `ip2region::Searcher`, an IO operation occurs to read the `xdb` header information to initialize the `Searcher`. The header information mainly includes the IP version of the `xdb`. This operation does not affect the performance or time consumption of subsequent IP queries and occupies approximately 20 additional bytes of memory.
+* In No Cache mode and `vector index` cache mode, all `xdb` IO reads are performed on-demand (based on bytes offset and bytes length) for small amounts of information. Both are thread-safe, as verified by benchmark testing.
+* In Full Cache mode, the `xdb` file is read and loaded into memory at once. Testing shows the `IPv6 xdb` file occupies about 200MB of memory. If queries are infrequent, memory usage will gradually decrease.
+* In all cache modes, including during the initialization of `ip2region::Searcher`, the program is thread-safe. There are no globally modifiable intermediate variables. After `ip2region::Searcher` initialization is complete, calling the `search` function uses immutable references. Meanwhile, `ip2region::Searcher` can also be passed to different threads using `Arc`.
 
-配置`Cargo.toml`的`[dependencies]`如下
+## Usage
+
+Create a new project using `cargo`, such as `cargo new ip-test`
+
+Configure `[dependencies]` in `Cargo.toml` as follows:
 
 ```toml
 [dependencies]
 ip2region = { git = "https://github.com/lionsoul2014/ip2region.git", branch = "master" }
+
 ```
 
-### 基本使用示例
+### Basic Usage Example
 
-编写`main.rs`
+Write `main.rs`
 
 ```rust
 use ip2region::{CachePolicy, Searcher};
@@ -41,6 +46,7 @@ fn main() {
         CachePolicy::FullMemory,
         CachePolicy::VectorIndex,
     ] {
+        // Create an IPv4 searcher
         let ipv4_seacher = Searcher::new("../ip2region/data/ip2region_v4.xdb".to_owned(), cache_policy).unwrap();
         for ip in [1_u32, 2, 3] {
             let result = ipv4_seacher.search(ip).unwrap();
@@ -52,6 +58,7 @@ fn main() {
             println!("CachePolicy: {cache_policy:?}, IP: {ip}, Result: {result}");
         }
 
+        // Create an IPv6 searcher
         let ipv6_seacher = Searcher::new("../ip2region/data/ip2region_v6.xdb".to_owned(), cache_policy).unwrap();
         for ip in ["2001::", "2001:4:112::"] {
             let result = ipv6_seacher.search(ip).unwrap();
@@ -69,7 +76,6 @@ fn main() {
 ## Cache policy benchmark
 
 ```bash
-$ git lfs pull
 $ cd binding/rust/ip2region
 $ cargo test
 $ cargo bench
@@ -112,19 +118,20 @@ Found 6 outliers among 100 measurements (6.00%)
 // --snip--
 ```
 
-## 测试与结果验证，benchmark
+## Testing, Result Verification, and Benchmark
+
 ```bash
-$ git lfs pull
 $ cd binding/rust/example
 $ cargo build -r
 ```
-构建的执行程序位置 `binding/rust/target/release/searcher`
 
-测试 IPv6 以及 IPv4 需要结合 ipv6_source.txt 以及 ipv4_source.txt 的内容进行查询结果校验
+The location of the built executable is `binding/rust/target/release/searcher`
 
-**此处展示的查询结果只表示当前时间数据的查询，后续查询结果可能会由于 ip_source.txt 以及 xdb 二进制数据的 IP region 段更新修正导致不同**
+Testing IPv6 and IPv4 requires verifying query results against the contents of `ipv6_source.txt` and `ipv4_source.txt`.
 
-#### 测试 IPv6
+**The query results shown here represent data at the current time; subsequent results may differ due to updates and corrections in the IP region segments of `ip_source.txt` and `xdb` binary data.**
+
+#### Test IPv6
 
 ```bash
 $ cd binding/rust
@@ -145,7 +152,8 @@ ip2region>> 2c99::
 region: Ok("0|0|Reserved|Reserved|Reserved"), took: 5.33µs
 ```
 
-#### 测试 IPv4
+#### Test IPv4
+
 ```bash
 $ cd binding/rust
 $ cargo build -r
@@ -159,25 +167,24 @@ ip2region>> 2.2.21.1
 region: Ok("United States|Texas|0|Oracle Svenska AB|US"), took: 4.556µs
 ```
 
-#### Benchmark 与验证结果
+#### Benchmark and Result Verification
 
-通过 searcher 程序来测试性能，同时依据 ip sources 文件对比查询结果，检测是否存在错误
+Test performance via the `searcher` program while comparing query results against `ip sources` files to check for errors.
 
 ```bash
 $ cd binding/rust/example
 $ cargo build -r
-## 通过 data/ip2region_v4.xdb 和 data/ipv4_source.txt 进行 ipv4 的 bench 测试：
+## Perform IPv4 bench test using data/ip2region_v4.xdb and data/ipv4_source.txt:
 $ RUST_LOG=debug ../target/release/searcher --xdb='../../../data/ip2region_v4.xdb' bench '../../../data/ipv4_source.txt'
 2025-09-24T07:02:07.840535Z DEBUG ip2region::searcher: Load xdb file with header header=Header { version: 3, index_policy: VectorIndex, create_time: 1757125456, start_index_ptr: 955933, end_index_ptr: 11042415, ip_version: V4, runtime_ptr_bytes: 4 }
 2025-09-24T07:02:07.840894Z DEBUG ip2region::searcher: Load vector index cache
 2025-09-24T07:02:07.840905Z DEBUG ip2region::searcher: Load full cache filepath="../../../data/ip2region_v4.xdb"
 2025-09-24T07:02:08.409990Z  INFO searcher: Benchmark finished count=3404406 took=569.388667ms avg_took=167ns
 
-## 通过 data/ip2region_v6.xdb 和 data/ipv6_source.txt 进行 ipv6 的 bench 测试：
+## Perform IPv6 bench test using data/ip2region_v6.xdb and data/ipv6_source.txt:
 $ RUST_LOG=debug ../target/release/searcher --xdb='../../../data/ip2region_v6.xdb' bench '../../../data/ipv6_source.txt'
 2025-09-24T07:01:48.991835Z DEBUG ip2region::searcher: Load xdb file with header header=Header { version: 3, index_policy: VectorIndex, create_time: 1756970508, start_index_ptr: 6585371, end_index_ptr: 647078145, ip_version: V6, runtime_ptr_bytes: 4 }
 2025-09-24T07:01:48.992557Z DEBUG ip2region::searcher: Load vector index cache
 2025-09-24T07:01:48.992563Z DEBUG ip2region::searcher: Load full cache filepath="../../../data/ip2region_v6.xdb"
 2025-09-24T07:01:59.775879Z  INFO searcher: Benchmark finished count=38335905 took=10.784124584s avg_took=281ns
-
 ```

binding/rust/README_zh.md

@@ -0,0 +1,182 @@
+:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md)
+
+## `ip2region rust` 查询客户端
+
+## Features
+- 支持`ip`字符串和`u32`/`u28` 数字两种类型的查询
+- 支持 IPv4 和 IPv6
+- 支持无缓存，Vector 索引缓存，全部数据缓存三种模式
+
+## 缓存策略对比与说明
+| 缓存模式     | IPv4 数据内存占用 | IPv6 数据内存占用 | IPv4 benchmark 查询耗时 | IPv6 benchmark 查询耗时 |
+| ------------ | ----------- | ----------- | ------------------- |---------------------|
+| 无缓存       | 1-2MB       | 1-2MB       | 54 us               | 122us               |
+| vector index | 1-2MB       | 1-2MB       | 27 us               | 100us               |
+| 全部缓存     | 20 MB       | 200 MB      | 120 ns              | 178 ns              |
+
+- 在 `ip2region::Searcher` 初始化的时候会产生一次 IO, 读取 `xdb` 的 header 信息以初始化 `Searcher`，header 信息主要包含了 `xdb` 的 IP 版本，该操作对后续 IP 的查询不产生性能，耗时影响，多占用约 20 Byte 的内存
+- 在无缓存模式与 `vector index` 缓存模式下，所有 `xdb` 的 IO 读取都是按需（按照 bytes offset, bytes length）读取少量信息, 都是线程安全的，可以 benchmark 测试验证
+- 在全部缓存模式下，`xdb` 文件会一次读取，加载到内存中，测试 `IPv6 xdb` 文件大约占用内存 200MB 左右，查询不频繁的话，占用内存会逐渐降低
+- 所有缓存模式下，包括初始化 `ip2region::Searcher` 过程当中，程序都是线程安全的，不存在某个全局可修改的中间变量，`ip2region::Searcher` 初始化完成以后，调用函数`search`都是使用不可变引用，同时 `ip2region::Searcher` 也可以通过 `Arc` 方式传递给不同线程使用
+
+## 使用方式
+
+使用`cargo`新建一个项目，比如`cargo new ip-test`
+
+配置`Cargo.toml`的`[dependencies]`如下
+
+```toml
+[dependencies]
+ip2region = { git = "https://github.com/lionsoul2014/ip2region.git", branch = "master" }
+```
+
+### 基本使用示例
+
+编写`main.rs`
+
+```rust
+use ip2region::{CachePolicy, Searcher};
+
+fn main() {
+    for cache_policy in [
+        CachePolicy::NoCache,
+        CachePolicy::FullMemory,
+        CachePolicy::VectorIndex,
+    ] {
+        let ipv4_seacher = Searcher::new("../ip2region/data/ip2region_v4.xdb".to_owned(), cache_policy).unwrap();
+        for ip in [1_u32, 2, 3] {
+            let result = ipv4_seacher.search(ip).unwrap();
+            println!("CachePolicy: {cache_policy:?}, IP: {ip}, Result: {result}");
+        }
+
+        for ip in ["1.1.1.1", "2.2.2.2"] {
+            let result = ipv4_seacher.search(ip).unwrap();
+            println!("CachePolicy: {cache_policy:?}, IP: {ip}, Result: {result}");
+        }
+
+        let ipv6_seacher = Searcher::new("../ip2region/data/ip2region_v6.xdb".to_owned(), cache_policy).unwrap();
+        for ip in ["2001::", "2001:4:112::"] {
+            let result = ipv6_seacher.search(ip).unwrap();
+            println!("CachePolicy: {cache_policy:?}, IP: {ip}, Result: {result}");
+        }
+
+        for ip in [1_u128, 2, 3<<125] {
+            let result = ipv6_seacher.search(ip).unwrap();
+            println!("CachePolicy: {cache_policy:?}, IP: {ip}, Result: {result}");
+        }
+    }
+}
+```
+
+## Cache policy benchmark
+
+```bash
+$ cd binding/rust/ip2region
+$ cargo test
+$ cargo bench
+
+// --snip---
+ipv4_no_memory_bench    time:   [54.699 µs 57.401 µs 61.062 µs]
+Found 16 outliers among 100 measurements (16.00%)
+  10 (10.00%) high mild
+  6 (6.00%) high severe
+
+ipv4_vector_index_cache_bench
+                        time:   [25.972 µs 26.151 µs 26.360 µs]
+Found 9 outliers among 100 measurements (9.00%)
+  1 (1.00%) low severe
+  6 (6.00%) high mild
+  2 (2.00%) high severe
+
+ipv4_full_memory_cache_bench
+                        time:   [132.04 ns 139.48 ns 149.20 ns]
+Found 10 outliers among 100 measurements (10.00%)
+  4 (4.00%) high mild
+  6 (6.00%) high severe
+
+ipv6_no_memory_bench    time:   [121.00 µs 122.14 µs 123.40 µs]
+Found 5 outliers among 100 measurements (5.00%)
+  2 (2.00%) high mild
+  3 (3.00%) high severe
+
+ipv6_vector_index_cache_bench
+                        time:   [96.830 µs 100.23 µs 104.81 µs]
+Found 8 outliers among 100 measurements (8.00%)
+  2 (2.00%) high mild
+  6 (6.00%) high severe
+
+ipv6_full_memory_cache_bench
+                        time:   [175.29 ns 178.82 ns 183.77 ns]
+Found 6 outliers among 100 measurements (6.00%)
+  2 (2.00%) high mild
+  4 (4.00%) high severe
+// --snip--
+```
+
+## 测试与结果验证，benchmark
+```bash
+$ cd binding/rust/example
+$ cargo build -r
+```
+构建的执行程序位置 `binding/rust/target/release/searcher`
+
+测试 IPv6 以及 IPv4 需要结合 ipv6_source.txt 以及 ipv4_source.txt 的内容进行查询结果校验
+
+**此处展示的查询结果只表示当前时间数据的查询，后续查询结果可能会由于 ip_source.txt 以及 xdb 二进制数据的 IP region 段更新修正导致不同**
+
+#### 测试 IPv6
+
+```bash
+$ cd binding/rust
+$ cargo build -r
+$ ./target/release/searcher --xdb='../../data/ip2region_v6.xdb' query
+ip2region xdb searcher test program, type `quit` or `Ctrl + c` to exit
+ip2region>> ::
+region: Ok(""), took: 79.651412ms
+ip2region>> 240e:3b7:3273:51d0:cd38:8ae1:e3c0:b708
+region: Ok("中国|广东省|深圳市|电信|CN"), took: 7.575µs
+ip2region>> 2001::
+region: Ok("0|0|Reserved|Reserved|Reserved"), took: 7.256µs
+ip2region>> 2001:268:9a02:8888::
+region: Ok("Japan|Aichi|Nagoya|KDDI CORPORATION|JP"), took: 7.921µs
+ip2region>> 2a02:26f7:b408:a6c2::
+region: Ok("United States|Virginia|Emporia|Akamai Technologies, Inc.|US"), took: 8.461µs
+ip2region>> 2c99::
+region: Ok("0|0|Reserved|Reserved|Reserved"), took: 5.33µs
+```
+
+#### 测试 IPv4
+```bash
+$ cd binding/rust
+$ cargo build -r
+$  ./target/release/searcher --xdb='../../data/ip2region_v4.xdb' query
+ip2region xdb searcher test program, type `quit` or `Ctrl + c` to exit
+ip2region>> 1.2.3.4
+region: Ok("Australia|Queensland|Brisbane|0|AU"), took: 6.07µs
+ip2region>> 1.1.2.1
+region: Ok("中国|福建省|福州市|0|CN"), took: 5.653µs
+ip2region>> 2.2.21.1
+region: Ok("United States|Texas|0|Oracle Svenska AB|US"), took: 4.556µs
+```
+
+#### Benchmark 与验证结果
+
+通过 searcher 程序来测试性能，同时依据 ip sources 文件对比查询结果，检测是否存在错误
+
+```bash
+$ cd binding/rust/example
+$ cargo build -r
+## 通过 data/ip2region_v4.xdb 和 data/ipv4_source.txt 进行 ipv4 的 bench 测试：
+$ RUST_LOG=debug ../target/release/searcher --xdb='../../../data/ip2region_v4.xdb' bench '../../../data/ipv4_source.txt'
+2025-09-24T07:02:07.840535Z DEBUG ip2region::searcher: Load xdb file with header header=Header { version: 3, index_policy: VectorIndex, create_time: 1757125456, start_index_ptr: 955933, end_index_ptr: 11042415, ip_version: V4, runtime_ptr_bytes: 4 }
+2025-09-24T07:02:07.840894Z DEBUG ip2region::searcher: Load vector index cache
+2025-09-24T07:02:07.840905Z DEBUG ip2region::searcher: Load full cache filepath="../../../data/ip2region_v4.xdb"
+2025-09-24T07:02:08.409990Z  INFO searcher: Benchmark finished count=3404406 took=569.388667ms avg_took=167ns
+
+## 通过 data/ip2region_v6.xdb 和 data/ipv6_source.txt 进行 ipv6 的 bench 测试：
+$ RUST_LOG=debug ../target/release/searcher --xdb='../../../data/ip2region_v6.xdb' bench '../../../data/ipv6_source.txt'
+2025-09-24T07:01:48.991835Z DEBUG ip2region::searcher: Load xdb file with header header=Header { version: 3, index_policy: VectorIndex, create_time: 1756970508, start_index_ptr: 6585371, end_index_ptr: 647078145, ip_version: V6, runtime_ptr_bytes: 4 }
+2025-09-24T07:01:48.992557Z DEBUG ip2region::searcher: Load vector index cache
+2025-09-24T07:01:48.992563Z DEBUG ip2region::searcher: Load full cache filepath="../../../data/ip2region_v6.xdb"
+2025-09-24T07:01:59.775879Z  INFO searcher: Benchmark finished count=38335905 took=10.784124584s avg_took=281ns
+```