doc: update documents for Golang user

liuq19 · liuq19 · commit f2cd277e5df4 · 2023-11-07T15:27:19.000+08:00
diff --git a/README.md b/README.md
@@ -21,10 +21,47 @@ The main optimization in sonic-rs is the use of SIMD. However, we do not use the
 
 More details about optimization can be found in [performance.md](docs/performance.md).
 
+***For Golang user to use `sonic_rs`, please see [for_Golang_user_zh.md](docs/for_Golang_user.md)***
+
+- [sonic-rs](#sonic-rs)
+    - [Requirements/Notes](#requirementsnotes)
+    - [Quick to use sonic-rs](#quick-to-use-sonic-rs)
+- [Features](#features)
+- [Benchmark](#benchmark)
+    - [Deserialize Struct](#deserialize-struct)
+    - [Deserialize Untyped](#deserialize-untyped)
+    - [Serialize Untyped](#serialize-untyped)
+    - [Serialize Struct](#serialize-struct)
+    - [Get from JSON](#get-from-json)
+- [Usage](#usage)
+    - [Serde into Rust Type](#serde-into-rust-type)
+    - [Get a field from JSON](#get-a-field-from-json)
+    - [Parse and Serialize into untyped Value](#parse-and-serialize-into-untyped-value)
+    - [JSON Iterator](#json-iterator)
+    - [JSON RawValue & Number & RawNumber](#json-rawvalue--number--rawnumber)
+    - [Error handle](#error-handle)
+- [FAQs](#faqs)
+    - [About UTF-8](#about-utf-8)
+    - [About floating point precision](#about-floating-point-precision)
+- [Acknowledgement](#acknowledgement)
+- [Contributing](#contributing)
+
 ## Requirements/Notes
 
 1. Support x86_64 or aarch64. Note that the performance in aarch64 is lower and needs optimization.
 2. Requires Rust nightly version, as we use the `packed_simd` crate.
+3. please add the compile options `-C target-cpu=native`
+
+## Quick to use sonic-rs
+
+To ensure that SIMD instruction is used in sonic-rs, you need to add rustflags `-C target-cpu=native` and compile on the host machine. For example, Rust flags can be configured in Cargo [config](.cargo/config).
+
+Add sonic-rs in `Cargo.toml`
+
+```
+[dependencies]
+sonic-rs = 0.2
+```
 
 ## Features
 1. Serde into Rust struct as `serde_json` and `serde`.
@@ -39,15 +76,6 @@ More details about optimization can be found in [performance.md](docs/performanc
 
 6. The floating parsing percision is as Rust std in default.
 
-## Quick to use sonic-rs
-
-To ensure that SIMD instruction is used in sonic-rs, you need to add rustflags `-C target-cpu=native` and compile on the host machine. For example, Rust flags can be configured in Cargo [config](.cargo/config).
-
-Add sonic-rs in `Cargo.toml`
-```
-[dependencies]
-sonic-rs = 0.2
-```
 
 ## Benchmark
 
diff --git a/README_ZH.md b/README_ZH.md
@@ -21,19 +21,36 @@ sonic-rs 的主要优化是使用 SIMD。然而，sonic-rs 没有使用来自`si
 
 有关优化的更多细节，请参见 [performance_zh.md](docs/performance_zh.md)。
 
+***对于 Golang 用户迁移 Rust 使用 `sonic_rs`, 请参考 [for_Golang_user.md](docs/for_Golang_user_zh.md)***
+
+- [sonic-rs](#sonic-rs)
+    - [要求/注意事项](#要求注意事项)
+    - [如何使用 sonic-rs](#如何使用-sonic-rs)
+- [功能](#功能)
+- [基准测试](#基准测试)
+    - [解析到结构体](#解析到结构体)
+    - [解析到document](#解析到-document)
+    - [序列化document](#序列化-document)
+    - [序列化Rust结构体](#序列化-rust-结构体)
+    - [从JSON中获取](#从-json-中获取)
+- [用法](#用法)
+    - [对Rust类型解析/序列化](#对-rust-类型解析序列化)
+    - [从JSON中获取字段](#从-json-中获取字段)
+    - [解析/序列化document](#解析序列化-document)
+    - [JSON Iterator](#json-iterator)
+    - [JSON RawValue & Number & RawNumber](#json-rawvalue--number--rawnumber)
+    - [错误处理](#错误处理)
+- [常见问题](#常见问题)
+    - [关于UTF-8](#关于-utf-8)
+    - [关于浮点数精度](#关于浮点数精度)
+- [致谢](#致谢)
+- [如何贡献](#如何贡献)
+
 ## ***要求/注意事项***
 
 1. 支持 x86_64 或 aarch64，aarch64 的性能较低，需要优化。
 2. 需要 Rust nightly 版本，因为 sonic-rs 使用了 `packed_simd` 包。
-
-## 功能
-
-1. JSON 与 Rust 结构体之间的序列化，基于兼容 `serde_json` 和 `serde`。
-2. JSON 与 document 之间的序列化，document是可变数据结构
-3. 从 JSON 中获取特定字段
-4. 将 JSON 解析为惰性迭代器
-5. 在默认情况下支持 `RawValue`，`Number` 和 `RawNumber`（就像 Golang 的 `JsonNumber`）。
-6. 浮点数精度默认和 Rust 标准库对齐
+3. 在编译选项中开启 `-C target-cpu=native`
 
 ## 如何使用 sonic-rs
 
@@ -45,6 +62,15 @@ sonic-rs 的主要优化是使用 SIMD。然而，sonic-rs 没有使用来自`si
 sonic-rs = 0.2
 ```
 
+## 功能
+
+1. JSON 与 Rust 结构体之间的序列化，基于兼容 `serde_json` 和 `serde`。
+2. JSON 与 document 之间的序列化，document是可变数据结构
+3. 从 JSON 中获取特定字段
+4. 将 JSON 解析为惰性迭代器
+5. 在默认情况下支持 `RawValue`，`Number` 和 `RawNumber`（就像 Golang 的 `JsonNumber`）。
+6. 浮点数精度默认和 Rust 标准库对齐
+
 
 ## 基准测试
 
diff --git a/docs/for_Golang_user.md b/docs/for_Golang_user.md
@@ -0,0 +1,39 @@
+## Golang to Rust migration
+
+Current version:
+
+`sonic-rs = "0.2.4"`
+
+Corresponding API references:
+
+- Parsing into Golang structures or strong types:
+
+  sonic-go/encoding-json Unmarshal => sonic_rs::from_str/from_slice
+
+  sonic-go/encoding-json Marshal => sonic_rs::to_string/to_vec, etc.
+
+- Parsing into Golang interface{}/any or sonic-go AST:
+
+  If it is a standalone `interface{}`, it is recommended to use `sonic_rs::Document` for better performance.
+
+  If it is an `interface{}` inside a Golang structure, it is recommended to replace `interface{}/any` with `serde_json::Value`. Note: `sonic_rs::Value` and `sonic_rs::Document` are not currently supported for embedding into Rust structures but will be supported later.
+
+- Using gjson/jsonparser for on-demand parsing:
+
+  Regarding gjson/jsonparser get API:
+
+  The gjson/jsonparser get API itself does not perform strict JSON validation, so you can use `sonic_rs::get_unchecked` for replacement. The sonic_rs get API will return a `Result<LazyValue>`, `LazyValue` can be further ***parsed into the corresponding type** by using `as_bool, as_str`, etc. If you need to get the original raw JSON, ***without parsing***, please use `as_raw_str, as_raw_slice` API. Refer to the example: [get_from.rs](examples/get_from.rs)
+
+  Regarding jsonparser `ArrayEach` and `ObjectEach` API:
+
+  The gjson/jsonparser get API itself does not perform strict JSON validation, so you can use `sonic_rs::to_object_iter_unchecked` for replacement. Refer to the example [iterator.rs](examples/iterator.rs)
+
+  If you need to get multiple fields from JSON, it is recommended to use `get_many`. Reference example: [get_many.rs](examples/get_many.rs)
+
+- Parsing into Golang JsonNumber:
+
+  Please use `sonic_rs::RawNumber` directly.
+
+- Parsing into Golang RawMessage:
+
+  Please use `sonic_rs::RawValue` directly.
diff --git a/docs/for_Golang_user_zh.md b/docs/for_Golang_user_zh.md
@@ -0,0 +1,51 @@
+## Golang 迁移 Rust
+
+目前版本：
+
+` sonic-rs = "0.2.4" `
+
+
+对应 API 参考:
+
+- 解析到 Golang 结构体等强类型:
+
+sonic-go/encoding-json Unmarshal => sonic_rs::from_str/from_slice
+
+sonic-go/encoding-json Marshal => sonic_rs::to_string/to_vec 等
+
+- 解析到 Golang interface{}/any 或 sonic-go AST:
+
+如果是单独的 `interface{}`, 建议使用 `sonic_rs::Document`，性能更优。
+
+如果是 Golang 结构体中的 `interface{}`, 建议将 `interface{}/any` 替换为 `serde_json::Value` 即可。 注意: `sonic_rs::Value` 和 `sonic_rs::Document` 暂时不支持嵌入到 Rust 结构体中, 后续会进行支持。
+
+- 使用 gjson/jsonparser 按需解析:
+
+关于 gjson/jsonparser get API:
+
+gjson/jsonparser get API 本身未做严格的JSON 校验，因此可以使用 `sonic_rs::get_unchecked` 进行平替。sonic_rs get API 会返回一个 `Result<LazyValue>`, `LazyValue` 可以用 `as_bool, as_str`等将 JSON 进一步***解析成对应的类型**, 如果需要拿到原始的raw JSON, ***不做解析***，请使用 `as_raw_str, as_raw_slice` 等 API. 参考例子: [get_from.rs](examples/get_from.rs)
+
+
+关于 jsonparser `ArrayEach` 和 `ObjectEach` API:
+
+gjson/jsonparser get API 本身未做严格的JSON 校验，因此可以使用 `sonic_rs::to_object_iter_unchecked` 等进行平替。参考例子 [iterator.rs](examples/iterator.rs)
+
+
+如果需要从 JSON 中拿到多个字段，推荐使用 `get_many`. 参考例子： [get_many.rs](examples/get_many.rs)
+
+
+- 解析到 Golang JsonNumber:
+
+请直接使用 `sonic_rs::RawNumber`
+
+- 解析到 Golang RawMessage:
+
+请直接使用 `sonic_rs::RawValue`
+
+
+
+
+
+
+
+
diff --git a/examples/get_many.rs b/examples/get_many.rs
@@ -0,0 +1,22 @@
+use sonic_rs::pointer;
+use sonic_rs::PointerNode;
+
+fn main() {
+    let json = r#"
+        {"u": 123, "a": {"b" : {"c": [null, "found"]}}}"#;
+
+    // build a pointer tree, representing multile json path
+    let mut tree = sonic_rs::PointerTree::new();
+
+    tree.add_path(&["u"]);
+    tree.add_path(&pointer!["a", "b", "c", 1]);
+
+    let nodes = unsafe { sonic_rs::get_many_unchecked(json, &tree) };
+
+    // the node order is as the order of `add_path`
+    for val in nodes.unwrap() {
+        println!("{}", val.as_raw_str());
+        // 123
+        // "found"
+    }
+}
diff --git a/examples/iterator.rs b/examples/iterator.rs
@@ -1,5 +1,6 @@
 use bytes::Bytes;
-use sonic_rs::{to_array_iter, JsonValue};
+use faststr::FastStr;
+use sonic_rs::{to_array_iter, to_object_iter_unchecked, JsonValue};
 
 fn main() {
     let json = Bytes::from(r#"[1, 2, 3, 4, 5, 6]"#);
@@ -11,6 +12,8 @@ fn main() {
     let json = Bytes::from(r#"[1, 2, 3, 4, 5, 6"#);
     let iter = to_array_iter(&json);
     for elem in iter {
+        // do something for each elem
+
         // deal with errors when invalid json
         if elem.is_err() {
             assert_eq!(
@@ -19,4 +22,24 @@ fn main() {
             );
         }
     }
+
+    let json = FastStr::from(r#"{"a": null, "b":[1, 2, 3]}"#);
+    let iter = unsafe { to_object_iter_unchecked(&json) };
+    for ret in iter {
+        // deal with errors
+        if ret.is_err() {
+            println!("{}", ret.unwrap_err());
+            return;
+        }
+
+        let (k, v) = ret.unwrap();
+        if k == "a" {
+            assert!(v.is_null());
+        } else if k == "b" {
+            let iter = to_array_iter(v.as_raw_str());
+            for (i, v) in iter.enumerate() {
+                assert_eq!(i + 1, v.as_u64().unwrap() as usize);
+            }
+        }
+    }
 }
diff --git a/src/pointer/tree.rs b/src/pointer/tree.rs
@@ -22,7 +22,7 @@ impl PointerTree {
 
     /// we build tree and return value according by the order of path.
     /// Allow the repeated path.
-    pub fn add_path<Path: Iterator>(&mut self, path: Path)
+    pub fn add_path<Path: IntoIterator>(&mut self, path: Path)
     where
         Path::Item: PointerTrait,
     {

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ impl PointerTree {`
`22`	`22`
`23`	`23`	`/// we build tree and return value according by the order of path.`
`24`	`24`	`/// Allow the repeated path.`
`25`		`- pub fn add_path<Path: Iterator>(&mut self, path: Path)`
	`25`	`+ pub fn add_path<Path: IntoIterator>(&mut self, path: Path)`
`26`	`26`	`where`
`27`	`27`	`Path::Item: PointerTrait,`
`28`	`28`	`{`