Update documents

CMakeLists.txt

@@ -4,7 +4,7 @@ project(yyjson VERSION 0.1.0)
 
 # Compile Options, see yyjson.h for more explanation.
 option(YYJSON_DISABLE_READER "Disable JSON reader" OFF)
-option(YYJSON_DISABLE_WRITER "disable JSON writer" OFF)
+option(YYJSON_DISABLE_WRITER "Disable JSON writer" OFF)
 option(YYJSON_DISABLE_FP_READER "Disable custom floating-point number reader" OFF)
 option(YYJSON_DISABLE_FP_WRITER "Disable custom floating-point number writer" OFF)
 option(YYJSON_DISABLE_COMMENT_READER "Disable non-standard comment reader" OFF)

README.md

@@ -9,14 +9,19 @@ A high performance JSON library written in ANSI C.
 
 # Features
 - **Fast**: can read or write gigabytes per second JSON data on modern CPU.
-- **Portable**: compliant with ANSI C (C89).
-- **Standard**: compliant with [RFC 8259](https://tools.ietf.org/html/rfc8259) and [ECMA-404](https://www.ecma-international.org/publications/standards/Ecma-404.htm) standard.
+- **Portable**: compliance with ANSI C (C89).
+- **Standard**: strict compliance with  [RFC 8259](https://tools.ietf.org/html/rfc8259) and [ECMA-404](https://www.ecma-international.org/publications/standards/Ecma-404.htm) standard.
 - **Safe**: complete JSON form, number format and UTF-8 validation.
 - **Accuracy**: can read and write `int64`, `uint64` and `double` number accurately.
-- **No Limit**: support large data size, unlimited JSON level, `\u0000` string.
+- **No Limit**: support unlimited JSON level, `\u0000` string.
 - **Extendable**: options to allow comments, trailing commas, nan/inf, custom memory allocator.
 - **Developer Friendly**: only one `h` and one `c` file, easy to use API.
 
+# Limitations
+- An array or object is stored as some [data structure](https://github.com/ibireme/yyjson/blob/master/doc/DataStructure.md) like linked list, access elements with index or key is slower than iterator.
+- Duplicate keys are allowed in an object, and the order of the keys is preserved.
+- JSON parsing result is immutable, a `mutable copy` is required for modification.
+
 # Performance
 Benchmark project and dataset: [yyjson_benchmark](https://github.com/ibireme/yyjson_benchmark)
 
@@ -73,11 +78,11 @@ More benchmark reports with interactive charts (update 2020-12-12)
 
 ### Manually
 Just copy `yyjson.h` and `yyjson.c` to your project and start using it.
-Since yyjson is ANSI C compatible, no other configuration is needed typically.
+Since `yyjson` is ANSI C compatible, no other configuration is needed typically.
 
-We have tested `yyjson` with the following compilers: gcc, clang, msvc, icc, tcc. If you find a compile error, please report a bug.
+`yyjson` has been tested with the following compilers: `gcc`, `clang`, `msvc`, `icc`, `tcc`. If you find a compile error, please [report a bug](https://github.com/ibireme/yyjson/issues/new?template=bug_report.md).
 
-yyjson includes all features by default, but you can trim out some of them by adding compile flags to get higher performance and/or smaller binary. See [compile flags](https://github.com/ibireme/yyjson/blob/master/doc/Building.md#compile-flags) for details.
+`yyjson` includes all features by default, but you can trim out some of them by adding compile flags to get higher performance and/or smaller binary. See [compile flags](https://github.com/ibireme/yyjson/blob/master/doc/Building.md#compile-flags) for details.
 
 ### CMake
 Clone repository and create build directory:
@@ -101,8 +106,8 @@ ctest
 
 Supported CMake options:
 
-- `-DYYJSON_BUILD_TESTS=ON` Build all tests.
 - `-DBUILD_SHARED_LIBS=ON` Build shared library instead of static library.
+- `-DYYJSON_BUILD_TESTS=ON` Build all tests.
 - `-DYYJSON_ENABLE_COVERAGE=ON` Enable code coverage for tests.
 - `-DYYJSON_ENABLE_VALGRIND=ON` Enable valgrind memory checker for tests.
 - `-DYYJSON_ENABLE_SANITIZE=ON` Enable sanitizer for tests.

doc/API.md

@@ -1188,21 +1188,20 @@ yyjson_type yyjson_mut_get_type(yyjson_mut_val *val);
 See [data structure](https://github.com/ibireme/yyjson/blob/master/doc/DataStructure.md) for more details.
 
 # Null Safe
-yyjson's API is designed to be null safe, which means that public API will check for NULL input to avoid crashes.
+`yyjson`'s public API will do `null check` for every input parameters to avoid crashes.
 
 For example, when reading a JSON, you don't need to do null check or type check on each value:
 ```c
-yyjson_doc *doc = yyjson_read("", 0, 0); // doc is NULL
+yyjson_doc *doc = yyjson_read(NULL, 0, 0); // doc is NULL
 yyjson_val *val = yyjson_doc_get_root(doc); // val is NULL
 const char *str = yyjson_get_str(val); // str is NULL
 if (!str) printf("err!");
 yyjson_doc_free(doc); // do nothing
 ```
 
+But if you are sure that a value is non-null, and the type is matched, you can use the `unsafe` prefix API to avoid the null check.
 
-If you are sure that a value is non-null, and the type is matched, you can use the `unsafe` prefix API to avoid the null check, but be careful because it's `unsafe`.
-
-For example, when traversing an array or object, the value and key must be non-null:
+For example, when iterating over an array or object, the value and key must be non-null:
 ```c
 size_t idx, max;
 yyjson_val *key, *val;

doc/Building.md

@@ -9,9 +9,9 @@
 
 ------
 # Import Manually
-`yyjson` aims to provide a cross-platform json library, so it was written in ANSI C (actually C99, but compatible with strict C89). You cay copy `yyjson.h` and `yyjson.c` to your project and start using it without any configuration.
+`yyjson` aims to provide a cross-platform JSON library, so it was written in ANSI C (actually C99, but compatible with strict C89). You can copy `yyjson.h` and `yyjson.c` to your project and start using it without any configuration.
 
-If you get compile error, please [report a bug](https://github.com/ibireme/yyjson/issues/new?assignees=&labels=&template=bug_report.md).
+If you get a compile error, please [report a bug](https://github.com/ibireme/yyjson/issues/new?template=bug_report.md).
 
 # Use CMake to build a library
 Clone repository and create build directory:
@@ -103,7 +103,7 @@ cmake .. -G Xcode -DYYJSON_BUILD_TESTS=ON
 
 ●**YYJSON_DISABLE_READER**<br/>
 Define it as 1 to disable the JSON reader.<br/>
-This may reduce binary size if you don't need read JSON.<br/>
+This flag can reduce binary size if you don't need to read JSON.<br/>
 These functions will be disabled by this flag:
 
 ```
@@ -114,7 +114,7 @@ yyjson_read()
 
 ●**YYJSON_DISABLE_WRITER**<br/>
 Define it as 1 to disable the JSON writer.<br/>
-This may reduce binary size if you don't need write JSON.<br/>
+This flag can reduce binary size if you don't need to write JSON.<br/>
 These functions will be disabled by this flag:
 
 ```
@@ -131,25 +131,25 @@ Define it as 1 to disable custom floating-point number reader.<br/>
 `yyjson` implements a high-performance floating-point number reader,<br/>
 but the fp reader may cost lots of binary size.<br/>
 
-This flag may disable the custom fp reader, and use libc's `strtod()` instead,<br/>
-so this flag may reduce binary size, but slow down floating-point reading speed.<br/>
+This flag will disable the custom fp reader, and use libc's `strtod()` instead,<br/>
+so this flag can reduce binary size, but slow down floating-point reading speed.<br/>
 
 ●**YYJSON_DISABLE_FP_WRITER**<br/>
 Define it as 1 to disable custom floating-point number writer.<br/>
 `yyjson` implements a high-performance floating-point number writer,<br/>
 but the fp writer may cost lots of binary size.<br/>
 
-This flag may disable the custom fp writer, and use libc's `sprintf()` instead,<br/>
-so this flag may reduce binary size, but slow down floating-point writing speed.<br/>
+This flag will disable the custom fp writer, and use libc's `sprintf()` instead,<br/>
+so this flag can reduce binary size, but slow down floating-point writing speed.<br/>
 
 ●**YYJSON_DISABLE_COMMENT_READER**<br/>
 Define it as 1 to disable non-standard comment support in JSON reader at compile time.<br/>
-This flag may reduce binary size, and increase reading speed slightly.<br/>
+This flag can reduce binary size, and increase reading speed slightly.<br/>
 This flag may also invalidate the `YYJSON_READ_ALLOW_TRAILING_COMMAS` option.
 
 ●**YYJSON_DISABLE_INF_AND_NAN_READER**<br/>
 Define it as 1 to disable non-standard inf and nan literal support in JSON reader at compile time.<br/>
-This flag may reduce binary size, and increase reading speed slightly.<br/>
+This flag can reduce binary size, and increase reading speed slightly.<br/>
 This flag may also invalidate the `YYJSON_READ_ALLOW_INF_AND_NAN` option.
 
 ●**YYJSON_EXPORTS**<br/>

doc/DataStructure.md

@@ -1,6 +1,6 @@
 # Data Structure
 
-yyjson have 2 types of data structures: immutable and mutable.
+yyjson has 2 types of data structures: immutable and mutable.
 
 When reading a JSON, yyjson returns immutable document and values;<br/>
 When building a JSON, yyjson creates mutable document and values.<br/>
@@ -27,20 +27,19 @@ struct yyjson_val {
 ![yyjson_val](images/struct_ival.svg)
 
 The lower 8 bits of `tag` stores the type of value.<br/>
-The higher 56 bits of `tag` stores the size of value (such as object size, array size, string length).
+The higher 56 bits of `tag` stores the size of value (string length, object size or array size).
 
 Modern 64-bit processors are typically limited to supporting fewer than 64 bits for RAM addresses ([Wikipedia](https://en.wikipedia.org/wiki/RAM_limit)). For example, Intel64, AMD64 and ARMv8 has a 52-bit (4PB) physical address limit. So we can safely store type and size into a 64 bits `tag`.
 
 ## Immutable Document
-yyjson document stores all strings in a **contiguous** memory area.<br/> 
+A JSON document stores all strings in a **contiguous** memory area.<br/> 
 Each string is unescaped in-place and ended with a null-terminator.<br/>
 For example:
 
 ![yyjson_val](images/struct_idoc1.svg)
 
 
-
-yyjson document stores all values in another **contiguous** memory area.<br/>
+A JSON document stores all values in another **contiguous** memory area.<br/>
 The `object` and `array` stores their own memory usage, so we can easily walk through a container's child values.<br/>
 For example:
 
@@ -69,7 +68,7 @@ The `tag` and `uni` field is same as immutable value, the `next` field is used t
 
 
 ## Mutable Document
-A yyjson document is composed of multiple `yyjson_mut_val`.
+A mutable JSON document is composed of multiple `yyjson_mut_val`.
 
 The child values of an `object` or `array` are linked as a cycle,<br/>
 the parent hold the **tail** of the linked list, so yyjson can do `append`, `prepend` and `remove_first` in O(1) time.