| 1 |
# 教程 |
| 2 |
|
| 3 |
本教程简介文件对象模型(Document Object Model, DOM)API。 |
| 4 |
|
| 5 |
如 [用法一览](../readme.zh-cn.md#用法一览) 中所示,可以解析一个 JSON 至 DOM,然后就可以轻松查询及修改 DOM,并最终转换回 JSON。 |
| 6 |
|
| 7 |
[TOC] |
| 8 |
|
| 9 |
# Value 及 Document {#ValueDocument} |
| 10 |
|
| 11 |
每个 JSON 值都储存为 `Value` 类,而 `Document` 类则表示整个 DOM,它存储了一个 DOM 树的根 `Value`。RapidJSON 的所有公开类型及函数都在 `rapidjson` 命名空间中。 |
| 12 |
|
| 13 |
# 查询 Value {#QueryValue} |
| 14 |
|
| 15 |
在本节中,我们会使用到 `example/tutorial/tutorial.cpp` 中的代码片段。 |
| 16 |
|
| 17 |
假设我们用 C 语言的字符串储存一个 JSON(`const char* json`): |
| 18 |
~~~~~~~~~~js |
| 19 |
{ |
| 20 |
"hello": "world", |
| 21 |
"t": true , |
| 22 |
"f": false, |
| 23 |
"n": null, |
| 24 |
"i": 123, |
| 25 |
"pi": 3.1416, |
| 26 |
"a": [1, 2, 3, 4] |
| 27 |
} |
| 28 |
~~~~~~~~~~ |
| 29 |
|
| 30 |
把它解析至一个 `Document`: |
| 31 |
~~~~~~~~~~cpp |
| 32 |
#include "rapidjson/document.h" |
| 33 |
|
| 34 |
using namespace rapidjson; |
| 35 |
|
| 36 |
// ... |
| 37 |
Document document; |
| 38 |
document.Parse(json); |
| 39 |
~~~~~~~~~~ |
| 40 |
|
| 41 |
那么现在该 JSON 就会被解析至 `document` 中,成为一棵 *DOM 树 *: |
| 42 |
|
| 43 |
 |
| 44 |
|
| 45 |
自从 RFC 7159 作出更新,合法 JSON 文件的根可以是任何类型的 JSON 值。而在较早的 RFC 4627 中,根值只允许是 Object 或 Array。而在上述例子中,根是一个 Object。 |
| 46 |
~~~~~~~~~~cpp |
| 47 |
assert(document.IsObject()); |
| 48 |
~~~~~~~~~~ |
| 49 |
|
| 50 |
让我们查询一下根 Object 中有没有 `"hello"` 成员。由于一个 `Value` 可包含不同类型的值,我们可能需要验证它的类型,并使用合适的 API 去获取其值。在此例中,`"hello"` 成员关联到一个 JSON String。 |
| 51 |
~~~~~~~~~~cpp |
| 52 |
assert(document.HasMember("hello")); |
| 53 |
assert(document["hello"].IsString()); |
| 54 |
printf("hello = %s\n", document["hello"].GetString()); |
| 55 |
~~~~~~~~~~ |
| 56 |
|
| 57 |
~~~~~~~~~~ |
| 58 |
world |
| 59 |
~~~~~~~~~~ |
| 60 |
|
| 61 |
JSON True/False 值是以 `bool` 表示的。 |
| 62 |
~~~~~~~~~~cpp |
| 63 |
assert(document["t"].IsBool()); |
| 64 |
printf("t = %s\n", document["t"].GetBool() ? "true" : "false"); |
| 65 |
~~~~~~~~~~ |
| 66 |
|
| 67 |
~~~~~~~~~~ |
| 68 |
true |
| 69 |
~~~~~~~~~~ |
| 70 |
|
| 71 |
JSON Null 值可用 `IsNull()` 查询。 |
| 72 |
~~~~~~~~~~cpp |
| 73 |
printf("n = %s\n", document["n"].IsNull() ? "null" : "?"); |
| 74 |
~~~~~~~~~~ |
| 75 |
|
| 76 |
~~~~~~~~~~ |
| 77 |
null |
| 78 |
~~~~~~~~~~ |
| 79 |
|
| 80 |
JSON Number 类型表示所有数值。然而,C++ 需要使用更专门的类型。 |
| 81 |
|
| 82 |
~~~~~~~~~~cpp |
| 83 |
assert(document["i"].IsNumber()); |
| 84 |
|
| 85 |
// 在此情况下,IsUint()/IsInt64()/IsUint64() 也会返回 true |
| 86 |
assert(document["i"].IsInt()); |
| 87 |
printf("i = %d\n", document["i"].GetInt()); |
| 88 |
// 另一种用法: (int)document["i"] |
| 89 |
|
| 90 |
assert(document["pi"].IsNumber()); |
| 91 |
assert(document["pi"].IsDouble()); |
| 92 |
printf("pi = %g\n", document["pi"].GetDouble()); |
| 93 |
~~~~~~~~~~ |
| 94 |
|
| 95 |
~~~~~~~~~~ |
| 96 |
i = 123 |
| 97 |
pi = 3.1416 |
| 98 |
~~~~~~~~~~ |
| 99 |
|
| 100 |
JSON Array 包含一些元素。 |
| 101 |
~~~~~~~~~~cpp |
| 102 |
// 使用引用来连续访问,方便之余还更高效。 |
| 103 |
const Value& a = document["a"]; |
| 104 |
assert(a.IsArray()); |
| 105 |
for (SizeType i = 0; i < a.Size(); i++) // 使用 SizeType 而不是 size_t |
| 106 |
printf("a[%d] = %d\n", i, a[i].GetInt()); |
| 107 |
~~~~~~~~~~ |
| 108 |
|
| 109 |
~~~~~~~~~~ |
| 110 |
a[0] = 1 |
| 111 |
a[1] = 2 |
| 112 |
a[2] = 3 |
| 113 |
a[3] = 4 |
| 114 |
~~~~~~~~~~ |
| 115 |
|
| 116 |
注意,RapidJSON 并不自动转换各种 JSON 类型。例如,对一个 String 的 Value 调用 `GetInt()` 是非法的。在调试模式下,它会被断言失败。在发布模式下,其行为是未定义的。 |
| 117 |
|
| 118 |
以下将会讨论有关查询各类型的细节。 |
| 119 |
|
| 120 |
## 查询 Array {#QueryArray} |
| 121 |
|
| 122 |
缺省情况下,`SizeType` 是 `unsigned` 的 typedef。在多数系统中,Array 最多能存储 2^32-1 个元素。 |
| 123 |
|
| 124 |
你可以用整数字面量访问元素,如 `a[0]`、`a[1]`、`a[2]`。 |
| 125 |
|
| 126 |
Array 与 `std::vector` 相似,除了使用索引,也可使用迭代器来访问所有元素。 |
| 127 |
~~~~~~~~~~cpp |
| 128 |
for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr) |
| 129 |
printf("%d ", itr->GetInt()); |
| 130 |
~~~~~~~~~~ |
| 131 |
|
| 132 |
还有一些熟悉的查询函数: |
| 133 |
* `SizeType Capacity() const` |
| 134 |
* `bool Empty() const` |
| 135 |
|
| 136 |
### 范围 for 循环 (v1.1.0 中的新功能) |
| 137 |
|
| 138 |
当使用 C++11 功能时,你可使用范围 for 循环去访问 Array 内的所有元素。 |
| 139 |
|
| 140 |
~~~~~~~~~~cpp |
| 141 |
for (auto& v : a.GetArray()) |
| 142 |
printf("%d ", v.GetInt()); |
| 143 |
~~~~~~~~~~ |
| 144 |
|
| 145 |
## 查询 Object {#QueryObject} |
| 146 |
|
| 147 |
和 Array 相似,我们可以用迭代器去访问所有 Object 成员: |
| 148 |
|
| 149 |
~~~~~~~~~~cpp |
| 150 |
static const char* kTypeNames[] = |
| 151 |
{ "Null", "False", "True", "Object", "Array", "String", "Number" }; |
| 152 |
|
| 153 |
for (Value::ConstMemberIterator itr = document.MemberBegin(); |
| 154 |
itr != document.MemberEnd(); ++itr) |
| 155 |
{ |
| 156 |
printf("Type of member %s is %s\n", |
| 157 |
itr->name.GetString(), kTypeNames[itr->value.GetType()]); |
| 158 |
} |
| 159 |
~~~~~~~~~~ |
| 160 |
|
| 161 |
~~~~~~~~~~ |
| 162 |
Type of member hello is String |
| 163 |
Type of member t is True |
| 164 |
Type of member f is False |
| 165 |
Type of member n is Null |
| 166 |
Type of member i is Number |
| 167 |
Type of member pi is Number |
| 168 |
Type of member a is Array |
| 169 |
~~~~~~~~~~ |
| 170 |
|
| 171 |
注意,当 `operator[](const char*)` 找不到成员,它会断言失败。 |
| 172 |
|
| 173 |
若我们不确定一个成员是否存在,便需要在调用 `operator[](const char*)` 前先调用 `HasMember()`。然而,这会导致两次查找。更好的做法是调用 `FindMember()`,它能同时检查成员是否存在并返回它的 Value: |
| 174 |
|
| 175 |
~~~~~~~~~~cpp |
| 176 |
Value::ConstMemberIterator itr = document.FindMember("hello"); |
| 177 |
if (itr != document.MemberEnd()) |
| 178 |
printf("%s\n", itr->value.GetString()); |
| 179 |
~~~~~~~~~~ |
| 180 |
|
| 181 |
### 范围 for 循环 (v1.1.0 中的新功能) |
| 182 |
|
| 183 |
当使用 C++11 功能时,你可使用范围 for 循环去访问 Object 内的所有成员。 |
| 184 |
|
| 185 |
~~~~~~~~~~cpp |
| 186 |
for (auto& m : document.GetObject()) |
| 187 |
printf("Type of member %s is %s\n", |
| 188 |
m.name.GetString(), kTypeNames[m.value.GetType()]); |
| 189 |
~~~~~~~~~~ |
| 190 |
|
| 191 |
## 查询 Number {#QueryNumber} |
| 192 |
|
| 193 |
JSON 只提供一种数值类型──Number。数字可以是整数或实数。RFC 4627 规定数字的范围由解析器指定。 |
| 194 |
|
| 195 |
由于 C++ 提供多种整数及浮点数类型,DOM 尝试尽量提供最广的范围及良好性能。 |
| 196 |
|
| 197 |
当解析一个 Number 时, 它会被存储在 DOM 之中,成为下列其中一个类型: |
| 198 |
|
| 199 |
类型 | 描述 |
| 200 |
-----------|--------------------------------------- |
| 201 |
`unsigned` | 32 位无号整数 |
| 202 |
`int` | 32 位有号整数 |
| 203 |
`uint64_t` | 64 位无号整数 |
| 204 |
`int64_t` | 64 位有号整数 |
| 205 |
`double` | 64 位双精度浮点数 |
| 206 |
|
| 207 |
当查询一个 Number 时, 你可以检查该数字是否能以目标类型来提取: |
| 208 |
|
| 209 |
查检 | 提取 |
| 210 |
------------------|--------------------- |
| 211 |
`bool IsNumber()` | 不适用 |
| 212 |
`bool IsUint()` | `unsigned GetUint()` |
| 213 |
`bool IsInt()` | `int GetInt()` |
| 214 |
`bool IsUint64()` | `uint64_t GetUint64()` |
| 215 |
`bool IsInt64()` | `int64_t GetInt64()` |
| 216 |
`bool IsDouble()` | `double GetDouble()` |
| 217 |
|
| 218 |
注意,一个整数可能用几种类型来提取,而无需转换。例如,一个名为 `x` 的 Value 包含 123,那么 `x.IsInt() == x.IsUint() == x.IsInt64() == x.IsUint64() == true`。但如果一个名为 `y` 的 Value 包含 -3000000000,那么仅会令 `x.IsInt64() == true`。 |
| 219 |
|
| 220 |
当要提取 Number 类型,`GetDouble()` 是会把内部整数的表示转换成 `double`。注意 `int` 和 `unsigned` 可以安全地转换至 `double`,但 `int64_t` 及 `uint64_t` 可能会丧失精度(因为 `double` 的尾数只有 52 位)。 |
| 221 |
|
| 222 |
## 查询 String {#QueryString} |
| 223 |
|
| 224 |
除了 `GetString()`,`Value` 类也有一个 `GetStringLength()`。这里会解释个中原因。 |
| 225 |
|
| 226 |
根据 RFC 4627,JSON String 可包含 Unicode 字符 `U+0000`,在 JSON 中会表示为 `"\u0000"`。问题是,C/C++ 通常使用空字符结尾字符串(null-terminated string),这种字符串把 ``\0'` 作为结束符号。 |
| 227 |
|
| 228 |
为了符合 RFC 4627,RapidJSON 支持包含 `U+0000` 的 String。若你需要处理这些 String,便可使用 `GetStringLength()` 去获得正确的字符串长度。 |
| 229 |
|
| 230 |
例如,当解析以下的 JSON 至 `Document d` 之后: |
| 231 |
|
| 232 |
~~~~~~~~~~js |
| 233 |
{ "s" : "a\u0000b" } |
| 234 |
~~~~~~~~~~ |
| 235 |
`"a\u0000b"` 值的正确长度应该是 3。但 `strlen()` 会返回 1。 |
| 236 |
|
| 237 |
`GetStringLength()` 也可以提高性能,因为用户可能需要调用 `strlen()` 去分配缓冲。 |
| 238 |
|
| 239 |
此外,`std::string` 也支持这个构造函数: |
| 240 |
|
| 241 |
~~~~~~~~~~cpp |
| 242 |
string(const char* s, size_t count); |
| 243 |
~~~~~~~~~~ |
| 244 |
|
| 245 |
此构造函数接受字符串长度作为参数。它支持在字符串中存储空字符,也应该会有更好的性能。 |
| 246 |
|
| 247 |
## 比较两个 Value |
| 248 |
|
| 249 |
你可使用 `==` 及 `!=` 去比较两个 Value。当且仅当两个 Value 的类型及内容相同,它们才当作相等。你也可以比较 Value 和它的原生类型值。以下是一个例子。 |
| 250 |
|
| 251 |
~~~~~~~~~~cpp |
| 252 |
if (document["hello"] == document["n"]) /*...*/; // 比较两个值 |
| 253 |
if (document["hello"] == "world") /*...*/; // 与字符串字面量作比较 |
| 254 |
if (document["i"] != 123) /*...*/; // 与整数作比较 |
| 255 |
if (document["pi"] != 3.14) /*...*/; // 与 double 作比较 |
| 256 |
~~~~~~~~~~ |
| 257 |
|
| 258 |
Array/Object 顺序以它们的元素/成员作比较。当且仅当它们的整个子树相等,它们才当作相等。 |
| 259 |
|
| 260 |
注意,现时若一个 Object 含有重复命名的成员,它与任何 Object 作比较都总会返回 `false`。 |
| 261 |
|
| 262 |
# 创建/修改值 {#CreateModifyValues} |
| 263 |
|
| 264 |
有多种方法去创建值。 当一个 DOM 树被创建或修改后,可使用 `Writer` 再次存储为 JSON。 |
| 265 |
|
| 266 |
## 改变 Value 类型 {#ChangeValueType} |
| 267 |
当使用默认构造函数创建一个 Value 或 Document,它的类型便会是 Null。要改变其类型,需调用 `SetXXX()` 或赋值操作,例如: |
| 268 |
|
| 269 |
~~~~~~~~~~cpp |
| 270 |
Document d; // Null |
| 271 |
d.SetObject(); |
| 272 |
|
| 273 |
Value v; // Null |
| 274 |
v.SetInt(10); |
| 275 |
v = 10; // 简写,和上面的相同 |
| 276 |
~~~~~~~~~~ |
| 277 |
|
| 278 |
### 构造函数的各个重载 |
| 279 |
几个类型也有重载构造函数: |
| 280 |
|
| 281 |
~~~~~~~~~~cpp |
| 282 |
Value b(true); // 调用 Value(bool) |
| 283 |
Value i(-123); // 调用 Value(int) |
| 284 |
Value u(123u); // 调用 Value(unsigned) |
| 285 |
Value d(1.5); // 调用 Value(double) |
| 286 |
~~~~~~~~~~ |
| 287 |
|
| 288 |
要重建空 Object 或 Array,可在默认构造函数后使用 `SetObject()`/`SetArray()`,或一次性使用 `Value(Type)`: |
| 289 |
|
| 290 |
~~~~~~~~~~cpp |
| 291 |
Value o(kObjectType); |
| 292 |
Value a(kArrayType); |
| 293 |
~~~~~~~~~~ |
| 294 |
|
| 295 |
## 转移语义(Move Semantics) {#MoveSemantics} |
| 296 |
|
| 297 |
在设计 RapidJSON 时有一个非常特别的决定,就是 Value 赋值并不是把来源 Value 复制至目的 Value,而是把来源 Value 转移(move)至目的 Value。例如: |
| 298 |
|
| 299 |
~~~~~~~~~~cpp |
| 300 |
Value a(123); |
| 301 |
Value b(456); |
| 302 |
b = a; // a 变成 Null,b 变成数字 123。 |
| 303 |
~~~~~~~~~~ |
| 304 |
|
| 305 |
 |
| 306 |
|
| 307 |
为什么?此语义有何优点? |
| 308 |
|
| 309 |
最简单的答案就是性能。对于固定大小的 JSON 类型(Number、True、False、Null),复制它们是简单快捷。然而,对于可变大小的 JSON 类型(String、Array、Object),复制它们会产生大量开销,而且这些开销常常不被察觉。尤其是当我们需要创建临时 Object,把它复制至另一变量,然后再析构它。 |
| 310 |
|
| 311 |
例如,若使用正常 * 复制 * 语义: |
| 312 |
|
| 313 |
~~~~~~~~~~cpp |
| 314 |
Value o(kObjectType); |
| 315 |
{ |
| 316 |
Value contacts(kArrayType); |
| 317 |
// 把元素加进 contacts 数组。 |
| 318 |
// ... |
| 319 |
o.AddMember("contacts", contacts, d.GetAllocator()); // 深度复制 contacts (可能有大量内存分配) |
| 320 |
// 析构 contacts。 |
| 321 |
} |
| 322 |
~~~~~~~~~~ |
| 323 |
|
| 324 |
 |
| 325 |
|
| 326 |
那个 `o` Object 需要分配一个和 contacts 相同大小的缓冲区,对 conacts 做深度复制,并最终要析构 contacts。这样会产生大量无必要的内存分配/释放,以及内存复制。 |
| 327 |
|
| 328 |
有一些方案可避免实质地复制这些数据,例如引用计数(reference counting)、垃圾回收(garbage collection, GC)。 |
| 329 |
|
| 330 |
为了使 RapidJSON 简单及快速,我们选择了对赋值采用 * 转移 * 语义。这方法与 `std::auto_ptr` 相似,都是在赋值时转移拥有权。转移快得多简单得多,只需要析构原来的 Value,把来源 `memcpy()` 至目标,最后把来源设置为 Null 类型。 |
| 331 |
|
| 332 |
因此,使用转移语义后,上面的例子变成: |
| 333 |
|
| 334 |
~~~~~~~~~~cpp |
| 335 |
Value o(kObjectType); |
| 336 |
{ |
| 337 |
Value contacts(kArrayType); |
| 338 |
// adding elements to contacts array. |
| 339 |
o.AddMember("contacts", contacts, d.GetAllocator()); // 只需 memcpy() contacts 本身至新成员的 Value(16 字节) |
| 340 |
// contacts 在这里变成 Null。它的析构是平凡的。 |
| 341 |
} |
| 342 |
~~~~~~~~~~ |
| 343 |
|
| 344 |
 |
| 345 |
|
| 346 |
在 C++11 中这称为转移赋值操作(move assignment operator)。由于 RapidJSON 支持 C++03,它在赋值操作采用转移语义,其它修改型函数如 `AddMember()`, `PushBack()` 也采用转移语义。 |
| 347 |
|
| 348 |
### 转移语义及临时值 {#TemporaryValues} |
| 349 |
|
| 350 |
有时候,我们想直接构造一个 Value 并传递给一个“转移”函数(如 `PushBack()`、`AddMember()`)。由于临时对象是不能转换为正常的 Value 引用,我们加入了一个方便的 `Move()` 函数: |
| 351 |
|
| 352 |
~~~~~~~~~~cpp |
| 353 |
Value a(kArrayType); |
| 354 |
Document::AllocatorType& allocator = document.GetAllocator(); |
| 355 |
// a.PushBack(Value(42), allocator); // 不能通过编译 |
| 356 |
a.PushBack(Value().SetInt(42), allocator); // fluent API |
| 357 |
a.PushBack(Value(42).Move(), allocator); // 和上一行相同 |
| 358 |
~~~~~~~~~~ |
| 359 |
|
| 360 |
## 创建 String {#CreateString} |
| 361 |
RapidJSON 提供两个 String 的存储策略。 |
| 362 |
|
| 363 |
1. copy-string: 分配缓冲区,然后把来源数据复制至它。 |
| 364 |
2. const-string: 简单地储存字符串的指针。 |
| 365 |
|
| 366 |
Copy-string 总是安全的,因为它拥有数据的克隆。Const-string 可用于存储字符串字面量,以及用于在 DOM 一节中将会提到的 in-situ 解析中。 |
| 367 |
|
| 368 |
为了让用户自定义内存分配方式,当一个操作可能需要内存分配时,RapidJSON 要求用户传递一个 allocator 实例作为 API 参数。此设计避免了在每个 Value 存储 allocator(或 document)的指针。 |
| 369 |
|
| 370 |
因此,当我们把一个 copy-string 赋值时, 调用含有 allocator 的 `SetString()` 重载函数: |
| 371 |
|
| 372 |
~~~~~~~~~~cpp |
| 373 |
Document document; |
| 374 |
Value author; |
| 375 |
char buffer[10]; |
| 376 |
int len = sprintf(buffer, "%s %s", "Milo", "Yip"); // 动态创建的字符串。 |
| 377 |
author.SetString(buffer, len, document.GetAllocator()); |
| 378 |
memset(buffer, 0, sizeof(buffer)); |
| 379 |
// 清空 buffer 后 author.GetString() 仍然包含 "Milo Yip" |
| 380 |
~~~~~~~~~~ |
| 381 |
|
| 382 |
在此例子中,我们使用 `Document` 实例的 allocator。这是使用 RapidJSON 时常用的惯用法。但你也可以用其他 allocator 实例。 |
| 383 |
|
| 384 |
另外,上面的 `SetString()` 需要长度参数。这个 API 能处理含有空字符的字符串。另一个 `SetString()` 重载函数没有长度参数,它假设输入是空字符结尾的,并会调用类似 `strlen()` 的函数去获取长度。 |
| 385 |
|
| 386 |
最后,对于字符串字面量或有安全生命周期的字符串,可以使用 const-string 版本的 `SetString()`,它没有 |
| 387 |
allocator 参数。对于字符串字面量(或字符数组常量),只需简单地传递字面量,又安全又高效: |
| 388 |
|
| 389 |
~~~~~~~~~~cpp |
| 390 |
Value s; |
| 391 |
s.SetString("rapidjson"); // 可包含空字符,长度在编译期推导 |
| 392 |
s = "rapidjson"; // 上行的缩写 |
| 393 |
~~~~~~~~~~ |
| 394 |
|
| 395 |
对于字符指针,RapidJSON 需要作一个标记,代表它不复制也是安全的。可以使用 `StringRef` 函数: |
| 396 |
|
| 397 |
~~~~~~~~~cpp |
| 398 |
const char * cstr = getenv("USER"); |
| 399 |
size_t cstr_len = ...; // 如果有长度 |
| 400 |
Value s; |
| 401 |
// s.SetString(cstr); // 这不能通过编译 |
| 402 |
s.SetString(StringRef(cstr)); // 可以,假设它的生命周期安全,并且是以空字符结尾的 |
| 403 |
s = StringRef(cstr); // 上行的缩写 |
| 404 |
s.SetString(StringRef(cstr, cstr_len));// 更快,可处理空字符 |
| 405 |
s = StringRef(cstr, cstr_len); // 上行的缩写 |
| 406 |
|
| 407 |
~~~~~~~~~ |
| 408 |
|
| 409 |
## 修改 Array {#ModifyArray} |
| 410 |
Array 类型的 Value 提供与 `std::vector` 相似的 API。 |
| 411 |
|
| 412 |
* `Clear()` |
| 413 |
* `Reserve(SizeType, Allocator&)` |
| 414 |
* `Value& PushBack(Value&, Allocator&)` |
| 415 |
* `template <typename T> GenericValue& PushBack(T, Allocator&)` |
| 416 |
* `Value& PopBack()` |
| 417 |
* `ValueIterator Erase(ConstValueIterator pos)` |
| 418 |
* `ValueIterator Erase(ConstValueIterator first, ConstValueIterator last)` |
| 419 |
|
| 420 |
注意,`Reserve(...)` 及 `PushBack(...)` 可能会为数组元素分配内存,所以需要一个 allocator。 |
| 421 |
|
| 422 |
以下是 `PushBack()` 的例子: |
| 423 |
|
| 424 |
~~~~~~~~~~cpp |
| 425 |
Value a(kArrayType); |
| 426 |
Document::AllocatorType& allocator = document.GetAllocator(); |
| 427 |
|
| 428 |
for (int i = 5; i <= 10; i++) |
| 429 |
a.PushBack(i, allocator); // 可能需要调用 realloc() 所以需要 allocator |
| 430 |
|
| 431 |
// 流畅接口(Fluent interface) |
| 432 |
a.PushBack("Lua", allocator).PushBack("Mio", allocator); |
| 433 |
~~~~~~~~~~ |
| 434 |
|
| 435 |
与 STL 不一样的是,`PushBack()`/`PopBack()` 返回 Array 本身的引用。这称为流畅接口(_fluent interface_)。 |
| 436 |
|
| 437 |
如果你想在 Array 中加入一个非常量字符串,或是一个没有足够生命周期的字符串(见 [Create String](#CreateString)),你需要使用 copy-string API 去创建一个 String。为了避免加入中间变量,可以就地使用一个 [临时值](#TemporaryValues): |
| 438 |
|
| 439 |
~~~~~~~~~~cpp |
| 440 |
// 就地 Value 参数 |
| 441 |
contact.PushBack(Value("copy", document.GetAllocator()).Move(), // copy string |
| 442 |
document.GetAllocator()); |
| 443 |
|
| 444 |
// 显式 Value 参数 |
| 445 |
Value val("key", document.GetAllocator()); // copy string |
| 446 |
contact.PushBack(val, document.GetAllocator()); |
| 447 |
~~~~~~~~~~ |
| 448 |
|
| 449 |
## 修改 Object {#ModifyObject} |
| 450 |
Object 是键值对的集合。每个键必须为 String。要修改 Object,方法是增加或移除成员。以下的 API 用来增加成员: |
| 451 |
|
| 452 |
* `Value& AddMember(Value&, Value&, Allocator& allocator)` |
| 453 |
* `Value& AddMember(StringRefType, Value&, Allocator&)` |
| 454 |
* `template <typename T> Value& AddMember(StringRefType, T value, Allocator&)` |
| 455 |
|
| 456 |
以下是一个例子。 |
| 457 |
|
| 458 |
~~~~~~~~~~cpp |
| 459 |
Value contact(kObject); |
| 460 |
contact.AddMember("name", "Milo", document.GetAllocator()); |
| 461 |
contact.AddMember("married", true, document.GetAllocator()); |
| 462 |
~~~~~~~~~~ |
| 463 |
|
| 464 |
使用 `StringRefType` 作为 name 参数的重载版本与字符串的 `SetString` 的接口相似。 这些重载是为了避免复制 `name` 字符串,因为 JSON object 中经常会使用常数键名。 |
| 465 |
|
| 466 |
如果你需要从非常数字符串或生命周期不足的字符串创建键名(见 [创建 String](#CreateString)),你需要使用 copy-string API。为了避免中间变量,可以就地使用 [临时值](#TemporaryValues): |
| 467 |
|
| 468 |
~~~~~~~~~~cpp |
| 469 |
// 就地 Value 参数 |
| 470 |
contact.AddMember(Value("copy", document.GetAllocator()).Move(), // copy string |
| 471 |
Value().Move(), // null value |
| 472 |
document.GetAllocator()); |
| 473 |
|
| 474 |
// 显式参数 |
| 475 |
Value key("key", document.GetAllocator()); // copy string name |
| 476 |
Value val(42); // 某 Value |
| 477 |
contact.AddMember(key, val, document.GetAllocator()); |
| 478 |
~~~~~~~~~~ |
| 479 |
|
| 480 |
移除成员有几个选择: |
| 481 |
|
| 482 |
* `bool RemoveMember(const Ch* name)`:使用键名来移除成员(线性时间复杂度)。 |
| 483 |
* `bool RemoveMember(const Value& name)`:除了 `name` 是一个 Value,和上一行相同。 |
| 484 |
* `MemberIterator RemoveMember(MemberIterator)`:使用迭代器移除成员(_ 常数 _ 时间复杂度)。 |
| 485 |
* `MemberIterator EraseMember(MemberIterator)`:和上行相似但维持成员次序(线性时间复杂度)。 |
| 486 |
* `MemberIterator EraseMember(MemberIterator first, MemberIterator last)`:移除一个范围内的成员,维持次序(线性时间复杂度)。 |
| 487 |
|
| 488 |
`MemberIterator RemoveMember(MemberIterator)` 使用了“转移最后”手法来达成常数时间复杂度。基本上就是析构迭代器位置的成员,然后把最后的成员转移至迭代器位置。因此,成员的次序会被改变。 |
| 489 |
|
| 490 |
## 深复制 Value {#DeepCopyValue} |
| 491 |
若我们真的要复制一个 DOM 树,我们可使用两个 APIs 作深复制:含 allocator 的构造函数及 `CopyFrom()`。 |
| 492 |
|
| 493 |
~~~~~~~~~~cpp |
| 494 |
Document d; |
| 495 |
Document::AllocatorType& a = d.GetAllocator(); |
| 496 |
Value v1("foo"); |
| 497 |
// Value v2(v1); // 不容许 |
| 498 |
|
| 499 |
Value v2(v1, a); // 制造一个克隆 |
| 500 |
assert(v1.IsString()); // v1 不变 |
| 501 |
d.SetArray().PushBack(v1, a).PushBack(v2, a); |
| 502 |
assert(v1.IsNull() && v2.IsNull()); // 两个都转移动 d |
| 503 |
|
| 504 |
v2.CopyFrom(d, a); // 把整个 document 复制至 v2 |
| 505 |
assert(d.IsArray() && d.Size() == 2); // d 不变 |
| 506 |
v1.SetObject().AddMember("array", v2, a); |
| 507 |
d.PushBack(v1, a); |
| 508 |
~~~~~~~~~~ |
| 509 |
|
| 510 |
## 交换 Value {#SwapValues} |
| 511 |
|
| 512 |
RapidJSON 也提供 `Swap()`。 |
| 513 |
|
| 514 |
~~~~~~~~~~cpp |
| 515 |
Value a(123); |
| 516 |
Value b("Hello"); |
| 517 |
a.Swap(b); |
| 518 |
assert(a.IsString()); |
| 519 |
assert(b.IsInt()); |
| 520 |
~~~~~~~~~~ |
| 521 |
|
| 522 |
无论两棵 DOM 树有多复杂,交换是很快的(常数时间)。 |
| 523 |
|
| 524 |
# 下一部分 {#WhatsNext} |
| 525 |
|
| 526 |
本教程展示了如何询查及修改 DOM 树。RapidJSON 还有一个重要概念: |
| 527 |
|
| 528 |
1. [流](doc/stream.zh-cn.md) 是读写 JSON 的通道。流可以是内存字符串、文件流等。用户也可以自定义流。 |
| 529 |
2. [编码](doc/encoding.zh-cn.md) 定义在流或内存中使用的字符编码。RapidJSON 也在内部提供 Unicode 转换及校验功能。 |
| 530 |
3. [DOM](doc/dom.zh-cn.md) 的基本功能已在本教程里介绍。还有更高级的功能,如原位(*in situ*)解析、其他解析选项及高级用法。 |
| 531 |
4. [SAX](doc/sax.zh-cn.md) 是 RapidJSON 解析/生成功能的基础。学习使用 `Reader`/`Writer` 去实现更高性能的应用程序。也可以使用 `PrettyWriter` 去格式化 JSON。 |
| 532 |
5. [性能](doc/performance.zh-cn.md) 展示一些我们做的及第三方的性能测试。 |
| 533 |
6. [技术内幕](doc/internals.md) 讲述一些 RapidJSON 内部的设计及技术。 |
| 534 |
|
| 535 |
你也可以参考 [常见问题](doc/faq.zh-cn.md)、API 文档、例子及单元测试。 |