README.md
1# ylong_json
2
3## Introduction
4`ylong_json` is a general `JSON` syntax parsing library that provides functions for converting `JSON` text to and from specific data structures.
5
6### ylong_json in OpenHarmony
7
8The following is a description of the key fields in the above figure:
9- `Application Layer`: The application layer provides specific functions to users.
10- `App`: Various applications need to use the functions of the system service layer.
11- `System Service Layer`: System service layer, which provides system services to upper-layer applications.
12- `system services`: Various system services require the use of `JSON` related functions.
13- `ylong_json`: System component, providing common `JSON` serialization and deserialization capabilities to related components of the system service layer.
14- `serde`: third-party library for efficient and versatile serialization and deserialization of `Rust` data structures.
15
16### ylong_json Internal architecture diagram
17
18`ylong_json` is mainly divided into three submodules: `JsonValue` submodule, `serde` submodule, and C-ffi submodule.
19
20The `JsonValue` submodule provides a basic data structure `JsonValue`.
21`JsonValue` supports serializing itself into `JSON` text in either indented or compact format. Any syntactically correct `JSON` text can also be deserialized into a corresponding `JsonValue` data structure.
22`JsonValue` supports addition, deletion, modification and query, and you can use the specified interface to change the data content in `JsonValue`.
23`JsonValue` supports all data types in `JSON` syntax: `null`, `boolean`, `number`, `string`, `array`, `object`, and implements all its functions according to `ECMA-404`.
24For `array` and `object` grammatical structures, `JsonValue` provides a variety of underlying data structures for different usage scenarios, for example, for `array` structures, it supports the underlying use of `Vec` or `LinkedList`, for `object` , supports the use of `Vec`, `LinkedList` or `Btree` as its underlying layer.
25On different underlying data structures, `array` and `object` will reflect different creation and query performance, for example, `object` based on `Btree` data structure has higher performance in query, `LinkedList` or `LinkedList` or `Vec` has high performance in terms of creation.
26
27The `serde` submodule provides procedural macro functions based on the `Serialize` and `Deserialize` traits provided by the `serde` third-party library, which can support fast conversion of user structures and `JSON` text.
28The advantage of `serde` compared to `JsonValue` is that it is easy to use. Users do not need to convert the `JSON` text to `JsonValue` and then extract the specified data from it to generate the `Rust` structure. They only need to set `Serialize' to the structure. ` and `Deserialize` process macro tags can be used to serialize the interface structure provided in `ylong_json` into `JSON` text, or convert the corresponding `JSON` text into a user structure.
29
30The C-ffi module provides a C interface layer based on the `JsonValue` module, which facilitates users to use the C interface to call the functions of the `ylong_json` library.
31## Directory
32```
33ylong_json
34├─ benches # Benche test files
35├─ docs # Description documents
36├─ examples # ylong_json code example
37├─ figures # ylong_json structure charts
38├─ src
39│ ├─ value # Array and Object type definitions and related methods
40│ ├─ adapter.rs # Adapts to the C interface implementation
41│ ├─ consts.rs # Some definitions of constants and tables
42│ ├─ deserializer.rs # Deserialization implementation of the adaptation serde
43│ ├─ encoder.rs # Serialization implementation for the `JsonValue` type
44│ ├─ error.rs # Error type definition, helpful to identify the problem
45│ ├─ link_list.rs # LinkedList type definition and related methods
46│ ├─ serializer_compact.rs # Serialization implementation of the adaptation serde
47│ ├─ states.rs # Deserialization implementation for the `JsonValue` type
48│ └─ value.rs # JsonValue type definition and related methods
49└─ tests # Test directory
50```
51
52## Build
53### Use Cargo
541. Add `ylong_json` to the dependency of `Cargo.toml`
55```toml
56[dependencies]
57ylong_json = { git = "https://gitee.com/openharmony-sig/commonlibrary_rust_ylong_json.git" }
58```
59
60### Use gn
611. Add `ylong_json` in `bundle.json`
62```gn
63“deps”： {
64 “components”: ["ylong_json"]
65}
66```
67
682. Add `ylong_json:lib` in `BUILD.gn`
69```gn
70external_deps = ["ylong_json:lib"]
71```
72
73## User Guide
74See [user_guide](./docs/user_guide.md)
75
76## Performance test
77The following tests are from [`nativejson-benchmark`](https://www.github.com/miloyip/nativejson-benchmark)。
78
79The test environment information is as follows:
80```
81OS: Ubuntu 7.3.-16ubuntu3
82Processor: Intel(R) Xeon(R) Gold 6278C CPU @ 2.60GHz
83CPU(s): 8
84Memory：8.0 G
85```
86
87Software versions tested:
88
89cJSON 1.7.16
90
91Test Results:
92```
93======= ylong-json ==== parse | stringify ====
94canada.json 200 MB/s 90 MB/s
95citm_catalog.json 450 MB/s 300 MB/s
96twitter.json 340 MB/s 520 MB/s
97
98======== cJSON ======== parse | stringify ====
99canada.json 55 MB/s 11 MB/s
100citm_catalog.json 260 MB/s 170 MB/s
101twitter.json 210 MB/s 210 MB/s
102```
103
104Description of test results:
105
106Three test files are provided in the `nativejson-benchmark` test. Among them, `canada.json` contains a large number of `number` structures, the various data types of `citm_catalog.json` are relatively average, and `twitter.json` exists Various `UTF-8` characters.
107To ensure test fairness, `ylong_json` enables `list_object`, `list_array` and `ascii_only` feature.
108The `list_object` and `list_array` features are mainly to ensure consistency with the `cJSON` data structure, and both are implemented using linked lists.
109`ascii_only` feature is to ensure consistent processing logic for `UTF-8` characters, `cJSON` does not handle UTF-8 characters.
110
111The testing process is as follows:
112- Read the content of the file into the memory, and get the content of the file `content`.
113- Call the specified `JSON` library deserialization interface to generate the corresponding `JSON` structure `data`.
114- Call the serialization interface of the `JSON` structure to generate the output content `result`.
115- Using `content`, loop deserialization generates `JSON` structure 100 times, taking the smallest processing time `t1`.
116- Using `data`, serialize and generate `JSON` text 100 times, taking the smallest processing time `t2`.
117- Calculate the parsing speed, the deserialization time is the length of `content` divided by `t1`, and the serialization time is the length of the `JSON` text divided by `t2`.
README_zh.md
1# ylong_json
2
3## 简介
4`ylong_json` 是一个通用的 `JSON` 语法解析库，提供了 `JSON` 文本和特定数据结构之间的相互转换功能。
5
6### ylong_json 在 OpenHarmony 中的位置
7
8以下是对于上图关键字段的描述信息：
9- `Application Layer`：应用层，给用户提供具体功能。
10- `App`：各种应用，需要使用系统服务层的功能。
11- `System Service Layer`：系统服务层，给上层应用提供系统服务。
12- `system services`：各种系统服务，需要使用 `JSON` 相关的功能。
13- `ylong_json`：系统组件，给系统服务层的相关组件提供通用的 `JSON` 序列化与反序列化能力。
14- `serde`：第三方库，用于高效、通用地序列化和反序列化 `Rust` 数据结构。
15
16### ylong_json 内部架构图
17
18`ylong_json` 主要分为三个子模块：`JsonValue` 子模块、`serde` 子模块、C-ffi 子模块。
19
20`JsonValue` 子模块提供了一种基础数据结构 `JsonValue`。
21`JsonValue` 支持以缩进型格式或紧凑型格式将自身序列化成 `JSON` 文本。任意语法正确的 `JSON` 文本也能被反序列化成一个对应的 `JsonValue` 数据结构。
22`JsonValue` 支持增删改查，可以使用指定接口变更 `JsonValue` 中的数据内容。
23`JsonValue` 支持 `JSON` 语法中全部的数据类型：`null`, `boolean`, `number`, `string`, `array`, `object`，且按照 `ECMA-404` 实现其全部功能。
24针对于 `array` 和 `object` 语法结构，`JsonValue` 提供了多种底层数据结构以针对不同使用场景，例如对于 `array` 结构，支持底层使用 `Vec` 或 `LinkedList`，对于 `object`，支持其底层使用 `Vec`, `LinkedList` 或 `Btree`。
25在不同的底层数据结构之上，`array` 和 `object` 会体现出不同的创建和查询性能，例如基于 `Btree` 数据结构的 `object` 在查询方面具有较高性能表现，`LinkedList` 或 `Vec` 在创建方面具有较高性能表现。
26
27`serde` 子模块提供了基于 `serde` 第三方库提供的 `Serialize` 和 `Deserialize` trait 的过程宏功能，可以支持用户结构体和 `JSON` 文本的快速转换。
28`serde` 相较于 `JsonValue` 的优势是使用便捷，用户无需将 `JSON` 文本先转换为 `JsonValue` 再从其中取出指定数据生成 `Rust` 结构体，只需给结构体设定 `Serialize` 和 `Deserialize` 过程宏标签，即可使用 `ylong_json` 中提供的接口结构体序列化成 `JSON` 文本，或将对应的 `JSON` 文本转换为用户结构体。
29
30C-ffi 模块提供了基于 `JsonValue` 模块的 C 接口层，方便用户使用 C 接口调用 `ylong_json` 库的功能。
31
32## 目录
33```
34ylong_json
35├─ benches # benche 测试文件
36├─ docs # 说明文档
37├─ examples # ylong_json 代码示例
38├─ figures # ylong_json 架构图
39├─ src
40│ ├─ value # Array, Object 类型定义和相关方法实现
41│ ├─ adapter.rs # 适配 C 的接口实现
42│ ├─ consts.rs # 一些常数与表格的定义
43│ ├─ deserializer.rs # 适配 serde 的反序列化实现
44│ ├─ encoder.rs # 为 JsonValue 类型序列化实现
45│ ├─ error.rs # 错误类型定义，便于定位
46│ ├─ link_list.rs # LinkedList 类型定义和相关方法实现
47│ ├─ serializer_compact.rs # 适配 serde 的序列化实现
48│ ├─ states.rs # 为 JsonValue 类型反序列化实现
49│ └─ value.rs # JsonValue 类型定义和相关方法实现
50└─ tests # 测试目录
51```
52
53## 编译构建
54
55### 使用 Cargo 编译
561. 在 `Cargo.toml` 的依赖中添加 `ylong_json`
57```toml
58[dependencies]
59ylong_json = { git = "https://gitee.com/openharmony-sig/commonlibrary_rust_ylong_json.git" }
60```
61
62### 使用 GN 编译
631. 在 `bundle.json` 中添加 `ylong_json`
64```gn
65“deps”： {
66 “components”: ["ylong_json"]
67}
68```
69
702. 在 `BUILD.gn` 中添加 `ylong_json:lib`
71```gn
72external_deps = ["ylong_json:lib"]
73```
74
75## 用户指南
76详情内容请见[用户指南](./docs/user_guide_zh.md)
77
78## 性能测试
79
80以下测试来源于 [`nativejson-benchmark`](https://www.github.com/miloyip/nativejson-benchmark)。
81
82测试环境信息如下：
83```
84操作系统：Linux
85架构：x86_64
86字节序：小端
87CPU 型号：Intel(R) Xeon(R) Gold 6278C CPU @ 2.60GHz
88CPU 核心数：8
89内存：8G
90```
91
92测试的软件版本：
93
94cJSON 1.7.16
95
96测试结果：
97```
98======= ylong-json ==== parse | stringify ====
99canada.json 200 MB/s 90 MB/s
100citm_catalog.json 450 MB/s 300 MB/s
101twitter.json 340 MB/s 520 MB/s
102
103======== cJSON ======== parse | stringify ====
104canada.json 55 MB/s 11 MB/s
105citm_catalog.json 260 MB/s 170 MB/s
106twitter.json 210 MB/s 210 MB/s
107```
108
109测试结果描述：
110
111在 `nativejson-benchmark` 测试中提供了三种测试文件，其中 `canada.json` 包含了大量的 `number` 结构，`citm_catalog.json` 的各种数据类型较为平均，`twitter.json` 中存在各种 `UTF-8` 字符。
112为了保证测试公平性，`ylong_json` 开启了 `list_object` 和 `list_array` 以及 `ascii_only` feature。
113`list_object` 和 `list_array` feature 主要是为了保证和 `cJSON` 数据结构层面一致，都使用链表实现。
114`ascii_only` feature 是为了保证针对 `UTF-8` 字符的处理逻辑一致，`cJSON` 对于 UTF-8 字符不做处理。
115
116测试流程如下：
117 - 读取文件内容到内存，得到文件内容 `content`。
118 - 调用指定 `JSON` 库反序列化接口生成对应的 `JSON` 结构体 `data`。
119 - 调用 `JSON` 结构体的序列化接口生成输出内容 `result`。
120 - 利用 `content`，循环反序列化生成 100 次 `JSON` 结构体，取较小的处理时间 `t1`。
121 - 利用 `data`，序列化生成 100 次 `JSON` 文本，取较小的处理时间 `t2`。
122 - 计算解析速度，反序列化时间为 `content` 的长度除以 `t1`，序列化时间为 `JSON` 文本长度除以 `t2`。
