"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/tutorial.zh-cn.md" between
rapidjson-1.0.2.tar.gz and rapidjson-1.1.0.tar.gz

About: RapidJSON is a fast JSON parser/generator for C++ with both SAX/DOM style API.

tutorial.zh-cn.md  (rapidjson-1.0.2)	:	tutorial.zh-cn.md  (rapidjson-1.1.0)
# 教程		# 教程
本教程简介文件对象模型（Document Object Model, DOM）API。		本教程简介文件对象模型（Document Object Model, DOM）API。
如[用法一览](readme.zh-cn.md)中所示，可以解析一个JSON至DOM，然后就可以轻松查询及修改DOM，并最终转换回JSON。		如 [用法一览](../readme.zh-cn.md#用法一览) 中所示，可以解析一个 JSON 至 DOM，然后就可以轻松查询及修改 DOM，并最终转换回 JSON。
[TOC]		[TOC]
# Value 及 Document {#ValueDocument}		# Value 及 Document {#ValueDocument}
每个JSON值都储存为`Value`类，而`Document`类则表示整个DOM，它存储了一个DOM树的根`Value`。RapidJSON的所有公开类型及函数 都在`rapidjson`命名空间中。		每个 JSON 值都储存为 `Value` 类，而 `Document` 类则表示整个 DOM，它存储了一个 DOM 树的根 `Value`。RapidJSON 的所有公开类型及函数都在 `rapidjson` 命名空间中。
# 查询Value {#QueryValue}		# 查询 Value {#QueryValue}
在本节中，我们会使用到`example/tutorial/tutorial.cpp`中的代码片段。		在本节中，我们会使用到 `example/tutorial/tutorial.cpp` 中的代码片段。
假设我们用C语言的字符串储存一个JSON（`const char* json`）：		假设我们用 C 语言的字符串储存一个 JSON（`const char* json`）：
~~~~~~~~~~js		~~~~~~~~~~js
{		{
"hello": "world",		"hello": "world",
"t": true ,		"t": true ,
"f": false,		"f": false,
"n": null,		"n": null,
"i": 123,		"i": 123,
"pi": 3.1416,		"pi": 3.1416,
"a": [1, 2, 3, 4]		"a": [1, 2, 3, 4]
}		}
~~~~~~~~~~		~~~~~~~~~~
把它解析至一个`Document`：		把它解析至一个 `Document`：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
#include "rapidjson/document.h"		#include "rapidjson/document.h"
using namespace rapidjson;		using namespace rapidjson;
// ...		// ...
Document document;		Document document;
document.Parse(json);		document.Parse(json);
~~~~~~~~~~		~~~~~~~~~~
那么现在该JSON就会被解析至`document`中，成为一棵*DOM树*:		那么现在该 JSON 就会被解析至 `document` 中，成为一棵 *DOM 树 *:
		
自从RFC 7159作出更新，合法JSON文件的根可以是任何类型的JSON值。而在较早的RFC 4627中，根值只允许是Object或Array。而在上述例子中 ，根是一个Object。		自从 RFC 7159 作出更新，合法 JSON 文件的根可以是任何类型的 JSON 值。而在较早的 RFC 4627 中，根值只允许是 Object 或 Ar ray。而在上述例子中，根是一个 Object。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
assert(document.IsObject());		assert(document.IsObject());
~~~~~~~~~~		~~~~~~~~~~
让我们查询一下根Object中有没有`"hello"`成员。由于一个`Value`可包含不同类型的值，我们可能需要验证它的类型，并使用合适的API去获取其值。在 此例中，`"hello"`成员关联到一个JSON String。		让我们查询一下根 Object 中有没有 `"hello"` 成员。由于一个 `Value` 可包含不同类型的值，我们可能需要验证它的类型，并使用合适的 API 去获取其值。在此例中，`"hello"` 成员关联到一个 JSON String。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
assert(document.HasMember("hello"));		assert(document.HasMember("hello"));
assert(document["hello"].IsString());		assert(document["hello"].IsString());
printf("hello = %s\n", document["hello"].GetString());		printf("hello = %s\n", document["hello"].GetString());
~~~~~~~~~~		~~~~~~~~~~
~~~~~~~~~~		~~~~~~~~~~
world		world
~~~~~~~~~~		~~~~~~~~~~
JSON True/False值是以`bool`表示的。		JSON True/False 值是以 `bool` 表示的。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
assert(document["t"].IsBool());		assert(document["t"].IsBool());
printf("t = %s\n", document["t"].GetBool() ? "true" : "false");		printf("t = %s\n", document["t"].GetBool() ? "true" : "false");
~~~~~~~~~~		~~~~~~~~~~
~~~~~~~~~~		~~~~~~~~~~
true		true
~~~~~~~~~~		~~~~~~~~~~
JSON Null值可用`IsNull()`查询。		JSON Null 值可用 `IsNull()` 查询。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
printf("n = %s\n", document["n"].IsNull() ? "null" : "?");		printf("n = %s\n", document["n"].IsNull() ? "null" : "?");
~~~~~~~~~~		~~~~~~~~~~
~~~~~~~~~~		~~~~~~~~~~
null		null
~~~~~~~~~~		~~~~~~~~~~
JSON Number类型表示所有数值。然而，C++需要使用更专门的类型。		JSON Number 类型表示所有数值。然而，C++ 需要使用更专门的类型。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
assert(document["i"].IsNumber());		assert(document["i"].IsNumber());
// 在此情况下，IsUint()/IsInt64()/IsUInt64()也会返回 true		// 在此情况下，IsUint()/IsInt64()/IsUInt64() 也会返回 true
assert(document["i"].IsInt());		assert(document["i"].IsInt());
printf("i = %d\n", document["i"].GetInt());		printf("i = %d\n", document["i"].GetInt());
// 另一种用法： (int)document["i"]		// 另一种用法： (int)document["i"]
assert(document["pi"].IsNumber());		assert(document["pi"].IsNumber());
assert(document["pi"].IsDouble());		assert(document["pi"].IsDouble());
printf("pi = %g\n", document["pi"].GetDouble());		printf("pi = %g\n", document["pi"].GetDouble());
~~~~~~~~~~		~~~~~~~~~~
~~~~~~~~~~		~~~~~~~~~~
i = 123		i = 123
pi = 3.1416		pi = 3.1416
~~~~~~~~~~		~~~~~~~~~~
JSON Array包含一些元素。		JSON Array 包含一些元素。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
// 使用引用来连续访问，方便之余还更高效。		// 使用引用来连续访问，方便之余还更高效。
const Value& a = document["a"];		const Value& a = document["a"];
assert(a.IsArray());		assert(a.IsArray());
for (SizeType i = 0; i < a.Size(); i++) // 使用 SizeType 而不是 size_t		for (SizeType i = 0; i < a.Size(); i++) // 使用 SizeType 而不是 size_t
printf("a[%d] = %d\n", i, a[i].GetInt());		printf("a[%d] = %d\n", i, a[i].GetInt());
~~~~~~~~~~		~~~~~~~~~~
~~~~~~~~~~		~~~~~~~~~~
a[0] = 1		a[0] = 1
a[1] = 2		a[1] = 2
a[2] = 3		a[2] = 3
a[3] = 4		a[3] = 4
~~~~~~~~~~		~~~~~~~~~~
注意，RapidJSON并不自动转换各种JSON类型。例如，对一个String的Value调用`GetInt()`是非法的。在调试模式下，它会被断言失败。在发布 模式下，其行为是未定义的。		注意，RapidJSON 并不自动转换各种 JSON 类型。例如，对一个 String 的 Value 调用 `GetInt()` 是非法的。在调试模式下，它会 被断言失败。在发布模式下，其行为是未定义的。
以下将会讨论有关查询各类型的细节。		以下将会讨论有关查询各类型的细节。
## 查询Array {#QueryArray}		## 查询 Array {#QueryArray}
缺省情况下，`SizeType`是`unsigned`的typedef。在多数系统中，Array最多能存储2^32-1个元素。		缺省情况下，`SizeType` 是 `unsigned` 的 typedef。在多数系统中，Array 最多能存储 2^32-1 个元素。
你可以用整数字面量访问元素，如`a[0]`、`a[1]`、`a[2]`。		你可以用整数字面量访问元素，如 `a[0]`、`a[1]`、`a[2]`。
Array与`std::vector`相似，除了使用索引，也可使用迭待器来访问所有元素。		Array 与 `std::vector` 相似，除了使用索引，也可使用迭代器来访问所有元素。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)		for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)
printf("%d ", itr->GetInt());		printf("%d ", itr->GetInt());
~~~~~~~~~~		~~~~~~~~~~
还有一些熟悉的查询函数：		还有一些熟悉的查询函数：
* `SizeType Capacity() const`		* `SizeType Capacity() const`
* `bool Empty() const`		* `bool Empty() const`
## 查询Object {#QueryObject}		### 范围 for 循环 (v1.1.0 中的新功能)
和Array相似，我们可以用迭代器去访问所有Object成员：		当使用 C++11 功能时，你可使用范围 for 循环去访问 Array 内的所有元素。
		~~~~~~~~~~cpp
		for (auto& v : a.GetArray())
		printf("%d ", v.GetInt());
		~~~~~~~~~~
		## 查询 Object {#QueryObject}
		和 Array 相似，我们可以用迭代器去访问所有 Object 成员：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
static const char* kTypeNames[] =		static const char* kTypeNames[] =
{ "Null", "False", "True", "Object", "Array", "String", "Number" };		{ "Null", "False", "True", "Object", "Array", "String", "Number" };
for (Value::ConstMemberIterator itr = document.MemberBegin();		for (Value::ConstMemberIterator itr = document.MemberBegin();
itr != document.MemberEnd(); ++itr)		itr != document.MemberEnd(); ++itr)
{		{
printf("Type of member %s is %s\n",		printf("Type of member %s is %s\n",
itr->name.GetString(), kTypeNames[itr->value.GetType()]);		itr->name.GetString(), kTypeNames[itr->value.GetType()]);
skipping to change at line 162		skipping to change at line 171
~~~~~~~~~~		~~~~~~~~~~
Type of member hello is String		Type of member hello is String
Type of member t is True		Type of member t is True
Type of member f is False		Type of member f is False
Type of member n is Null		Type of member n is Null
Type of member i is Number		Type of member i is Number
Type of member pi is Number		Type of member pi is Number
Type of member a is Array		Type of member a is Array
~~~~~~~~~~		~~~~~~~~~~
注意，当`operator[](const char*)`找不到成员，它会断言失败。		注意，当 `operator[](const char*)` 找不到成员，它会断言失败。
若我们不确定一个成员是否存在，便需要在调用`operator[](const char*)`前先调用`HasMember()`。然而，这会导致两次查找。更好的做 法是调用`FindMember()`，它能同时检查成员是否存在并返回它的Value：		若我们不确定一个成员是否存在，便需要在调用 `operator[](const char*)` 前先调用 `HasMember()`。然而，这会导致两次查找。更 好的做法是调用 `FindMember()`，它能同时检查成员是否存在并返回它的 Value：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value::ConstMemberIterator itr = document.FindMember("hello");		Value::ConstMemberIterator itr = document.FindMember("hello");
if (itr != document.MemberEnd())		if (itr != document.MemberEnd())
printf("%s %s\n", itr->value.GetString());		printf("%s\n", itr->value.GetString());
		~~~~~~~~~~
		### 范围 for 循环 (v1.1.0 中的新功能)
		当使用 C++11 功能时，你可使用范围 for 循环去访问 Object 内的所有成员。
		~~~~~~~~~~cpp
		for (auto& m : document.GetObject())
		printf("Type of member %s is %s\n",
		m.name.GetString(), kTypeNames[m.value.GetType()]);
~~~~~~~~~~		~~~~~~~~~~
## 查询Number {#QueryNumber}		## 查询 Number {#QueryNumber}
JSON只提供一种数值类型──Number。数字可以是整数或实数。RFC 4627规定数字的范围由解析器指定。		JSON 只提供一种数值类型──Number。数字可以是整数或实数。RFC 4627 规定数字的范围由解析器指定。
由于C++提供多种整数及浮点数类型，DOM尝试尽量提供最广的范围及良好性能。		由于 C++ 提供多种整数及浮点数类型，DOM 尝试尽量提供最广的范围及良好性能。
当解析一个Number时, 它会被存储在DOM之中，成为下列其中一个类型：		当解析一个 Number 时, 它会被存储在 DOM 之中，成为下列其中一个类型：
类型 | 描述		类型 | 描述
-----------|---------------------------------------		-----------|---------------------------------------
`unsigned` | 32位无号整数		`unsigned` | 32 位无号整数
`int` | 32位有号整数		`int` | 32 位有号整数
`uint64_t` | 64位无号整数		`uint64_t` | 64 位无号整数
`int64_t` | 64位有号整数		`int64_t` | 64 位有号整数
`double` | 64位双精度浮点数		`double` | 64 位双精度浮点数
当查询一个Number时, 你可以检查该数字是否能以目标类型来提取：		当查询一个 Number 时, 你可以检查该数字是否能以目标类型来提取：
查检 | 提取		查检 | 提取
------------------|---------------------		------------------|---------------------
`bool IsNumber()` | 不适用		`bool IsNumber()` | 不适用
`bool IsUint()` | `unsigned GetUint()`		`bool IsUint()` | `unsigned GetUint()`
`bool IsInt()` | `int GetInt()`		`bool IsInt()` | `int GetInt()`
`bool IsUint64()` | `uint64_t GetUint64()`		`bool IsUint64()` | `uint64_t GetUint64()`
`bool IsInt64()` | `int64_t GetInt64()`		`bool IsInt64()` | `int64_t GetInt64()`
`bool IsDouble()` | `double GetDouble()`		`bool IsDouble()` | `double GetDouble()`
注意，一个整数可能用几种类型来提取，而无需转换。例如，一个名为`x`的Value包含123，那么`x.IsInt() == x.IsUint() == x.Is Int64() == x.IsUint64() == true`。但如果一个名为`y`的Value包含-3000000000，那么仅会令`x.IsInt64() == true`。		注意，一个整数可能用几种类型来提取，而无需转换。例如，一个名为 `x` 的 Value 包含 123，那么 `x.IsInt() == x.IsUint() = = x.IsInt64() == x.IsUint64() == true`。但如果一个名为 `y` 的 Value 包含 -3000000000，那么仅会令 `x.IsInt64() == true`。
当要提取Number类型，`GetDouble()`是会把内部整数的表示转换成`double`。注意`int` 和`unsigned`可以安全地转换至`doub le`，但`int64_t`及`uint64_t`可能会丧失精度（因为`double`的尾数只有52位）。		当要提取 Number 类型，`GetDouble()` 是会把内部整数的表示转换成 `double`。注意 `int` 和 `unsigned` 可以安全地转 换至 `double`，但 `int64_t` 及 `uint64_t` 可能会丧失精度（因为 `double` 的尾数只有 52 位）。
## 查询String {#QueryString}		## 查询 String {#QueryString}
除了`GetString()`，`Value`类也有一个`GetStringLength()`。这里会解释个中原因。		除了 `GetString()`，`Value` 类也有一个 `GetStringLength()`。这里会解释个中原因。
根据RFC 4627，JSON String可包含Unicode字符`U+0000`，在JSON中会表示为`"\u0000"`。问题是，C/C++通常使用空字符 结尾字符串（null-terminated string），这种字符串把``\0'`作为结束符号。		根据 RFC 4627，JSON String 可包含 Unicode 字符 `U+0000`，在 JSON 中会表示为 `"\u0000"`。问题是，C/C+ + 通常使用空字符结尾字符串（null-terminated string），这种字符串把 ``\0'` 作为结束符号。
为了符合RFC 4627，RapidJSON支持包含`U+0000`的String。若你需要处理这些String，便可使用`GetStringLength()` 去获得正确的字符串长度。		为了符合 RFC 4627，RapidJSON 支持包含 `U+0000` 的 String。若你需要处理这些 String，便可使用 `GetStringLe ngth()` 去获得正确的字符串长度。
例如，当解析以下的JSON至`Document d`之后：		例如，当解析以下的 JSON 至 `Document d` 之后：
~~~~~~~~~~js		~~~~~~~~~~js
{ "s" : "a\u0000b" }		{ "s" : "a\u0000b" }
~~~~~~~~~~		~~~~~~~~~~
`"a\u0000b"`值的正确长度应该是3。但`strlen()`会返回1。		`"a\u0000b"` 值的正确长度应该是 3。但 `strlen()` 会返回 1。
`GetStringLength()`也可以提高性能，因为用户可能需要调用`strlen()`去分配缓冲。		`GetStringLength()` 也可以提高性能，因为用户可能需要调用 `strlen()` 去分配缓冲。
此外，`std::string`也支持这个构造函数：		此外，`std::string` 也支持这个构造函数：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
string(const char* s, size_t count);		string(const char* s, size_t count);
~~~~~~~~~~		~~~~~~~~~~
此构造函数接受字符串长度作为参数。它支持在字符串中存储空字符，也应该会有更好的性能。		此构造函数接受字符串长度作为参数。它支持在字符串中存储空字符，也应该会有更好的性能。
## 比较两个Value		## 比较两个 Value
你可使用`==`及`!=`去比较两个Value。当且仅当两个Value的类型及内容相同，它们才当作相等。你也可以比较Value和它的原生类型值。以下是一个例子。		你可使用 `==` 及 `!=` 去比较两个 Value。当且仅当两个 Value 的类型及内容相同，它们才当作相等。你也可以比较 Value 和它的原生类型值 。以下是一个例子。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
if (document["hello"] == document["n"]) /*...*/; // 比较两个值		if (document["hello"] == document["n"]) /*...*/; // 比较两个值
if (document["hello"] == "world") /*...*/; // 与字符串家面量作比较		if (document["hello"] == "world") /*...*/; // 与字符串家面量作比较
if (document["i"] != 123) /*...*/; // 与整数作比较		if (document["i"] != 123) /*...*/; // 与整数作比较
if (document["pi"] != 3.14) /*...*/; // 与double作比较		if (document["pi"] != 3.14) /*...*/; // 与 double 作比较
~~~~~~~~~~		~~~~~~~~~~
Array／Object顺序以它们的元素／成员作比较。当且仅当它们的整个子树相等，它们才当作相等。		Array／Object 顺序以它们的元素／成员作比较。当且仅当它们的整个子树相等，它们才当作相等。
注意，现时若一个Object含有重复命名的成员，它与任何Object作比较都总会返回`false`。		注意，现时若一个 Object 含有重复命名的成员，它与任何 Object 作比较都总会返回 `false`。
# 创建／修改值 {#CreateModifyValues}		# 创建／修改值 {#CreateModifyValues}
有多种方法去创建值。 当一个DOM树被创建或修改后，可使用`Writer`再次存储为JSON。		有多种方法去创建值。 当一个 DOM 树被创建或修改后，可使用 `Writer` 再次存储为 JSON。
## 改变Value类型 {#ChangeValueType}		## 改变 Value 类型 {#ChangeValueType}
当使用默认构造函数创建一个Value或Document，它的类型便会是Null。要改变其类型，需调用`SetXXX()`或赋值操作，例如：		当使用默认构造函数创建一个 Value 或 Document，它的类型便会是 Null。要改变其类型，需调用 `SetXXX()` 或赋值操作，例如：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Document d; // Null		Document d; // Null
d.SetObject();		d.SetObject();
Value v; // Null		Value v; // Null
v.SetInt(10);		v.SetInt(10);
v = 10; // 简写，和上面的相同		v = 10; // 简写，和上面的相同
~~~~~~~~~~		~~~~~~~~~~
### 构造函数的各个重载		### 构造函数的各个重载
几个类型也有重载构造函数：		几个类型也有重载构造函数：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value b(true); // 调用Value(bool)		Value b(true); // 调用 Value(bool)
Value i(-123); // 调用 Value(int)		Value i(-123); // 调用 Value(int)
Value u(123u); // 调用Value(unsigned)		Value u(123u); // 调用 Value(unsigned)
Value d(1.5); // 调用Value(double)		Value d(1.5); // 调用 Value(double)
~~~~~~~~~~		~~~~~~~~~~
要重建空Object或Array，可在默认构造函数后使用 `SetObject()`/`SetArray()`，或一次性使用`Value(Type)`：		要重建空 Object 或 Array，可在默认构造函数后使用 `SetObject()`/`SetArray()`，或一次性使用 `Value(Type)`：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value o(kObjectType);		Value o(kObjectType);
Value a(kArrayType);		Value a(kArrayType);
~~~~~~~~~~		~~~~~~~~~~
## 转移语意（Move Semantics） {#MoveSemantics}		## 转移语意（Move Semantics） {#MoveSemantics}
在设计RapidJSON时有一个非常特别的决定，就是Value赋值并不是把来源Value复制至目的Value，而是把把来源Value转移（move）至目的Val ue。例如：		在设计 RapidJSON 时有一个非常特别的决定，就是 Value 赋值并不是把来源 Value 复制至目的 Value，而是把把来源 Value 转移（mo ve）至目的 Value。例如：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value a(123);		Value a(123);
Value b(456);		Value b(456);
b = a; // a变成Null，b变成数字123。		b = a; // a 变成 Null，b 变成数字 123。
~~~~~~~~~~		~~~~~~~~~~
		
为什么？此语意有何优点？		为什么？此语意有何优点？
最简单的答案就是性能。对于固定大小的JSON类型（Number、True、False、Null），复制它们是简单快捷。然而，对于可变大小的JSON类型（Stri ng、Array、Object），复制它们会产生大量开销，而且这些开销常常不被察觉。尤其是当我们需要创建临时Object，把它复制至另一变量，然后再析构它。		最简单的答案就是性能。对于固定大小的 JSON 类型（Number、True、False、Null），复制它们是简单快捷。然而，对于可变大小的 JSON 类型（ String、Array、Object），复制它们会产生大量开销，而且这些开销常常不被察觉。尤其是当我们需要创建临时 Object，把它复制至另一变量，然后再析 构它。
例如，若使用正常*复制*语意：		例如，若使用正常 * 复制 * 语意：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value o(kObjectType);		Value o(kObjectType);
{		{
Value contacts(kArrayType);		Value contacts(kArrayType);
// 把元素加进contacts数组。		// 把元素加进 contacts 数组。
// ...		// ...
o.AddMember("contacts", contacts); // 深度复制contacts （可能有大量内存分配）		o.AddMember("contacts", contacts, d.GetAllocator()); // 深度复制 contacts （可能有大
// 析构contacts。		量内存分配）
		// 析构 contacts。
}		}
~~~~~~~~~~		~~~~~~~~~~
		
那个`o` Object需要分配一个和contacts相同大小的缓冲区，对conacts做深度复制，并最终要析构contacts。这样会产生大量无必要的内存分配 ／释放，以及内存复制。		那个 `o` Object 需要分配一个和 contacts 相同大小的缓冲区，对 conacts 做深度复制，并最终要析构 contacts。这样会产生大量无 必要的内存分配／释放，以及内存复制。
有一些方案可避免实质地复制这些数据，例如引用计数（reference counting）、垃圾回收（garbage collection, GC）。		有一些方案可避免实质地复制这些数据，例如引用计数（reference counting）、垃圾回收（garbage collection, GC）。
为了使RapidJSON简单及快速，我们选择了对赋值采用*转移*语意。这方法与`std::auto_ptr`相似，都是在赋值时转移拥有权。转移快得多简单得多，只 需要析构原来的Value，把来源`memcpy()`至目标，最后把来源设置为Null类型。		为了使 RapidJSON 简单及快速，我们选择了对赋值采用 * 转移 * 语意。这方法与 `std::auto_ptr` 相似，都是在赋值时转移拥有权。转移快 得多简单得多，只需要析构原来的 Value，把来源 `memcpy()` 至目标，最后把来源设置为 Null 类型。
因此，使用转移语意后，上面的例子变成：		因此，使用转移语意后，上面的例子变成：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value o(kObjectType);		Value o(kObjectType);
{		{
Value contacts(kArrayType);		Value contacts(kArrayType);
// adding elements to contacts array.		// adding elements to contacts array.
o.AddMember("contacts", contacts); // 只需 memcpy() contacts本身至新成员的Value（16字节		o.AddMember("contacts", contacts, d.GetAllocator()); // 只需 memcpy() contact
）		s 本身至新成员的 Value（16 字节）
// contacts在这里变成Null。它的析构是平凡的。		// contacts 在这里变成 Null。它的析构是平凡的。
}		}
~~~~~~~~~~		~~~~~~~~~~
		
在C++11中这称为转移赋值操作（move assignment operator）。由于RapidJSON 支持C++03，它在赋值操作采用转移语意，其它修改 形函数如`AddMember()`, `PushBack()`也采用转移语意。		在 C++11 中这称为转移赋值操作（move assignment operator）。由于 RapidJSON 支持 C++03，它在赋值操作采用转移语意， 其它修改形函数如 `AddMember()`, `PushBack()` 也采用转移语意。
### 转移语意及临时值 {#TemporaryValues}		### 转移语意及临时值 {#TemporaryValues}
有时候，我们想直接构造一个Value并传递给一个“转移”函数（如`PushBack()`、`AddMember()`）。由于临时对象是不能转换为正常的Value 引用，我们加入了一个方便的`Move()`函数：		有时候，我们想直接构造一个 Value 并传递给一个“转移”函数（如 `PushBack()`、`AddMember()`）。由于临时对象是不能转换为正常的 V alue 引用，我们加入了一个方便的 `Move()` 函数：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value a(kArrayType);		Value a(kArrayType);
Document::AllocatorType& allocator = document.GetAllocator();		Document::AllocatorType& allocator = document.GetAllocator();
// a.PushBack(Value(42), allocator); // 不能通过编译		// a.PushBack(Value(42), allocator); // 不能通过编译
a.PushBack(Value().SetInt(42), allocator); // fluent API		a.PushBack(Value().SetInt(42), allocator); // fluent API
a.PushBack(Value(42).Move(), allocator); // 和上一行相同		a.PushBack(Value(42).Move(), allocator); // 和上一行相同
~~~~~~~~~~		~~~~~~~~~~
## 创建String {#CreateString}		## 创建 String {#CreateString}
RapidJSON提供两个String的存储策略。		RapidJSON 提供两个 String 的存储策略。
1. copy-string: 分配缓冲区，然后把来源数据复制至它。		1. copy-string: 分配缓冲区，然后把来源数据复制至它。
2. const-string: 简单地储存字符串的指针。		2. const-string: 简单地储存字符串的指针。
Copy-string总是安全的，因为它拥有数据的克隆。Const-string可用于存储字符串字面量，以及用于在DOM一节中将会提到的in-situ解析中。		Copy-string 总是安全的，因为它拥有数据的克隆。Const-string 可用于存储字符串字面量，以及用于在 DOM 一节中将会提到的 in-situ 解析中。
为了让用户自定义内存分配方式，当一个操作可能需要内存分配时，RapidJSON要求用户传递一个allocator实例作为API参数。此设计避免了在每个Value 存储allocator（或document）的指针。		为了让用户自定义内存分配方式，当一个操作可能需要内存分配时，RapidJSON 要求用户传递一个 allocator 实例作为 API 参数。此设计避免了在每个 Value 存储 allocator（或 document）的指针。
因此，当我们把一个copy-string赋值时, 调用含有allocator的`SetString()`重载函数：		因此，当我们把一个 copy-string 赋值时, 调用含有 allocator 的 `SetString()` 重载函数：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Document document;		Document document;
Value author;		Value author;
char buffer[10];		char buffer[10];
int len = sprintf(buffer, "%s %s", "Milo", "Yip"); // 动态创建的字符串。		int len = sprintf(buffer, "%s %s", "Milo", "Yip"); // 动态创建的字符串。
author.SetString(buffer, len, document.GetAllocator());		author.SetString(buffer, len, document.GetAllocator());
memset(buffer, 0, sizeof(buffer));		memset(buffer, 0, sizeof(buffer));
// 清空buffer后author.GetString() 仍然包含 "Milo Yip"		// 清空 buffer 后 author.GetString() 仍然包含 "Milo Yip"
~~~~~~~~~~		~~~~~~~~~~
在此例子中，我们使用`Document`实例的allocator。这是使用RapidJSON时常用的惯用法。但你也可以用其他allocator实例。		在此例子中，我们使用 `Document` 实例的 allocator。这是使用 RapidJSON 时常用的惯用法。但你也可以用其他 allocator 实例 。
另外，上面的`SetString()`需要长度参数。这个API能处理含有空字符的字符串。另一个`SetString()`重载函数没有长度参数，它假设输入是空字符 结尾的，并会调用类似`strlen()`的函数去获取长度。		另外，上面的 `SetString()` 需要长度参数。这个 API 能处理含有空字符的字符串。另一个 `SetString()` 重载函数没有长度参数，它假设 输入是空字符结尾的，并会调用类似 `strlen()` 的函数去获取长度。
最后，对于字符串字面量或有安全生命周期的字符串，可以使用const-string版本的`SetString()`，它没有allocator参数。对于字符串家面量 （或字符数组常量），只需简单地传递字面量，又安全又高效：		最后，对于字符串字面量或有安全生命周期的字符串，可以使用 const-string 版本的 `SetString()`，它没有 allocator 参数。对于字 符串家面量（或字符数组常量），只需简单地传递字面量，又安全又高效：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value s;		Value s;
s.SetString("rapidjson"); // 可包含空字符，长度在编译萁推导		s.SetString("rapidjson"); // 可包含空字符，长度在编译萁推导
s = "rapidjson"; // 上行的缩写		s = "rapidjson"; // 上行的缩写
~~~~~~~~~~		~~~~~~~~~~
对于字符指针，RapidJSON需要作一个标记，代表它不复制也是安全的。可以使用`StringRef`函数：		对于字符指针，RapidJSON 需要作一个标记，代表它不复制也是安全的。可以使用 `StringRef` 函数：
~~~~~~~~~cpp		~~~~~~~~~cpp
const char * cstr = getenv("USER");		const char * cstr = getenv("USER");
size_t cstr_len = ...; // 如果有长度		size_t cstr_len = ...; // 如果有长度
Value s;		Value s;
// s.SetString(cstr); // 这不能通过编译		// s.SetString(cstr); // 这不能通过编译
s.SetString(StringRef(cstr)); // 可以，假设它的生命周期案全，并且是以空字符结尾的		s.SetString(StringRef(cstr)); // 可以，假设它的生命周期安全，并且是以空字符结尾的
s = StringRef(cstr); // 上行的缩写		s = StringRef(cstr); // 上行的缩写
s.SetString(StringRef(cstr, cstr_len));// 更快，可处理空字符		s.SetString(StringRef(cstr, cstr_len));// 更快，可处理空字符
s = StringRef(cstr, cstr_len); // 上行的缩写		s = StringRef(cstr, cstr_len); // 上行的缩写
~~~~~~~~~		~~~~~~~~~
## 修改Array {#ModifyArray}		## 修改 Array {#ModifyArray}
Array类型的Value提供与`std::vector`相似的API。		Array 类型的 Value 提供与 `std::vector` 相似的 API。
* `Clear()`		* `Clear()`
* `Reserve(SizeType, Allocator&)`		* `Reserve(SizeType, Allocator&)`
* `Value& PushBack(Value&, Allocator&)`		* `Value& PushBack(Value&, Allocator&)`
* `template <typename T> GenericValue& PushBack(T, Allocator&)`		* `template <typename T> GenericValue& PushBack(T, Allocator&)`
* `Value& PopBack()`		* `Value& PopBack()`
* `ValueIterator Erase(ConstValueIterator pos)`		* `ValueIterator Erase(ConstValueIterator pos)`
* `ValueIterator Erase(ConstValueIterator first, ConstValueIterator last)`		* `ValueIterator Erase(ConstValueIterator first, ConstValueIterator last)`
注意，`Reserve(...)`及`PushBack(...)`可能会为数组元素分配内存，所以需要一个allocator。		注意，`Reserve(...)` 及 `PushBack(...)` 可能会为数组元素分配内存，所以需要一个 allocator。
以下是`PushBack()`的例子：		以下是 `PushBack()` 的例子：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value a(kArrayType);		Value a(kArrayType);
Document::AllocatorType& allocator = document.GetAllocator();		Document::AllocatorType& allocator = document.GetAllocator();
for (int i = 5; i <= 10; i++)		for (int i = 5; i <= 10; i++)
a.PushBack(i, allocator); // 可能需要调用realloc()所以需要allocator		a.PushBack(i, allocator); // 可能需要调用 realloc() 所以需要 allocator
// 流畅接口（Fluent interface）		// 流畅接口（Fluent interface）
a.PushBack("Lua", allocator).PushBack("Mio", allocator);		a.PushBack("Lua", allocator).PushBack("Mio", allocator);
~~~~~~~~~~		~~~~~~~~~~
与STL不一样的是，`PushBack()`/`PopBack()`返回Array本身的引用。这称为流畅接口（_fluent interface_）。		与 STL 不一样的是，`PushBack()`/`PopBack()` 返回 Array 本身的引用。这称为流畅接口（_fluent interface_）。
如果你想在Array中加入一个非常量字符串，或是一个没有足够生命周期的字符串（见[Create String](#CreateString)），你需要使用cop y-string API去创建一个String。为了避免加入中间变量，可以就地使用一个[临时值](#TemporaryValues)：		如果你想在 Array 中加入一个非常量字符串，或是一个没有足够生命周期的字符串（见 [Create String](#CreateString)），你需要使用 copy-string API 去创建一个 String。为了避免加入中间变量，可以就地使用一个 [临时值](#TemporaryValues)：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
// 就地Value参数		// 就地 Value 参数
contact.PushBack(Value("copy", document.GetAllocator()).Move(), // copy string		contact.PushBack(Value("copy", document.GetAllocator()).Move(), // copy string
document.GetAllocator());		document.GetAllocator());
// 显式Value参数		// 显式 Value 参数
Value val("key", document.GetAllocator()); // copy string		Value val("key", document.GetAllocator()); // copy string
contact.PushBack(val, document.GetAllocator());		contact.PushBack(val, document.GetAllocator());
~~~~~~~~~~		~~~~~~~~~~
## 修改Object {#ModifyObject}		## 修改 Object {#ModifyObject}
Object是键值对的集合。每个键必须为String。要修改Object，方法是增加或移除成员。以下的API用来增加城员：		Object 是键值对的集合。每个键必须为 String。要修改 Object，方法是增加或移除成员。以下的 API 用来增加城员：
* `Value& AddMember(Value&, Value&, Allocator& allocator)`		* `Value& AddMember(Value&, Value&, Allocator& allocator)`
* `Value& AddMember(StringRefType, Value&, Allocator&)`		* `Value& AddMember(StringRefType, Value&, Allocator&)`
* `template <typename T> Value& AddMember(StringRefType, T value, Allocator&)`		* `template <typename T> Value& AddMember(StringRefType, T value, Allocator&)`
以下是一个例子。		以下是一个例子。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value contact(kObject);		Value contact(kObject);
contact.AddMember("name", "Milo", document.GetAllocator());		contact.AddMember("name", "Milo", document.GetAllocator());
contact.AddMember("married", true, document.GetAllocator());		contact.AddMember("married", true, document.GetAllocator());
~~~~~~~~~~		~~~~~~~~~~
使用`StringRefType`作为name参数的重载版本与字符串的`SetString`的接口相似。 这些重载是为了避免复制`name`字符串，因为JSON object中经常会使用常数键名。		使用 `StringRefType` 作为 name 参数的重载版本与字符串的 `SetString` 的接口相似。 这些重载是为了避免复制 `name` 字符 串，因为 JSON object 中经常会使用常数键名。
如果你需要从非常数字符串或生命周期不足的字符串创建键名（见[创建String](#CreateString)），你需要使用copy-string API。为了避 免中间变量，可以就地使用[临时值](#TemporaryValues)：		如果你需要从非常数字符串或生命周期不足的字符串创建键名（见 [创建 String](#CreateString)），你需要使用 copy-string API。 为了避免中间变量，可以就地使用 [临时值](#TemporaryValues)：
~~~~~~~~~~cpp		~~~~~~~~~~cpp
// 就地Value参数		// 就地 Value 参数
contact.AddMember(Value("copy", document.GetAllocator()).Move(), // copy string		contact.AddMember(Value("copy", document.GetAllocator()).Move(), // copy string
Value().Move(), // null value		Value().Move(), // null value
document.GetAllocator());		document.GetAllocator());
// 显式参数		// 显式参数
Value key("key", document.GetAllocator()); // copy string name		Value key("key", document.GetAllocator()); // copy string name
Value val(42); // 某Value		Value val(42); // 某 Value
contact.AddMember(key, val, document.GetAllocator());		contact.AddMember(key, val, document.GetAllocator());
~~~~~~~~~~		~~~~~~~~~~
移除成员有几个选择：		移除成员有几个选择：
* `bool RemoveMember(const Ch* name)`：使用键名来移除成员（线性时间复杂度）。		* `bool RemoveMember(const Ch* name)`：使用键名来移除成员（线性时间复杂度）。
* `bool RemoveMember(const Value& name)`：除了`name`是一个Value，和上一行相同。		* `bool RemoveMember(const Value& name)`：除了 `name` 是一个 Value，和上一行相同。
* `MemberIterator RemoveMember(MemberIterator)`：使用迭待器移除成员（_常数_时间复杂度）。		* `MemberIterator RemoveMember(MemberIterator)`：使用迭代器移除成员（_ 常数 _ 时间复杂度）。
* `MemberIterator EraseMember(MemberIterator)`：和上行相似但维持成员次序（线性时间复杂度）。		* `MemberIterator EraseMember(MemberIterator)`：和上行相似但维持成员次序（线性时间复杂度）。
* `MemberIterator EraseMember(MemberIterator first, MemberIterator last)`：移除一个范围 内的成员，维持次序（线性时间复杂度）。		* `MemberIterator EraseMember(MemberIterator first, MemberIterator last)`：移除一个范围 内的成员，维持次序（线性时间复杂度）。
`MemberIterator RemoveMember(MemberIterator)`使用了“转移最后”手法来达成常数时间复杂度。基本上就是析构迭代器位置的 成员，然后把最后的成员转移至迭代器位置。因此，成员的次序会被改变。		`MemberIterator RemoveMember(MemberIterator)` 使用了“转移最后”手法来达成常数时间复杂度。基本上就是析构迭代器位置 的成员，然后把最后的成员转移至迭代器位置。因此，成员的次序会被改变。
## 深复制Value {#DeepCopyValue}		## 深复制 Value {#DeepCopyValue}
若我们真的要复制一个DOM树，我们可使用两个APIs作深复制：含allocator的构造函数及`CopyFrom()`。		若我们真的要复制一个 DOM 树，我们可使用两个 APIs 作深复制：含 allocator 的构造函数及 `CopyFrom()`。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Document d;		Document d;
Document::AllocatorType& a = d.GetAllocator();		Document::AllocatorType& a = d.GetAllocator();
Value v1("foo");		Value v1("foo");
// Value v2(v1); // 不容许		// Value v2(v1); // 不容许
Value v2(v1, a); // 制造一个克隆		Value v2(v1, a); // 制造一个克隆
assert(v1.IsString()); // v1不变		assert(v1.IsString()); // v1 不变
d.SetArray().PushBack(v1, a).PushBack(v2, a);		d.SetArray().PushBack(v1, a).PushBack(v2, a);
assert(v1.IsNull() && v2.IsNull()); // 两个都转移动d		assert(v1.IsNull() && v2.IsNull()); // 两个都转移动 d
v2.CopyFrom(d, a); // 把整个document复制至v2		v2.CopyFrom(d, a); // 把整个 document 复制至 v2
assert(d.IsArray() && d.Size() == 2); // d不变		assert(d.IsArray() && d.Size() == 2); // d 不变
v1.SetObject().AddMember("array", v2, a);		v1.SetObject().AddMember("array", v2, a);
d.PushBack(v1, a);		d.PushBack(v1, a);
~~~~~~~~~~		~~~~~~~~~~
## 交换Value {#SwapValues}		## 交换 Value {#SwapValues}
RapidJSON也提供`Swap()`。		RapidJSON 也提供 `Swap()`。
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Value a(123);		Value a(123);
Value b("Hello");		Value b("Hello");
a.Swap(b);		a.Swap(b);
assert(a.IsString());		assert(a.IsString());
assert(b.IsInt());		assert(b.IsInt());
~~~~~~~~~~		~~~~~~~~~~
无论两棵DOM树有多复杂，交换是很快的（常数时间）。		无论两棵 DOM 树有多复杂，交换是很快的（常数时间）。
# 下一部分 {#WhatsNext}		# 下一部分 {#WhatsNext}
本教程展示了如何询查及修改DOM树。RapidJSON还有一个重要概念：		本教程展示了如何询查及修改 DOM 树。RapidJSON 还有一个重要概念：
1. [流](doc/stream.zh-cn.md) 是读写JSON的通道。流可以是内存字符串、文件流等。用户也可以自定义流。		1. [流](doc/stream.zh-cn.md) 是读写 JSON 的通道。流可以是内存字符串、文件流等。用户也可以自定义流。
2. [编码](doc/encoding.zh-cn.md)定义在流或内存中使用的字符编码。RapidJSON也在内部提供Unicode转换及校验功能。		2. [编码](doc/encoding.zh-cn.md) 定义在流或内存中使用的字符编码。RapidJSON 也在内部提供 Unicode 转换及校验功能。
3. [DOM](doc/dom.zh-cn.md)的基本功能已在本教程里介绍。还有更高级的功能，如原位（*in situ*）解析、其他解析选项及高级用法。		3. [DOM](doc/dom.zh-cn.md) 的基本功能已在本教程里介绍。还有更高级的功能，如原位（*in situ*）解析、其他解析选项及高级用法。
4. [SAX](doc/sax.zh-cn.md) 是RapidJSON解析／生成功能的基础。学习使用`Reader`/`Writer`去实现更高性能的应用程		4. [SAX](doc/sax.zh-cn.md) 是 RapidJSON 解析／生成功能的基础。学习使用 `Reader`/`Writer` 去实现更高性能
序。也可以使用`PrettyWriter`去格式化JSON。		的应用程序。也可以使用 `PrettyWriter` 去格式化 JSON。
5. [性能](doc/performance.zh-cn.md)展示一些我们做的及第三方的性能测试。		5. [性能](doc/performance.zh-cn.md) 展示一些我们做的及第三方的性能测试。
6. [技术内幕](doc/internals.zh-cn.md)讲述一些RapidJSON内部的设计及技术。		6. [技术内幕](doc/internals.md) 讲述一些 RapidJSON 内部的设计及技术。
你也可以参考[常见问题](faq.zh-cn.md)、API文档、例子及单元测试。		你也可以参考 [常见问题](doc/faq.zh-cn.md)、API 文档、例子及单元测试。
End of changes. 97 change blocks.
117 lines changed or deleted		137 lines changed or added

---