diff --git a/readme.md b/readme.md index 10332e1c..64538a65 100644 --- a/readme.md +++ b/readme.md @@ -7,7 +7,7 @@ 为什么选择 JSON？因为它足够简单，除基本编程外不需大量技术背景知识。JSON 有标准，可按照标准逐步实现。JSON 也是实际在许多应用上会使用的格式，所以才会有大量的开源库。 -这是一个免费、开源的教程，如果你喜欢，也可以打赏鼓励。因为工作及家庭因素，不能保证每篇文章的首发时间，请各为见谅。 +这是一个免费、开源的教程，如果你喜欢，也可以打赏鼓励。因为工作及家庭因素，不能保证每篇文章的首发时间，请各位见谅。 ## 对象与目标 @@ -44,7 +44,7 @@ 4. [Unicode](tutorial04/tutorial04.md)（2016/10/2 完成）：Unicode 和 UTF-8 的基本知识、JSON string 的 unicode 处理。练习完成 JSON string 类型的解析。[Unicode 解答篇](tutorial04_answer/tutorial04_answer.md)（2016/10/6 完成）。 5. [解析数组](tutorial05/tutorial05.md)（2016/10/7 完成）：JSON array 的语法。练习完成 JSON array 类型的解析、相关内存释放。[解析数组解答篇](tutorial05_answer/tutorial05_answer.md)（2016/10/13 完成）。 6. [解析对象](tutorial06/tutorial06.md)（2016/10/29 完成）：JSON object 的语法、重构 string 解析函数。练习完成 JSON object 的解析、相关内存释放。[解析对象解答篇](tutorial06_answer/tutorial06_answer.md)（2016/11/15 完成）。 -7. [生成器](tutorial07/tutorial07.md)（2016/12/20 完成）：JSON 生成过程、注意事项。练习完成 JSON 生成器。[生成器解答篇](tutorial07_answer/tutorial07_answer.md)（2017/1/5 完成） +7. [生成器](tutorial07/tutorial07.md)（2016/12/20 完成）：JSON 生成过程、注意事项。练习完成 JSON 生成器。[生成器解答篇](tutorial07_answer/tutorial07_answer.md)（2017/1/5 完成）。 8. [访问与其他功能](tutorial08/tutorial08.md)（2018/6/2 完成）：JSON array／object 的访问及修改。练习完成相关功能。 9. 终点及新开始：加入 nativejson-benchmark 测试，与 RapidJSON 对比及展望。 diff --git a/tutorial01/tutorial01.md b/tutorial01/tutorial01.md index 0f966fe5..4665e47e 100644 --- a/tutorial01/tutorial01.md +++ b/tutorial01/tutorial01.md @@ -7,20 +7,20 @@ 本单元内容： -1. [JSON 是什么](#json-是什么) -2. [搭建编译环境](#搭建编译环境) -3. [头文件与 API 设计](#头文件与-api-设计) -4. [JSON 语法子集](#json-语法子集) -5. [单元测试](#单元测试) -6. [宏的编写技巧](#宏的编写技巧) -7. [实现解析器](#实现解析器) -8. [关于断言](#关于断言) -9. [总结与练习](#总结与练习) -10. [常见问答](#常见问答) +1. [JSON 是什么](#1-json-是什么) +2. [搭建编译环境](#2-搭建编译环境) +3. [头文件与 API 设计](#3-头文件与-api-设计) +4. [JSON 语法子集](#4-json-语法子集) +5. [单元测试](#5-单元测试) +6. [宏的编写技巧](#6-宏的编写技巧) +7. [实现解析器](#7-实现解析器) +8. [关于断言](#8-关于断言) +9. [总结与练习](#9-总结与练习) +10. [常见问答](#10-常见问答) -## JSON 是什么 +## 1. JSON 是什么 -JSON（JavaScript Object Notation）是一个用于数据交换的文本格式，现时的标准为[ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf)。 +JSON（JavaScript Object Notation）是一个用于数据交换的文本格式，现时的标准为[ECMA-404](https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf)。 虽然 JSON 源至于 JavaScript 语言，但它只是一种数据格式，可用于任何编程语言。现时具类似功能的格式有 XML、YAML，当中以 JSON 的语法最为简单。 @@ -68,7 +68,7 @@ JSON（JavaScript Object Notation）是一个用于数据交换的文本格式 我们会逐步实现这些需求。在本单元中，我们只实现最简单的 null 和 boolean 解析。 -## 搭建编译环境 +## 2. 搭建编译环境 我们要做的库是跨平台、跨编译器的，同学可使用任意平台进行练习。 @@ -90,7 +90,7 @@ JSON（JavaScript Object Notation）是一个用于数据交换的文本格式 按 Configure，选择编译器，然后按 Generate 便会生成 Visual Studio 的 .sln 和 .vcproj 等文件。注意这个 build 目录都是生成的文件，可以随时删除，也不用上传至仓库。 -在 OS X 下，建议安装 [Homebrew](http://brew.sh/)，然后在命令行键入： +在 OS X 下，建议安装 [Homebrew](https://brew.sh/)，然后在命令行键入： ~~~ $ brew install cmake @@ -126,7 +126,7 @@ $ ./leptjson_test 若看到类似以上的结果，说明已成功搭建编译环境，我们可以去看看那几个代码文件的内容了。 -## 头文件与 API 设计 +## 3. 头文件与 API 设计 C 语言有头文件的概念，需要使用 `#include`去引入头文件中的类型声明和函数声明。但由于头文件也可以 `#include` 其他头文件，为避免重复声明，通常会利用宏加入 include 防范（include guard）： @@ -193,9 +193,9 @@ enum { lept_type lept_get_type(const lept_value* v); ~~~ -## JSON 语法子集 +## 4. JSON 语法子集 -下面是此单元的 JSON 语法子集，使用 [RFC7159](http://rfc7159.net/rfc7159) 中的 [ABNF](https://tools.ietf.org/html/rfc5234) 表示： +下面是此单元的 JSON 语法子集，使用 [RFC7159](https://tools.ietf.org/html/rfc7159) 中的 [ABNF](https://tools.ietf.org/html/rfc5234) 表示： ~~~ JSON-text = ws value ws @@ -222,11 +222,11 @@ true = "true" * 若一个值之后，在空白之后还有其他字符，传回 `LEPT_PARSE_ROOT_NOT_SINGULAR`。 * 若值不是那三种字面值，传回 `LEPT_PARSE_INVALID_VALUE`。 -## 单元测试 +## 5. 单元测试 许多同学在做练习题时，都是以 `printf`／`cout` 打印结果，再用肉眼对比结果是否乎合预期。但当软件项目越来越复杂，这个做法会越来越低效。一般我们会采用自动的测试方式，例如单元测试（unit testing）。单元测试也能确保其他人修改代码后，原来的功能维持正确（这称为回归测试／regression testing）。 -常用的单元测试框架有 xUnit 系列，如 C++ 的 [Google Test](https://github.com/google/googletest)、C# 的 [NUnit](http://www.nunit.org/)。我们为了简单起见，会编写一个极简单的单元测试方式。 +常用的单元测试框架有 xUnit 系列，如 C++ 的 [Google Test](https://github.com/google/googletest)、C# 的 [NUnit](https://www.nunit.org/)。我们为了简单起见，会编写一个极简单的单元测试方式。 一般来说，软件开发是以周期进行的。例如，加入一个功能，再写关于该功能的单元测试。但也有另一种软件开发方法论，称为测试驱动开发（test-driven development, TDD），它的主要循环步骤是： @@ -243,7 +243,7 @@ TDD 是先写测试，再实现功能。好处是实现只会刚好满足测试 回到 leptjson 项目，`test.c` 包含了一个极简的单元测试框架： -~~~ +~~~c #include #include #include @@ -299,7 +299,7 @@ int main() { 然而，完全按照 TDD 的步骤来开发，是会减慢开发进程。所以我个人会在这两种极端的工作方式取平衡。通常会在设计 API 后，先写部分测试代码，再写满足那些测试的实现。 -## 宏的编写技巧 +## 6. 宏的编写技巧 有些同学可能不了解 `EXPECT_EQ_BASE` 宏的编写技巧，简单说明一下。反斜线代表该行未结束，会串接下一行。而如果宏里有多过一个语句（statement），就需要用 `do { /*...*/ } while(0)` 包裹成单个语句，否则会有如下的问题： @@ -344,7 +344,7 @@ else c(); ~~~ -## 实现解析器 +## 7. 实现解析器 有了 API 的设计、单元测试，终于要实现解析器了。 @@ -419,15 +419,15 @@ static int lept_parse_value(lept_context* c, lept_value* v) { 由于 `lept_parse_whitespace()` 是不会出现错误的，返回类型为 `void`。其它的解析函数会返回错误码，传递至顶层。 -## 关于断言 +## 8. 关于断言 断言（assertion）是 C 语言中常用的防御式编程方式，减少编程错误。最常用的是在函数开始的地方，检测所有参数。有时候也可以在调用函数后，检查上下文是否正确。 -C 语言的标准库含有 [`assert()`](http://en.cppreference.com/w/c/error/assert) 这个宏（需 `#include `），提供断言功能。当程序以 release 配置编译时（定义了 `NDEBUG` 宏），`assert()` 不会做检测；而当在 debug 配置时（没定义 `NDEBUG` 宏），则会在运行时检测 `assert(cond)` 中的条件是否为真（非 0），断言失败会直接令程序崩溃。 +C 语言的标准库含有 [`assert()`](https://en.cppreference.com/w/c/error/assert) 这个宏（需 `#include `），提供断言功能。当程序以 release 配置编译时（定义了 `NDEBUG` 宏），`assert()` 不会做检测；而当在 debug 配置时（没定义 `NDEBUG` 宏），则会在运行时检测 `assert(cond)` 中的条件是否为真（非 0），断言失败会直接令程序崩溃。 例如上面的 `lept_parse_null()` 开始时，当前字符应该是 `'n'`，所以我们使用一个宏 `EXPECT(c, ch)` 进行断言，并跳到下一字符。 -初使用断言的同学，可能会错误地把含副作用的代码放在 `assert()` 中： +初使用断言的同学，可能会错误地把含[副作用](https://en.wikipedia.org/wiki/Side_effect_(computer_science))的代码放在 `assert()` 中： ~~~c assert(x++ == 0); /* 这是错误的! */ @@ -437,7 +437,7 @@ assert(x++ == 0); /* 这是错误的! */ 另一个问题是，初学者可能会难于分辨何时使用断言，何时处理运行时错误（如返回错误值或在 C++ 中抛出异常）。简单的答案是，如果那个错误是由于程序员错误编码所造成的（例如传入不合法的参数），那么应用断言；如果那个错误是程序员无法避免，而是由运行时的环境所造成的，就要处理运行时错误（例如开启文件失败）。 -## 总结与练习 +## 9. 总结与练习 本文介绍了如何配置一个编程环境，单元测试的重要性，以至于一个 JSON 解析器的子集实现。如果你读到这里，还未动手，建议你快点试一下。以下是本单元的练习，很容易的，但我也会在稍后发出解答篇。 @@ -445,7 +445,7 @@ assert(x++ == 0); /* 这是错误的! */ 2. 参考 `test_parse_null()`，加入 `test_parse_true()`、`test_parse_false()` 单元测试。 3. 参考 `lept_parse_null()` 的实现和调用方，解析 true 和 false 值。 -## 常见问答 +## 10. 常见问答 1. 为什么把例子命名为 leptjson？ diff --git a/tutorial01_answer/tutorial01_answer.md b/tutorial01_answer/tutorial01_answer.md index 99865363..63bf0c69 100644 --- a/tutorial01_answer/tutorial01_answer.md +++ b/tutorial01_answer/tutorial01_answer.md @@ -69,7 +69,7 @@ static void test_parse() { } ~~~ -但要记得在上一级的测试函数 `test_parse()` 调用这函数，否则会不起作用。还好如果我们记得用 `static` 修饰这两个函数，编译器会发出告警： +但要记得在上一级的测试函数 `test_parse()` 调用这函数，否则会不起作用。还好如果我们记得用 `static` 修饰这两个函数，编译器会发出警告： ~~~ test.c:30:13: warning: unused function 'test_parse_true' [-Wunused-function] diff --git a/tutorial02/leptjson.h b/tutorial02/leptjson.h index 4818278c..0a2652bf 100644 --- a/tutorial02/leptjson.h +++ b/tutorial02/leptjson.h @@ -4,7 +4,7 @@ typedef enum { LEPT_NULL, LEPT_FALSE, LEPT_TRUE, LEPT_NUMBER, LEPT_STRING, LEPT_ARRAY, LEPT_OBJECT } lept_type; typedef struct { - double n; + double n; lept_type type; }lept_value; diff --git a/tutorial02/tutorial02.md b/tutorial02/tutorial02.md index 5f520b2b..820ba35f 100644 --- a/tutorial02/tutorial02.md +++ b/tutorial02/tutorial02.md @@ -7,16 +7,16 @@ 本单元内容： -1. [初探重构](#初探重构) -2. [JSON 数字语法](#json-数字语法) -3. [数字表示方式](#数字表示方式) -4. [单元测试](#单元测试) -5. [十进制转换至二进制](#十进制转换至二进制) -6. [总结与练习](#总结与练习) -7. [参考](#参考) -8. [常见问题](#常见问题) +1. [初探重构](#1-初探重构) +2. [JSON 数字语法](#2-json-数字语法) +3. [数字表示方式](#3-数字表示方式) +4. [单元测试](#4-单元测试) +5. [十进制转换至二进制](#5-十进制转换至二进制) +6. [总结与练习](#6-总结与练习) +7. [参考](#7-参考) +8. [常见问题](#8-常见问题) -# 1. 初探重构 +## 1. 初探重构 在讨论解析数字之前，我们再补充 TDD 中的一个步骤──重构（refactoring）。根据[1]，重构是一个这样的过程： @@ -45,7 +45,7 @@ static void test_parse_expect_value() { 最后，我希望指出，软件的架构难以用单一标准评分，重构时要考虑平衡各种软件品质。例如上述把 3 个函数合并后，优点是减少重复的代码，维护较容易，但缺点可能是带来性能的少量影响。 -# 2. JSON 数字语法 +## 2. JSON 数字语法 回归正题，本单元的重点在于解析 JSON number 类型。我们先看看它的语法： @@ -64,13 +64,13 @@ number 是以十进制表示，它主要由 4 部分顺序组成：负号、整 JSON 可使用科学记数法，指数部分由大写 E 或小写 e 开始，然后可有正负号，之后是一或多个数字（0-9）。 -JSON 标准 [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) 采用图的形式表示语法，也可以更直观地看到解析时可能经过的路径： +JSON 标准 [ECMA-404](https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) 采用图的形式表示语法，也可以更直观地看到解析时可能经过的路径： ![number](images/number.png) 上一单元的 null、false、true 在解析后，我们只需把它们存储为类型。但对于数字，我们要考虑怎么存储解析后的结果。 -# 3. 数字表示方式 +## 3. 数字表示方式 从 JSON 数字的语法，我们可能直观地会认为它应该表示为一个浮点数（floating point number），因为它带有小数和指数部分。然而，标准中并没有限制数字的范围或精度。为简单起见，leptjson 选择以双精度浮点数（C 中的 `double` 类型）来存储 JSON 数字。 @@ -94,7 +94,7 @@ double lept_get_number(const lept_value* v) { 使用者应确保类型正确，才调用此 API。我们继续使用断言来保证。 -# 4. 单元测试 +## 4. 单元测试 我们定义了 API 之后，按照 TDD，我们可以先写一些单元测试。这次我们使用多行的宏的减少重复代码： @@ -149,9 +149,9 @@ static void test_parse_invalid_value() { } ~~~ -# 5. 十进制转换至二进制 +## 5. 十进制转换至二进制 -我们需要把十进制的数字转换成二进制的 `double`。这并不是容易的事情 [2]。为了简单起见，leptjson 将使用标准库的 [`strtod()`](http://en.cppreference.com/w/c/string/byte/strtof) 来进行转换。`strtod()` 可转换 JSON 所要求的格式，但问题是，一些 JSON 不容许的格式，`strtod()` 也可转换，所以我们需要自行做格式校验。 +我们需要把十进制的数字转换成二进制的 `double`。这并不是容易的事情 [2]。为了简单起见，leptjson 将使用标准库的 [`strtod()`](https://en.cppreference.com/w/c/string/byte/strtof) 来进行转换。`strtod()` 可转换 JSON 所要求的格式，但问题是，一些 JSON 不容许的格式，`strtod()` 也可转换，所以我们需要自行做格式校验。 ~~~c #include /* NULL, strtod() */ @@ -192,7 +192,7 @@ static int lept_parse_value(lept_context* c, lept_value* v) { } ~~~ -# 6. 总结与练习 +## 6. 总结与练习 本单元讲述了 JSON 数字类型的语法，以及 leptjson 所采用的自行校验＋`strtod()`转换为 `double` 的方案。实际上一些 JSON 库会采用更复杂的方案，例如支持 64 位带符号／无符号整数，自行实现转换。以我的个人经验，解析／生成数字类型可以说是 RapidJSON 中最难实现的部分，也是 RapidJSON 高效性能的原因，有机会再另外撰文解释。 @@ -200,8 +200,8 @@ static int lept_parse_value(lept_context* c, lept_value* v) { 1. 重构合并 `lept_parse_null()`、`lept_parse_false()`、`lept_parse_true` 为 `lept_parse_literal()`。 2. 加入 [维基百科双精度浮点数](https://en.wikipedia.org/wiki/Double-precision_floating-point_format#Double-precision_examples) 的一些边界值至单元测试，如 min subnormal positive double、max double 等。 -3. 去掉 `test_parse_invalid_value()` 和 `test_parse_root_not_singular` 中的 `#if 0 ... #endif`，执行测试，证实测试失败。按 JSON number 的语法在 lept_parse_number() 校验，不符合标准的程况返回 `LEPT_PARSE_INVALID_VALUE`　错误码。 -4. 去掉 `test_parse_number_too_big` 中的 `#if 0 ... #endif`，执行测试，证实测试失败。仔细阅读 [`strtod()`](http://en.cppreference.com/w/c/string/byte/strtof)，看看怎样从返回值得知数值是否过大，以返回 `LEPT_PARSE_NUMBER_TOO_BIG` 错误码。（提示：这里需要 `#include` 额外两个标准库头文件。） +3. 去掉 `test_parse_invalid_value()` 和 `test_parse_root_not_singular` 中的 `#if 0 ... #endif`，执行测试，证实测试失败。按 JSON number 的语法在 lept_parse_number() 校验，不符合标准的程况返回 `LEPT_PARSE_INVALID_VALUE` 错误码。 +4. 去掉 `test_parse_number_too_big` 中的 `#if 0 ... #endif`，执行测试，证实测试失败。仔细阅读 [`strtod()`](https://en.cppreference.com/w/c/string/byte/strtof)，看看怎样从返回值得知数值是否过大，以返回 `LEPT_PARSE_NUMBER_TOO_BIG` 错误码。（提示：这里需要 `#include` 额外两个标准库头文件。） 以上最重要的是第 3 条题目，就是要校验 JSON 的数字语法。建议可使用以下两个宏去简化一下代码： @@ -214,12 +214,13 @@ static int lept_parse_value(lept_context* c, lept_value* v) { 如果你遇到问题，有不理解的地方，或是有建议，都欢迎在评论或 [issue](https://github.com/miloyip/json-tutorial/issues) 中提出，让所有人一起讨论。 -# 7. 参考 +## 7. 参考 [1] Fowler, Martin. Refactoring: improving the design of existing code. Pearson Education India, 2009. 中译本：《重构：改善既有代码的设计》，熊节译，人民邮电出版社，2010年。 + [2] Gay, David M. "Correctly rounded binary-decimal and decimal-binary conversions." Numerical Analysis Manuscript 90-10 (1990). -# 8. 常见问题 +## 8. 常见问题 1. 为什么要把一些测试代码以 `#if 0 ... #endif` 禁用？ @@ -227,6 +228,6 @@ static int lept_parse_value(lept_context* c, lept_value* v) { 2. 科学计数法的指数部分没有对前导零作限制吗？`1E012` 也是合法的吗？ - 是的，这是合法的。JSON 源自于 JavaScript（[ECMA-262, 3rd edition](http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf)），数字语法取自 JavaScript 的十进位数字的语法（§7.8.3 Numeric Literals）。整数不容许前导零（leading zero），是因为更久的 JavaScript 版本容许以前导零来表示八进位数字，如 `052 == 42`，这种八进位常数表示方式来自于 [C 语言](http://en.cppreference.com/w/c/language/integer_constant)。禁止前导零避免了可能出现的歧义。但是在指数里就不会出现这个问题。多谢 @Smallay 提出及协助解答这个问题。 + 是的，这是合法的。JSON 源自于 JavaScript（[ECMA-262, 3rd edition](https://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf)），数字语法取自 JavaScript 的十进位数字的语法（§7.8.3 Numeric Literals）。整数不容许前导零（leading zero），是因为更久的 JavaScript 版本容许以前导零来表示八进位数字，如 `052 == 42`，这种八进位常数表示方式来自于 [C 语言](https://en.cppreference.com/w/c/language/integer_constant)。禁止前导零避免了可能出现的歧义。但是在指数里就不会出现这个问题。多谢 @Smallay 提出及协助解答这个问题。 其他常见问答将会从评论中整理。 diff --git a/tutorial02_answer/tutorial02_answer.md b/tutorial02_answer/tutorial02_answer.md index 37451ae9..7079201a 100644 --- a/tutorial02_answer/tutorial02_answer.md +++ b/tutorial02_answer/tutorial02_answer.md @@ -55,7 +55,7 @@ TEST_NUMBER(-1.7976931348623157e+308, "-1.7976931348623157e+308"); 有一些 JSON 解析器不使用 `strtod()` 而自行转换，例如在校验的同时，记录负号、尾数（整数和小数）和指数，然后 naive 地计算： -~~~ +~~~c int negative = 0; int64_t mantissa = 0; int exp = 0; @@ -101,7 +101,7 @@ exp = ("e" / "E") ["-" / "+"] 1*digit if (*p == '-') p++; ~~~ -整数部分有两种合法情况，一是单个 `0`，否则是一个 1-9 再加上任意数量的 digit。对于第一种情况，我们像负数般跳过便行。对于第二种情况，第一个字符必须为 1-9，如果否定的就是不合法的，可立即返回错误码。然后，有多少个 digit 就跳过多少个。 +整数部分有两种合法情况，一是单个 `0`，否则是一个 1-9 再加上任意数量的 digit。对于第一种情况，我们像负号般跳过便行。对于第二种情况，第一个字符必须为 1-9，如果否定的就是不合法的，可立即返回错误码。然后，有多少个 digit 就跳过多少个。 ~~~c if (*p == '0') p++; @@ -157,7 +157,7 @@ static int lept_parse_number(lept_context* c, lept_value* v) { } ~~~ -许多时候课本／书籍也不会把每个标准库功能说得很仔细，我想藉此提醒同学要好好看参考文档，学会读文档编程就简单得多！[cppreference.com](http://cppreference.com) 是 C/C++ 程序员的宝库。 +许多时候课本／书籍也不会把每个标准库功能说得很仔细，我想藉此提醒同学要好好看参考文档，学会读文档编程就简单得多！[cppreference.com](https://cppreference.com) 是 C/C++ 程序员的宝库。 ## 5. 总结 diff --git a/tutorial03/tutorial03.md b/tutorial03/tutorial03.md index 113eea78..8179e0d4 100644 --- a/tutorial03/tutorial03.md +++ b/tutorial03/tutorial03.md @@ -7,14 +7,14 @@ 本单元内容： -1. [JSON 字符串语法](#json-字符串语法) -2. [字符串表示](#字符串表示) -3. [内存管理](#内存管理) -4. [缓冲区与堆栈](#缓冲区与堆栈) -5. [解析字符串](#解析字符串) -6. [总结和练习](#总结和练习) -7. [参考](#参考) -8. [常见问题](#常见问题) +1. [JSON 字符串语法](#1-json-字符串语法) +2. [字符串表示](#2-字符串表示) +3. [内存管理](#3-内存管理) +4. [缓冲区与堆栈](#4-缓冲区与堆栈) +5. [解析字符串](#5-解析字符串) +6. [总结和练习](#6-总结和练习) +7. [参考](#7-参考) +8. [常见问题](#8-常见问题) ## 1. JSON 字符串语法 @@ -44,7 +44,7 @@ unescaped = %x20-21 / %x23-5B / %x5D-10FFFF ## 2. 字符串表示 -在 C 语言中，字符串一般表示为空结尾字符串（null-terminated string），即以空字符（`'\0'`）代表字符串的结束。然而，JSON 字符串是允许含有空字符的，例如这个 JSON `"Hello\u0000World"` 就是单个字符串，解析后为11个字符。如果纯粹使用空结尾字符来表示 JSON 解析后的结果，就没法处理空字符。 +在 C 语言中，字符串一般表示为空结尾字符串（null-terminated string），即以空字符（`'\0'`）代表字符串的结束。然而，JSON 字符串是允许含有空字符的，例如这个 JSON `"Hello\u0000World"` 就是单个字符串，解析后为11个字符。如果纯粹使用空结尾字符串来表示 JSON 解析后的结果，就没法处理空字符。 因此，我们可以分配内存来储存解析后的字符，以及记录字符的数目（即字符串长度）。由于大部分 C 程序都假设字符串是空结尾字符串，我们还是在最后加上一个空字符，那么不需处理 `\u0000` 这种字符的应用可以简单地把它当作是空结尾字符串。 @@ -158,7 +158,7 @@ static void test_access_string() { 我们解析字符串（以及之后的数组、对象）时，需要把解析的结果先储存在一个临时的缓冲区，最后再用 `lept_set_string()` 把缓冲区的结果设进值之中。在完成解析一个字符串之前，这个缓冲区的大小是不能预知的。因此，我们可以采用动态数组（dynamic array）这种数据结构，即数组空间不足时，能自动扩展。C++ 标准库的 `std::vector` 也是一种动态数组。 -如果每次解析字符串时，都重新建一个动态数组，那么是比较耗时的。我们可以重用这个动态数组，每次解析 JSON 时就只需要创建一个。而且我们将会发现，无论是解析字符串、数组或对象，我们也只需要以先进后出的方式访问这个动态数组。换句话说，我们需要一个动态的堆栈数据结构。 +如果每次解析字符串时，都重新建一个动态数组，那么是比较耗时的。我们可以重用这个动态数组，每次解析 JSON 时就只需要创建一个。而且我们将会发现，无论是解析字符串、数组或对象，我们也只需要以先进后出的方式访问这个动态数组。换句话说，我们需要一个动态的堆栈（stack）数据结构。 我们把一个动态堆栈的数据放进 `lept_context` 里： @@ -225,7 +225,7 @@ static void* lept_context_pop(lept_context* c, size_t size) { 压入时若空间不足，便回以 1.5 倍大小扩展。为什么是 1.5 倍而不是两倍？可参考我在 [STL 的 vector 有哪些封装上的技巧？](https://www.zhihu.com/question/25079705/answer/30030883) 的答案。 -注意到这里使用了 [`realloc()`](http://en.cppreference.com/w/c/memory/realloc) 来重新分配内存，`c->stack` 在初始化时为 `NULL`，`realloc(NULL, size)` 的行为是等价于 `malloc(size)` 的，所以我们不需要为第一次分配内存作特别处理。 +注意到这里使用了 [`realloc()`](https://en.cppreference.com/w/c/memory/realloc) 来重新分配内存，`c->stack` 在初始化时为 `NULL`，`realloc(NULL, size)` 的行为是等价于 `malloc(size)` 的，所以我们不需要为第一次分配内存作特别处理。 另外，我们把初始大小以宏 `LEPT_PARSE_STACK_INIT_SIZE` 的形式定义，使用 `#ifndef X #define X ... #endif` 方式的好处是，使用者可在编译选项中自行设置宏，没设置的话就用缺省值。 diff --git a/tutorial03_answer/tutorial03_answer.md b/tutorial03_answer/tutorial03_answer.md index 77d56084..8747fccc 100644 --- a/tutorial03_answer/tutorial03_answer.md +++ b/tutorial03_answer/tutorial03_answer.md @@ -105,7 +105,7 @@ Object dump complete. ## 1B. Linux/OSX 下的内存泄漏检测方法 -在 Linux、OS X 下，我们可以使用 [valgrind](http://valgrind.org/) 工具（用 `apt-get install valgrind`、 `brew install valgrind`）。我们完全不用修改代码，只要在命令行执行： +在 Linux、OS X 下，我们可以使用 [valgrind](https://valgrind.org/) 工具（用 `apt-get install valgrind`、 `brew install valgrind`）。我们完全不用修改代码，只要在命令行执行： ~~~ $ valgrind --leak-check=full ./leptjson_test diff --git a/tutorial04/test.c b/tutorial04/test.c index beaa8724..a0c2e54d 100644 --- a/tutorial04/test.c +++ b/tutorial04/test.c @@ -191,7 +191,7 @@ static void test_parse_invalid_unicode_hex() { TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\uG000\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0G00\""); - TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); + TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00/0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00G0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000/\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000G\""); diff --git a/tutorial04/tutorial04.md b/tutorial04/tutorial04.md index a5091176..5009cb6c 100644 --- a/tutorial04/tutorial04.md +++ b/tutorial04/tutorial04.md @@ -77,7 +77,7 @@ UTF-8 在网页上的使用率势无可挡： 由于我们的 JSON 库也只支持 UTF-8，我们需要把码点编码成 UTF-8。这里简单介绍一下 UTF-8 的编码方式。 -UTF-8 的编码单元是 8 位字节，每个码点编码成 1 至 4 个字节。它的编码方式很简单，按照码点的范围，把码点的二进位分拆成 1 至最多 4 个字节： +UTF-8 的编码单元为 8 位（1 字节），每个码点编码成 1 至 4 个字节。它的编码方式很简单，按照码点的范围，把码点的二进位分拆成 1 至最多 4 个字节： | 码点范围 | 码点位数 | 字节1 | 字节2 | 字节3 | 字节4 | |:------------------:|:--------:|:--------:|:--------:|:--------:|:--------:| diff --git a/tutorial04_answer/test.c b/tutorial04_answer/test.c index 46a1d1f7..db947998 100644 --- a/tutorial04_answer/test.c +++ b/tutorial04_answer/test.c @@ -191,7 +191,7 @@ static void test_parse_invalid_unicode_hex() { TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\uG000\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0G00\""); - TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); + TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00/0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00G0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000/\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000G\""); diff --git a/tutorial04_answer/tutorial04_answer.md b/tutorial04_answer/tutorial04_answer.md index e634a069..f7020877 100644 --- a/tutorial04_answer/tutorial04_answer.md +++ b/tutorial04_answer/tutorial04_answer.md @@ -25,7 +25,7 @@ static const char* lept_parse_hex4(const char* p, unsigned* u) { } ~~~ -可能有同学想到用标准库的 [`strtol()`](http://en.cppreference.com/w/c/string/byte/strtol)，因为它也能解析 16 进制数字，那么可以简短的写成： +可能有同学想到用标准库的 [`strtol()`](https://en.cppreference.com/w/c/string/byte/strtol)，因为它也能解析 16 进制数字，那么可以简短的写成： ~~~c static const char* lept_parse_hex4(const char* p, unsigned* u) { @@ -35,7 +35,7 @@ static const char* lept_parse_hex4(const char* p, unsigned* u) { } ~~~ -但这个实现会错误地接受 `"\u 123"` 这种不合法的 JSON，因为 `strtol()` 会跳过开始的空白。要解决的话，还需要检测第一个字符是否 `[0-9A-Fa-f]`，或者 `!isspace(*p)`。但为了 `strtol()` 做多余的检测，而且自行实现也很简单，我个人会选择首个方案。（前两个单元用 `strtod()` 就没辨法，因为它的实现要复杂得多。） +但这个实现会错误地接受 `"\u 123"` 这种不合法的 JSON，因为 `strtol()` 会跳过开始的空白。要解决的话，还需要检测第一个字符是否 `[0-9A-Fa-f]`，或者 `!isspace(*p)`。但为了 `strtol()` 做多余的检测，而且自行实现也很简单，我个人会选择首个方案。（前两个单元用 `strtod()` 就没办法，因为它的实现要复杂得多。） ## 2. 实现 `lept_encode_utf8()` diff --git a/tutorial05/test.c b/tutorial05/test.c index 2d4dd21e..62389f0a 100644 --- a/tutorial05/test.c +++ b/tutorial05/test.c @@ -213,7 +213,7 @@ static void test_parse_invalid_unicode_hex() { TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\uG000\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0G00\""); - TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); + TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00/0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00G0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000/\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000G\""); diff --git a/tutorial05_answer/test.c b/tutorial05_answer/test.c index 1a17a2a7..d49419e7 100644 --- a/tutorial05_answer/test.c +++ b/tutorial05_answer/test.c @@ -241,7 +241,7 @@ static void test_parse_invalid_unicode_hex() { TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\uG000\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0G00\""); - TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); + TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00/0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00G0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000/\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000G\""); diff --git a/tutorial05_answer/tutorial05_answer.md b/tutorial05_answer/tutorial05_answer.md index 8b27f325..466c4f01 100644 --- a/tutorial05_answer/tutorial05_answer.md +++ b/tutorial05_answer/tutorial05_answer.md @@ -184,7 +184,7 @@ static int lept_parse_array(lept_context* c, lept_value* v) { 但这种 bug 有时可能在简单测试中不能自动发现，因为问题只有堆栈满了才会出现。从测试的角度看，我们需要一些压力测试（stress test），测试更大更复杂的数据。但从编程的角度看，我们要谨慎考虑变量的生命周期，尽量从编程阶段避免出现问题。例如把 `lept_context_push()` 的 API 改为： -~~~ +~~~c static void lept_context_push(lept_context* c, const void* data, size_t size); ~~~ diff --git a/tutorial06/test.c b/tutorial06/test.c index 8d332e45..544eaeb3 100644 --- a/tutorial06/test.c +++ b/tutorial06/test.c @@ -300,7 +300,7 @@ static void test_parse_invalid_unicode_hex() { TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\uG000\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0G00\""); - TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); + TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00/0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00G0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000/\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000G\""); diff --git a/tutorial06/tutorial06.md b/tutorial06/tutorial06.md index 749270ae..90cf5714 100644 --- a/tutorial06/tutorial06.md +++ b/tutorial06/tutorial06.md @@ -7,7 +7,7 @@ 本单元内容： -1. [JSON 对象](#1-JSON-对象) +1. [JSON 对象](#1-json-对象) 2. [数据结构](#2-数据结构) 3. [重构字符串解析](#3-重构字符串解析) 4. [实现](#4-实现) @@ -26,19 +26,19 @@ object = %x7B ws [ member *( ws %x2C ws member ) ] ws %x7D 要表示键值对的集合，有很多数据结构可供选择，例如： -* 动态数组（dynamic array）：可扩展容量的数组，如 C++ 的 [`std::vector`](http://en.cppreference.com/w/cpp/container/vector)。 +* 动态数组（dynamic array）：可扩展容量的数组，如 C++ 的 [`std::vector`](https://en.cppreference.com/w/cpp/container/vector)。 * 有序动态数组（sorted dynamic array）：和动态数组相同，但保证元素已排序，可用二分搜寻查询成员。 -* 平衡树（balanced tree）：平衡二叉树可有序地遍历成员，如红黑树和 C++ 的 [`std::map`](http://en.cppreference.com/w/cpp/container/map)（[`std::multi_map`](http://en.cppreference.com/w/cpp/container/multimap) 支持重复键）。 -* 哈希表（hash table）：通过哈希函数能实现平均 O(1) 查询，如 C++11 的 [`std::unordered_map`](http://en.cppreference.com/w/cpp/container/unordered_map)（[`unordered_multimap`](http://en.cppreference.com/w/cpp/container/unordered_multimap) 支持重复键）。 +* 平衡树（balanced tree）：平衡二叉树可有序地遍历成员，如红黑树和 C++ 的 [`std::map`](https://en.cppreference.com/w/cpp/container/map)（[`std::multi_map`](https://en.cppreference.com/w/cpp/container/multimap) 支持重复键）。 +* 哈希表（hash table）：通过哈希函数能实现平均 O(1) 查询，如 C++11 的 [`std::unordered_map`](https://en.cppreference.com/w/cpp/container/unordered_map)（[`unordered_multimap`](https://en.cppreference.com/w/cpp/container/unordered_multimap) 支持重复键）。 设一个对象有 n 个成员，数据结构的容量是 m，n ⩽ m，那么一些常用操作的时间／空间复杂度如下： -| |动态数组 |有序动态数组|平衡树 |哈希表 | -|---------------|:-------:|:----------:|:--------:|:--------------------:| +| |动态数组 |有序动态数组|平衡树 |哈希表 | +|---------------|:-------:|:----------:|:--------:|:--------------------:| |有序 |否 |是 |是 |否 | |自定成员次序 |可 |否 |否 |否 | |初始化 n 个成员|O(n) |O(n log n) |O(n log n)|平均 O(n)、最坏 O(n^2)| -|加入成员 |分摊 O(1)|O(n) |O(log n) |平均 O(1)、最坏 O(n) | +|加入成员 |分摊 O(1)|O(n) |O(log n) |平均 O(1)、最坏 O(n) | |移除成员 |O(n) |O(n) |O(log n) |平均 O(1)、最坏 O(n) | |查询成员 |O(n) |O(log n) |O(log n) |平均 O(1)、最坏 O(n) | |遍历成员 |O(n) |O(n) |O(n) |O(m) | diff --git a/tutorial06_answer/test.c b/tutorial06_answer/test.c index ad4dc6f3..04319804 100644 --- a/tutorial06_answer/test.c +++ b/tutorial06_answer/test.c @@ -300,7 +300,7 @@ static void test_parse_invalid_unicode_hex() { TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\uG000\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0G00\""); - TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u0/00\""); + TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00/0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u00G0\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000/\""); TEST_ERROR(LEPT_PARSE_INVALID_UNICODE_HEX, "\"\\u000G\""); diff --git a/tutorial07/tutorial07.md b/tutorial07/tutorial07.md index c301abe3..625bc761 100644 --- a/tutorial07/tutorial07.md +++ b/tutorial07/tutorial07.md @@ -5,6 +5,14 @@ 本文是[《从零开始的 JSON 库教程》](https://zhuanlan.zhihu.com/json-tutorial)的第七个单元。代码位于 [json-tutorial/tutorial07](https://github.com/miloyip/json-tutorial/blob/master/tutorial07)。 +本单元内容： + +1. [JSON 生成器](#1-json-生成器) +2. [再利用 lept_context 做动态数组](#2-再利用-lept_context-做动态数组) +3. [生成 null、false 和 true](#3-生成-nullfalse-和-true) +4. [生成数字](#4-生成数字) +5. [总结与练习](#5-总结与练习) + ## 1. JSON 生成器 我们在前 6 个单元实现了一个合乎标准的 JSON 解析器，它把 JSON 文本解析成一个树形数据结构，整个结构以 `lept_value` 的节点组成。 @@ -148,7 +156,7 @@ leptjson 重复利用了 `lept_context` 中的数据结构作为输出缓冲， 1. 由于有两个地方需要生成字符串（JSON 字符串和对象类型），所以先实现 `lept_stringify_string()`。注意，字符串的语法比较复杂，一些字符必须转义，其他少于 `0x20` 的字符需要转义为 `\u00xx` 形式。 -2. 直接在 `lept_stringify_value()` 的 `switch` 内实现 JSON 数组和对象类型的生成。这些实现里都会递归调用 `lept_stringify_value()` 。 +2. 直接在 `lept_stringify_value()` 的 `switch` 内实现 JSON 数组和对象类型的生成。这些实现里都会递归调用 `lept_stringify_value()`。 3. 在你的 `lept_stringify_string()` 是否使用了多次 `PUTC()`？如果是，它每次输出一个字符时，都要检测缓冲区是否有足够空间（不够时需扩展）。能否优化这部分的性能？这种优化有什么代价么？ diff --git a/tutorial07_answer/tutorial07_answer.md b/tutorial07_answer/tutorial07_answer.md index b10ea1e3..724779b5 100644 --- a/tutorial07_answer/tutorial07_answer.md +++ b/tutorial07_answer/tutorial07_answer.md @@ -46,7 +46,7 @@ static void lept_stringify_value(lept_context* c, const lept_value* v) { } ~~~ -注意到，十六进位输出的字母可以用大写或小写，我们这里选择了大写，所以 roundstrip 测试时也用大写。但这个并不是必然的，输出小写（用 `"\\u%04x"`）也可以。 +注意到，十六进位输出的字母可以用大写或小写，我们这里选择了大写，所以 roundtrip 测试时也用大写。但这个并不是必然的，输出小写（用 `"\\u%04x"`）也可以。 ## 2. 生成数组和对象 diff --git a/tutorial08/tutorial08.md b/tutorial08/tutorial08.md index 60874345..49c5a8d7 100644 --- a/tutorial08/tutorial08.md +++ b/tutorial08/tutorial08.md @@ -5,6 +5,15 @@ 本文是[《从零开始的 JSON 库教程》](https://zhuanlan.zhihu.com/json-tutorial)的第八个单元。代码位于 [json-tutorial/tutorial08](https://github.com/miloyip/json-tutorial/blob/master/tutorial08)。 +本单元内容： + +1. [对象键值查询](#1-对象键值查询) +2. [相等比较](#2-相等比较) +3. [复制、移动与交换](#3-复制移动与交换) +4. [动态数组](#4-动态数组) +5. [动态对象](#5-动态对象) +6. [总结与练习](#6-总结与练习) + ## 1. 对象键值查询 我们在第六个单元实现了 JSON 对象的数据结构，它仅为一个 `lept_value` 的数组：