iw7-mod/deps/rapidjson/doc/tutorial.zh-cn.md
2024-08-13 05:15:34 -04:00

21 KiB
Raw Blame History

教程

本教程简介文件对象模型Document Object Model, DOMAPI。

用法一览 中所示,可以解析一个 JSON 至 DOM然后就可以轻松查询及修改 DOM并最终转换回 JSON。

[TOC]

Value 及 Document

每个 JSON 值都储存为 Value 类,而 Document 类则表示整个 DOM它存储了一个 DOM 树的根 Value。RapidJSON 的所有公开类型及函数都在 rapidjson 命名空间中。

查询 Value

在本节中,我们会使用到 example/tutorial/tutorial.cpp 中的代码片段。

假设我们用 C 语言的字符串储存一个 JSONconst char* json

{
    "hello": "world",
    "t": true ,
    "f": false,
    "n": null,
    "i": 123,
    "pi": 3.1416,
    "a": [1, 2, 3, 4]
}

把它解析至一个 Document

#include "rapidjson/document.h"

using namespace rapidjson;

// ...
Document document;
document.Parse(json);

那么现在该 JSON 就会被解析至 document 中,成为一棵 *DOM 树 *:

教程中的 DOM

自从 RFC 7159 作出更新,合法 JSON 文件的根可以是任何类型的 JSON 值。而在较早的 RFC 4627 中,根值只允许是 Object 或 Array。而在上述例子中根是一个 Object。

assert(document.IsObject());

让我们查询一下根 Object 中有没有 "hello" 成员。由于一个 Value 可包含不同类型的值,我们可能需要验证它的类型,并使用合适的 API 去获取其值。在此例中,"hello" 成员关联到一个 JSON String。

assert(document.HasMember("hello"));
assert(document["hello"].IsString());
printf("hello = %s\n", document["hello"].GetString());
world

JSON True/False 值是以 bool 表示的。

assert(document["t"].IsBool());
printf("t = %s\n", document["t"].GetBool() ? "true" : "false");
true

JSON Null 值可用 IsNull() 查询。

printf("n = %s\n", document["n"].IsNull() ? "null" : "?");
null

JSON Number 类型表示所有数值。然而C++ 需要使用更专门的类型。

assert(document["i"].IsNumber());

// 在此情况下IsUint()/IsInt64()/IsUint64() 也会返回 true
assert(document["i"].IsInt());          
printf("i = %d\n", document["i"].GetInt());
// 另一种用法: (int)document["i"]

assert(document["pi"].IsNumber());
assert(document["pi"].IsDouble());
printf("pi = %g\n", document["pi"].GetDouble());
i = 123
pi = 3.1416

JSON Array 包含一些元素。

// 使用引用来连续访问,方便之余还更高效。
const Value& a = document["a"];
assert(a.IsArray());
for (SizeType i = 0; i < a.Size(); i++) // 使用 SizeType 而不是 size_t
        printf("a[%d] = %d\n", i, a[i].GetInt());
a[0] = 1
a[1] = 2
a[2] = 3
a[3] = 4

注意RapidJSON 并不自动转换各种 JSON 类型。例如,对一个 String 的 Value 调用 GetInt() 是非法的。在调试模式下,它会被断言失败。在发布模式下,其行为是未定义的。

以下将会讨论有关查询各类型的细节。

查询 Array

缺省情况下,SizeTypeunsigned 的 typedef。在多数系统中Array 最多能存储 2^32-1 个元素。

你可以用整数字面量访问元素,如 a[0]a[1]a[2]

Array 与 std::vector 相似,除了使用索引,也可使用迭代器来访问所有元素。

for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)
    printf("%d ", itr->GetInt());

还有一些熟悉的查询函数:

  • SizeType Capacity() const
  • bool Empty() const

范围 for 循环 (v1.1.0 中的新功能)

当使用 C++11 功能时,你可使用范围 for 循环去访问 Array 内的所有元素。

for (auto& v : a.GetArray())
    printf("%d ", v.GetInt());

查询 Object

和 Array 相似,我们可以用迭代器去访问所有 Object 成员:

static const char* kTypeNames[] = 
    { "Null", "False", "True", "Object", "Array", "String", "Number" };

for (Value::ConstMemberIterator itr = document.MemberBegin();
    itr != document.MemberEnd(); ++itr)
{
    printf("Type of member %s is %s\n",
        itr->name.GetString(), kTypeNames[itr->value.GetType()]);
}
Type of member hello is String
Type of member t is True
Type of member f is False
Type of member n is Null
Type of member i is Number
Type of member pi is Number
Type of member a is Array

注意,当 operator[](const char*) 找不到成员,它会断言失败。

若我们不确定一个成员是否存在,便需要在调用 operator[](const char*) 前先调用 HasMember()。然而,这会导致两次查找。更好的做法是调用 FindMember(),它能同时检查成员是否存在并返回它的 Value

Value::ConstMemberIterator itr = document.FindMember("hello");
if (itr != document.MemberEnd())
    printf("%s\n", itr->value.GetString());

范围 for 循环 (v1.1.0 中的新功能)

当使用 C++11 功能时,你可使用范围 for 循环去访问 Object 内的所有成员。

for (auto& m : document.GetObject())
    printf("Type of member %s is %s\n",
        m.name.GetString(), kTypeNames[m.value.GetType()]);

查询 Number

JSON 只提供一种数值类型──Number。数字可以是整数或实数。RFC 4627 规定数字的范围由解析器指定。

由于 C++ 提供多种整数及浮点数类型DOM 尝试尽量提供最广的范围及良好性能。

当解析一个 Number 时, 它会被存储在 DOM 之中,成为下列其中一个类型:

类型 描述
unsigned 32 位无号整数
int 32 位有号整数
uint64_t 64 位无号整数
int64_t 64 位有号整数
double 64 位双精度浮点数

当查询一个 Number 时, 你可以检查该数字是否能以目标类型来提取:

查检 提取
bool IsNumber() 不适用
bool IsUint() unsigned GetUint()
bool IsInt() int GetInt()
bool IsUint64() uint64_t GetUint64()
bool IsInt64() int64_t GetInt64()
bool IsDouble() double GetDouble()

注意,一个整数可能用几种类型来提取,而无需转换。例如,一个名为 x 的 Value 包含 123那么 x.IsInt() == x.IsUint() == x.IsInt64() == x.IsUint64() == true。但如果一个名为 y 的 Value 包含 -3000000000那么仅会令 x.IsInt64() == true

当要提取 Number 类型,GetDouble() 是会把内部整数的表示转换成 double。注意 intunsigned 可以安全地转换至 double,但 int64_tuint64_t 可能会丧失精度(因为 double 的尾数只有 52 位)。

查询 String

除了 GetString()Value 类也有一个 GetStringLength()。这里会解释个中原因。

根据 RFC 4627JSON String 可包含 Unicode 字符 U+0000,在 JSON 中会表示为 "\u0000"。问题是C/C++ 通常使用空字符结尾字符串null-terminated string这种字符串把 ``\0'` 作为结束符号。

为了符合 RFC 4627RapidJSON 支持包含 U+0000 的 String。若你需要处理这些 String便可使用 GetStringLength() 去获得正确的字符串长度。

例如,当解析以下的 JSON 至 Document d 之后:

{ "s" :  "a\u0000b" }

"a\u0000b" 值的正确长度应该是 3。但 strlen() 会返回 1。

GetStringLength() 也可以提高性能,因为用户可能需要调用 strlen() 去分配缓冲。

此外,std::string 也支持这个构造函数:

string(const char* s, size_t count);

此构造函数接受字符串长度作为参数。它支持在字符串中存储空字符,也应该会有更好的性能。

比较两个 Value

你可使用 ==!= 去比较两个 Value。当且仅当两个 Value 的类型及内容相同,它们才当作相等。你也可以比较 Value 和它的原生类型值。以下是一个例子。

if (document["hello"] == document["n"]) /*...*/;    // 比较两个值
if (document["hello"] == "world") /*...*/;          // 与字符串字面量作比较
if (document["i"] != 123) /*...*/;                  // 与整数作比较
if (document["pi"] != 3.14) /*...*/;                // 与 double 作比较

ArrayObject 顺序以它们的元素/成员作比较。当且仅当它们的整个子树相等,它们才当作相等。

注意,现时若一个 Object 含有重复命名的成员,它与任何 Object 作比较都总会返回 false

创建/修改值

有多种方法去创建值。 当一个 DOM 树被创建或修改后,可使用 Writer 再次存储为 JSON。

改变 Value 类型

当使用默认构造函数创建一个 Value 或 Document它的类型便会是 Null。要改变其类型需调用 SetXXX() 或赋值操作,例如:

Document d; // Null
d.SetObject();

Value v;    // Null
v.SetInt(10);
v = 10;     // 简写,和上面的相同

构造函数的各个重载

几个类型也有重载构造函数:

Value b(true);    // 调用 Value(bool)
Value i(-123);    // 调用 Value(int)
Value u(123u);    // 调用 Value(unsigned)
Value d(1.5);     // 调用 Value(double)

要重建空 Object 或 Array可在默认构造函数后使用 SetObject()/SetArray(),或一次性使用 Value(Type)

Value o(kObjectType);
Value a(kArrayType);

转移语义Move Semantics

在设计 RapidJSON 时有一个非常特别的决定,就是 Value 赋值并不是把来源 Value 复制至目的 Value而是把来源 Value 转移move至目的 Value。例如

Value a(123);
Value b(456);
b = a;         // a 变成 Nullb 变成数字 123。

使用移动语义赋值。

为什么?此语义有何优点?

最简单的答案就是性能。对于固定大小的 JSON 类型Number、True、False、Null复制它们是简单快捷。然而对于可变大小的 JSON 类型String、Array、Object复制它们会产生大量开销而且这些开销常常不被察觉。尤其是当我们需要创建临时 Object把它复制至另一变量然后再析构它。

例如,若使用正常 * 复制 * 语义:

Value o(kObjectType);
{
    Value contacts(kArrayType);
    // 把元素加进 contacts 数组。
    // ...
    o.AddMember("contacts", contacts, d.GetAllocator());  // 深度复制 contacts (可能有大量内存分配)
    // 析构 contacts。
}

复制语义产生大量的复制操作。

那个 o Object 需要分配一个和 contacts 相同大小的缓冲区,对 conacts 做深度复制,并最终要析构 contacts。这样会产生大量无必要的内存分配释放以及内存复制。

有一些方案可避免实质地复制这些数据例如引用计数reference counting、垃圾回收garbage collection, GC

为了使 RapidJSON 简单及快速,我们选择了对赋值采用 * 转移 * 语义。这方法与 std::auto_ptr 相似,都是在赋值时转移拥有权。转移快得多简单得多,只需要析构原来的 Value把来源 memcpy() 至目标,最后把来源设置为 Null 类型。

因此,使用转移语义后,上面的例子变成:

Value o(kObjectType);
{
    Value contacts(kArrayType);
    // adding elements to contacts array.
    o.AddMember("contacts", contacts, d.GetAllocator());  // 只需 memcpy() contacts 本身至新成员的 Value16 字节)
    // contacts 在这里变成 Null。它的析构是平凡的。
}

转移语义不需复制。

在 C++11 中这称为转移赋值操作move assignment operator。由于 RapidJSON 支持 C++03它在赋值操作采用转移语义其它修改型函数如 AddMember(), PushBack() 也采用转移语义。

转移语义及临时值

有时候,我们想直接构造一个 Value 并传递给一个“转移”函数(如 PushBack()AddMember())。由于临时对象是不能转换为正常的 Value 引用,我们加入了一个方便的 Move() 函数:

Value a(kArrayType);
Document::AllocatorType& allocator = document.GetAllocator();
// a.PushBack(Value(42), allocator);       // 不能通过编译
a.PushBack(Value().SetInt(42), allocator); // fluent API
a.PushBack(Value(42).Move(), allocator);   // 和上一行相同

创建 String

RapidJSON 提供两个 String 的存储策略。

  1. copy-string: 分配缓冲区,然后把来源数据复制至它。
  2. const-string: 简单地储存字符串的指针。

Copy-string 总是安全的因为它拥有数据的克隆。Const-string 可用于存储字符串字面量,以及用于在 DOM 一节中将会提到的 in-situ 解析中。

为了让用户自定义内存分配方式当一个操作可能需要内存分配时RapidJSON 要求用户传递一个 allocator 实例作为 API 参数。此设计避免了在每个 Value 存储 allocator或 document的指针。

因此,当我们把一个 copy-string 赋值时, 调用含有 allocator 的 SetString() 重载函数:

Document document;
Value author;
char buffer[10];
int len = sprintf(buffer, "%s %s", "Milo", "Yip"); // 动态创建的字符串。
author.SetString(buffer, len, document.GetAllocator());
memset(buffer, 0, sizeof(buffer));
// 清空 buffer 后 author.GetString() 仍然包含 "Milo Yip"

在此例子中,我们使用 Document 实例的 allocator。这是使用 RapidJSON 时常用的惯用法。但你也可以用其他 allocator 实例。

另外,上面的 SetString() 需要长度参数。这个 API 能处理含有空字符的字符串。另一个 SetString() 重载函数没有长度参数,它假设输入是空字符结尾的,并会调用类似 strlen() 的函数去获取长度。

最后,对于字符串字面量或有安全生命周期的字符串,可以使用 const-string 版本的 SetString(),它没有 allocator 参数。对于字符串字面量(或字符数组常量),只需简单地传递字面量,又安全又高效:

Value s;
s.SetString("rapidjson");    // 可包含空字符,长度在编译期推导
s = "rapidjson";             // 上行的缩写

对于字符指针RapidJSON 需要作一个标记,代表它不复制也是安全的。可以使用 StringRef 函数:

const char * cstr = getenv("USER");
size_t cstr_len = ...;                 // 如果有长度
Value s;
// s.SetString(cstr);                  // 这不能通过编译
s.SetString(StringRef(cstr));          // 可以,假设它的生命周期安全,并且是以空字符结尾的
s = StringRef(cstr);                   // 上行的缩写
s.SetString(StringRef(cstr, cstr_len));// 更快,可处理空字符
s = StringRef(cstr, cstr_len);         // 上行的缩写

修改 Array

Array 类型的 Value 提供与 std::vector 相似的 API。

  • Clear()
  • Reserve(SizeType, Allocator&)
  • Value& PushBack(Value&, Allocator&)
  • template <typename T> GenericValue& PushBack(T, Allocator&)
  • Value& PopBack()
  • ValueIterator Erase(ConstValueIterator pos)
  • ValueIterator Erase(ConstValueIterator first, ConstValueIterator last)

注意,Reserve(...)PushBack(...) 可能会为数组元素分配内存,所以需要一个 allocator。

以下是 PushBack() 的例子:

Value a(kArrayType);
Document::AllocatorType& allocator = document.GetAllocator();

for (int i = 5; i <= 10; i++)
    a.PushBack(i, allocator);   // 可能需要调用 realloc() 所以需要 allocator

// 流畅接口Fluent interface
a.PushBack("Lua", allocator).PushBack("Mio", allocator);

与 STL 不一样的是,PushBack()/PopBack() 返回 Array 本身的引用。这称为流畅接口(fluent interface)。

如果你想在 Array 中加入一个非常量字符串,或是一个没有足够生命周期的字符串(见 Create String),你需要使用 copy-string API 去创建一个 String。为了避免加入中间变量可以就地使用一个 临时值

// 就地 Value 参数
contact.PushBack(Value("copy", document.GetAllocator()).Move(), // copy string
                 document.GetAllocator());

// 显式 Value 参数
Value val("key", document.GetAllocator()); // copy string
contact.PushBack(val, document.GetAllocator());

修改 Object

Object 是键值对的集合。每个键必须为 String。要修改 Object方法是增加或移除成员。以下的 API 用来增加成员:

  • Value& AddMember(Value&, Value&, Allocator& allocator)
  • Value& AddMember(StringRefType, Value&, Allocator&)
  • template <typename T> Value& AddMember(StringRefType, T value, Allocator&)

以下是一个例子。

Value contact(kObject);
contact.AddMember("name", "Milo", document.GetAllocator());
contact.AddMember("married", true, document.GetAllocator());

使用 StringRefType 作为 name 参数的重载版本与字符串的 SetString 的接口相似。 这些重载是为了避免复制 name 字符串,因为 JSON object 中经常会使用常数键名。

如果你需要从非常数字符串或生命周期不足的字符串创建键名(见 创建 String),你需要使用 copy-string API。为了避免中间变量可以就地使用 临时值

// 就地 Value 参数
contact.AddMember(Value("copy", document.GetAllocator()).Move(), // copy string
                  Value().Move(),                                // null value
                  document.GetAllocator());

// 显式参数
Value key("key", document.GetAllocator()); // copy string name
Value val(42);                             // 某 Value
contact.AddMember(key, val, document.GetAllocator());

移除成员有几个选择:

  • bool RemoveMember(const Ch* name):使用键名来移除成员(线性时间复杂度)。
  • bool RemoveMember(const Value& name):除了 name 是一个 Value和上一行相同。
  • MemberIterator RemoveMember(MemberIterator)使用迭代器移除成员_ 常数 _ 时间复杂度)。
  • MemberIterator EraseMember(MemberIterator):和上行相似但维持成员次序(线性时间复杂度)。
  • MemberIterator EraseMember(MemberIterator first, MemberIterator last):移除一个范围内的成员,维持次序(线性时间复杂度)。

MemberIterator RemoveMember(MemberIterator) 使用了“转移最后”手法来达成常数时间复杂度。基本上就是析构迭代器位置的成员,然后把最后的成员转移至迭代器位置。因此,成员的次序会被改变。

深复制 Value

若我们真的要复制一个 DOM 树,我们可使用两个 APIs 作深复制:含 allocator 的构造函数及 CopyFrom()

Document d;
Document::AllocatorType& a = d.GetAllocator();
Value v1("foo");
// Value v2(v1); // 不容许

Value v2(v1, a);                      // 制造一个克隆
assert(v1.IsString());                // v1 不变
d.SetArray().PushBack(v1, a).PushBack(v2, a);
assert(v1.IsNull() && v2.IsNull());   // 两个都转移动 d

v2.CopyFrom(d, a);                    // 把整个 document 复制至 v2
assert(d.IsArray() && d.Size() == 2); // d 不变
v1.SetObject().AddMember("array", v2, a);
d.PushBack(v1, a);

交换 Value

RapidJSON 也提供 Swap()

Value a(123);
Value b("Hello");
a.Swap(b);
assert(a.IsString());
assert(b.IsInt());

无论两棵 DOM 树有多复杂,交换是很快的(常数时间)。

下一部分

本教程展示了如何询查及修改 DOM 树。RapidJSON 还有一个重要概念:

  1. 是读写 JSON 的通道。流可以是内存字符串、文件流等。用户也可以自定义流。
  2. 编码 定义在流或内存中使用的字符编码。RapidJSON 也在内部提供 Unicode 转换及校验功能。
  3. DOM 的基本功能已在本教程里介绍。还有更高级的功能,如原位(in situ)解析、其他解析选项及高级用法。
  4. SAX 是 RapidJSON 解析/生成功能的基础。学习使用 Reader/Writer 去实现更高性能的应用程序。也可以使用 PrettyWriter 去格式化 JSON。
  5. 性能 展示一些我们做的及第三方的性能测试。
  6. 技术内幕 讲述一些 RapidJSON 内部的设计及技术。

你也可以参考 常见问题、API 文档、例子及单元测试。