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![structure](./figures/ylong_json_oh_relate.png)
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![structure](./figures/ylong_json_inner_structure.png)
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`.