rj_schema 0.0.1

data/ext/rj_schema/rapidjson/doc/stream.zh-cn.md

@@ -0,0 +1,426 @@
+# 流
+
+在 RapidJSON 中，`rapidjson::Stream` 是用於读写 JSON 的概念（概念是指 C++ 的 concept）。在这里我们先介绍如何使用 RapidJSON 提供的各种流。然后再看看如何自行定义流。
+
+[TOC]
+
+# 内存流 {#MemoryStreams}
+
+内存流把 JSON 存储在内存之中。
+
+## StringStream（输入）{#StringStream}
+
+`StringStream` 是最基本的输入流，它表示一个完整的、只读的、存储于内存的 JSON。它在 `rapidjson/rapidjson.h` 中定义。
+
+~~~~~~~~~~cpp
+#include "rapidjson/document.h" // 会包含 "rapidjson/rapidjson.h"
+
+using namespace rapidjson;
+
+// ...
+const char json[] = "[1, 2, 3, 4]";
+StringStream s(json);
+
+Document d;
+d.ParseStream(s);
+~~~~~~~~~~
+
+由于这是非常常用的用法，RapidJSON 提供 `Document::Parse(const char*)` 去做完全相同的事情：
+
+~~~~~~~~~~cpp
+// ...
+const char json[] = "[1, 2, 3, 4]";
+Document d;
+d.Parse(json);
+~~~~~~~~~~
+
+需要注意，`StringStream` 是 `GenericStringStream<UTF8<> >` 的 typedef，使用者可用其他编码类去代表流所使用的字符集。
+
+## StringBuffer（输出）{#StringBuffer}
+
+`StringBuffer` 是一个简单的输出流。它分配一个内存缓冲区，供写入整个 JSON。可使用 `GetString()` 来获取该缓冲区。
+
+~~~~~~~~~~cpp
+#include "rapidjson/stringbuffer.h"
+
+StringBuffer buffer;
+Writer<StringBuffer> writer(buffer);
+d.Accept(writer);
+
+const char* output = buffer.GetString();
+~~~~~~~~~~
+
+当缓冲区满溢，它将自动增加容量。缺省容量是 256 个字符（UTF8 是 256 字节，UTF16 是 512 字节等）。使用者能自行提供分配器及初始容量。
+
+~~~~~~~~~~cpp
+StringBuffer buffer1(0, 1024); // 使用它的分配器，初始大小 = 1024
+StringBuffer buffer2(allocator, 1024);
+~~~~~~~~~~
+
+如无设置分配器，`StringBuffer` 会自行实例化一个内部分配器。
+
+相似地，`StringBuffer` 是 `GenericStringBuffer<UTF8<> >` 的 typedef。
+
+# 文件流 {#FileStreams}
+
+当要从文件解析一个 JSON，你可以把整个 JSON 读入内存并使用上述的 `StringStream`。
+
+然而，若 JSON 很大，或是内存有限，你可以改用 `FileReadStream`。它只会从文件读取一部分至缓冲区，然后让那部分被解析。若缓冲区的字符都被读完，它会再从文件读取下一部分。
+
+## FileReadStream（输入） {#FileReadStream}
+
+`FileReadStream` 通过 `FILE` 指针读取文件。使用者需要提供一个缓冲区。
+
+~~~~~~~~~~cpp
+#include "rapidjson/filereadstream.h"
+#include <cstdio>
+
+using namespace rapidjson;
+
+FILE* fp = fopen("big.json", "rb"); // 非 Windows 平台使用 "r"
+
+char readBuffer[65536];
+FileReadStream is(fp, readBuffer, sizeof(readBuffer));
+
+Document d;
+d.ParseStream(is);
+
+fclose(fp);
+~~~~~~~~~~
+
+与 `StringStreams` 不一样，`FileReadStream` 是一个字节流。它不处理编码。若文件并非 UTF-8 编码，可以把字节流用 `EncodedInputStream` 包装。我们很快会讨论这个问题。
+
+除了读取文件，使用者也可以使用 `FileReadStream` 来读取 `stdin`。
+
+## FileWriteStream（输出）{#FileWriteStream}
+
+`FileWriteStream` 是一个含缓冲功能的输出流。它的用法与 `FileReadStream` 非常相似。
+
+~~~~~~~~~~cpp
+#include "rapidjson/filewritestream.h"
+#include <cstdio>
+
+using namespace rapidjson;
+
+Document d;
+d.Parse(json);
+// ...
+
+FILE* fp = fopen("output.json", "wb"); // 非 Windows 平台使用 "w"
+
+char writeBuffer[65536];
+FileWriteStream os(fp, writeBuffer, sizeof(writeBuffer));
+
+Writer<FileWriteStream> writer(os);
+d.Accept(writer);
+
+fclose(fp);
+~~~~~~~~~~
+
+它也可以把输出导向 `stdout`。
+
+# iostream 包装类 {#iostreamWrapper}
+
+基于用户的要求，RapidJSON 提供了正式的 `std::basic_istream` 和 `std::basic_ostream` 包装类。然而，请注意其性能会大大低于以上的其他流。
+
+## IStreamWrapper {#IStreamWrapper}
+
+`IStreamWrapper` 把任何继承自 `std::istream` 的类（如 `std::istringstream`、`std::stringstream`、`std::ifstream`、`std::fstream`）包装成 RapidJSON 的输入流。
+
+~~~cpp
+#include <rapidjson/document.h>
+#include <rapidjson/istreamwrapper.h>
+#include <fstream>
+
+using namespace rapidjson;
+using namespace std;
+
+ifstream ifs("test.json");
+IStreamWrapper isw(ifs);
+
+Document d;
+d.ParseStream(isw);
+~~~
+
+对于继承自 `std::wistream` 的类，则使用 `WIStreamWrapper`。
+
+## OStreamWrapper {#OStreamWrapper}
+
+相似地，`OStreamWrapper` 把任何继承自 `std::ostream` 的类（如 `std::ostringstream`、`std::stringstream`、`std::ofstream`、`std::fstream`）包装成 RapidJSON 的输出流。
+
+~~~cpp
+#include <rapidjson/document.h>
+#include <rapidjson/ostreamwrapper.h>
+#include <rapidjson/writer.h>
+#include <fstream>
+
+using namespace rapidjson;
+using namespace std;
+
+Document d;
+d.Parse(json);
+
+// ...
+
+ofstream ofs("output.json");
+OStreamWrapper osw(ofs);
+
+Writer<OStreamWrapper> writer(osw);
+d.Accept(writer);
+~~~
+
+对于继承自 `std::wistream` 的类，则使用 `WIStreamWrapper`。
+
+# 编码流 {#EncodedStreams}
+
+编码流（encoded streams）本身不存储 JSON，它们是通过包装字节流来提供基本的编码／解码功能。
+
+如上所述，我们可以直接读入 UTF-8 字节流。然而，UTF-16 及 UTF-32 有字节序（endian）问题。要正确地处理字节序，需要在读取时把字节转换成字符（如对 UTF-16 使用 `wchar_t`），以及在写入时把字符转换为字节。
+
+除此以外，我们也需要处理 [字节顺序标记（byte order mark, BOM）](http://en.wikipedia.org/wiki/Byte_order_mark)。当从一个字节流读取时，需要检测 BOM，或者仅仅是把存在的 BOM 消去。当把 JSON 写入字节流时，也可选择写入 BOM。
+
+若一个流的编码在编译期已知，你可使用 `EncodedInputStream` 及 `EncodedOutputStream`。若一个流可能存储 UTF-8、UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE 的 JSON，并且编码只能在运行时得知，你便可以使用 `AutoUTFInputStream` 及 `AutoUTFOutputStream`。这些流定义在 `rapidjson/encodedstream.h`。
+
+注意到，这些编码流可以施于文件以外的流。例如，你可以用编码流包装内存中的文件或自定义的字节流。
+
+## EncodedInputStream {#EncodedInputStream}
+
+`EncodedInputStream` 含两个模板参数。第一个是 `Encoding` 类型，例如定义于 `rapidjson/encodings.h` 的 `UTF8`、`UTF16LE`。第二个参数是被包装的流的类型。
+
+~~~~~~~~~~cpp
+#include "rapidjson/document.h"
+#include "rapidjson/filereadstream.h"   // FileReadStream
+#include "rapidjson/encodedstream.h"    // EncodedInputStream
+#include <cstdio>
+
+using namespace rapidjson;
+
+FILE* fp = fopen("utf16le.json", "rb"); // 非 Windows 平台使用 "r"
+
+char readBuffer[256];
+FileReadStream bis(fp, readBuffer, sizeof(readBuffer));
+
+EncodedInputStream<UTF16LE<>, FileReadStream> eis(bis);  // 用 eis 包装 bis
+
+Document d; // Document 为 GenericDocument<UTF8<> > 
+d.ParseStream<0, UTF16LE<> >(eis);  // 把 UTF-16LE 文件解析至内存中的 UTF-8
+
+fclose(fp);
+~~~~~~~~~~
+
+## EncodedOutputStream {#EncodedOutputStream}
+
+`EncodedOutputStream` 也是相似的，但它的构造函数有一个 `bool putBOM` 参数，用于控制是否在输出字节流写入 BOM。
+
+~~~~~~~~~~cpp
+#include "rapidjson/filewritestream.h"  // FileWriteStream
+#include "rapidjson/encodedstream.h"    // EncodedOutputStream
+#include <cstdio>
+
+Document d;         // Document 为 GenericDocument<UTF8<> > 
+// ...
+
+FILE* fp = fopen("output_utf32le.json", "wb"); // 非 Windows 平台使用 "w"
+
+char writeBuffer[256];
+FileWriteStream bos(fp, writeBuffer, sizeof(writeBuffer));
+
+typedef EncodedOutputStream<UTF32LE<>, FileWriteStream> OutputStream;
+OutputStream eos(bos, true);   // 写入 BOM
+
+Writer<OutputStream, UTF32LE<>, UTF8<>> writer(eos);
+d.Accept(writer);   // 这里从内存的 UTF-8 生成 UTF32-LE 文件
+
+fclose(fp);
+~~~~~~~~~~
+
+## AutoUTFInputStream {#AutoUTFInputStream}
+
+有时候，应用软件可能需要㲃理所有可支持的 JSON 编码。`AutoUTFInputStream` 会先使用 BOM 来检测编码。若 BOM 不存在，它便会使用合法 JSON 的特性来检测。若两种方法都失败，它就会倒退至构造函数提供的 UTF 类型。
+
+由于字符（编码单元／code unit）可能是 8 位、16 位或 32 位，`AutoUTFInputStream` 需要一个能至少储存 32 位的字符类型。我们可以使用 `unsigned` 作为模板参数：
+
+~~~~~~~~~~cpp
+#include "rapidjson/document.h"
+#include "rapidjson/filereadstream.h"   // FileReadStream
+#include "rapidjson/encodedstream.h"    // AutoUTFInputStream
+#include <cstdio>
+
+using namespace rapidjson;
+
+FILE* fp = fopen("any.json", "rb"); // 非 Windows 平台使用 "r"
+
+char readBuffer[256];
+FileReadStream bis(fp, readBuffer, sizeof(readBuffer));
+
+AutoUTFInputStream<unsigned, FileReadStream> eis(bis);  // 用 eis 包装 bis
+
+Document d;         // Document 为 GenericDocument<UTF8<> > 
+d.ParseStream<0, AutoUTF<unsigned> >(eis); // 把任何 UTF 编码的文件解析至内存中的 UTF-8
+
+fclose(fp);
+~~~~~~~~~~
+
+当要指定流的编码，可使用上面例子中 `ParseStream()` 的参数 `AutoUTF<CharType>`。
+
+你可以使用 `UTFType GetType()` 去获取 UTF 类型，并且用 `HasBOM()` 检测输入流是否含有 BOM。
+
+## AutoUTFOutputStream {#AutoUTFOutputStream}
+
+相似地，要在运行时选择输出的编码，我们可使用 `AutoUTFOutputStream`。这个类本身并非「自动」。你需要在运行时指定 UTF 类型，以及是否写入 BOM。
+
+~~~~~~~~~~cpp
+using namespace rapidjson;
+
+void WriteJSONFile(FILE* fp, UTFType type, bool putBOM, const Document& d) {
+    char writeBuffer[256];
+    FileWriteStream bos(fp, writeBuffer, sizeof(writeBuffer));
+
+    typedef AutoUTFOutputStream<unsigned, FileWriteStream> OutputStream;
+    OutputStream eos(bos, type, putBOM);
+    
+    Writer<OutputStream, UTF8<>, AutoUTF<> > writer;
+    d.Accept(writer);
+}
+~~~~~~~~~~
+
+`AutoUTFInputStream`／`AutoUTFOutputStream` 是比 `EncodedInputStream`／`EncodedOutputStream` 方便。但前者会产生一点运行期额外开销。
+
+# 自定义流 {#CustomStream}
+
+除了内存／文件流，使用者可创建自行定义适配 RapidJSON API 的流类。例如，你可以创建网络流、从压缩文件读取的流等等。
+
+RapidJSON 利用模板结合不同的类型。只要一个类包含所有所需的接口，就可以作为一个流。流的接合定义在 `rapidjson/rapidjson.h` 的注释里：
+
+~~~~~~~~~~cpp
+concept Stream {
+    typename Ch;    //!< 流的字符类型
+
+    //! 从流读取当前字符，不移动读取指针（read cursor）
+    Ch Peek() const;
+
+    //! 从流读取当前字符，移动读取指针至下一字符。
+    Ch Take();
+
+    //! 获取读取指针。
+    //! \return 从开始以来所读过的字符数量。
+    size_t Tell();
+
+    //! 从当前读取指针开始写入操作。
+    //! \return 返回开始写入的指针。
+    Ch* PutBegin();
+
+    //! 写入一个字符。
+    void Put(Ch c);
+
+    //! 清空缓冲区。
+    void Flush();
+
+    //! 完成写作操作。
+    //! \param begin PutBegin() 返回的开始写入指针。
+    //! \return 已写入的字符数量。
+    size_t PutEnd(Ch* begin);
+}
+~~~~~~~~~~
+
+输入流必须实现 `Peek()`、`Take()` 及 `Tell()`。
+输出流必须实现 `Put()` 及 `Flush()`。
+`PutBegin()` 及 `PutEnd()` 是特殊的接口，仅用于原位（*in situ*）解析。一般的流不需实现它们。然而，即使接口不需用于某些流，仍然需要提供空实现，否则会产生编译错误。
+
+## 例子：istream 的包装类 {#ExampleIStreamWrapper}
+
+以下的简单例子是 `std::istream` 的包装类，它只需现 3 个函数。
+
+~~~~~~~~~~cpp
+class MyIStreamWrapper {
+public:
+    typedef char Ch;
+
+    MyIStreamWrapper(std::istream& is) : is_(is) {
+    }
+
+    Ch Peek() const { // 1
+        int c = is_.peek();
+        return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
+    }
+
+    Ch Take() { // 2
+        int c = is_.get();
+        return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
+    }
+
+    size_t Tell() const { return (size_t)is_.tellg(); } // 3
+
+    Ch* PutBegin() { assert(false); return 0; }
+    void Put(Ch) { assert(false); }
+    void Flush() { assert(false); }
+    size_t PutEnd(Ch*) { assert(false); return 0; }
+
+private:
+    MyIStreamWrapper(const MyIStreamWrapper&);
+    MyIStreamWrapper& operator=(const MyIStreamWrapper&);
+
+    std::istream& is_;
+};
+~~~~~~~~~~
+
+使用者能用它来包装 `std::stringstream`、`std::ifstream` 的实例。
+
+~~~~~~~~~~cpp
+const char* json = "[1,2,3,4]";
+std::stringstream ss(json);
+MyIStreamWrapper is(ss);
+
+Document d;
+d.ParseStream(is);
+~~~~~~~~~~
+
+但要注意，由于标准库的内部开销问，此实现的性能可能不如 RapidJSON 的内存／文件流。
+
+## 例子：ostream 的包装类 {#ExampleOStreamWrapper}
+
+以下的例子是 `std::istream` 的包装类，它只需实现 2 个函数。
+
+~~~~~~~~~~cpp
+class MyOStreamWrapper {
+public:
+    typedef char Ch;
+
+    OStreamWrapper(std::ostream& os) : os_(os) {
+    }
+
+    Ch Peek() const { assert(false); return '\0'; }
+    Ch Take() { assert(false); return '\0'; }
+    size_t Tell() const {  }
+
+    Ch* PutBegin() { assert(false); return 0; }
+    void Put(Ch c) { os_.put(c); }                  // 1
+    void Flush() { os_.flush(); }                   // 2
+    size_t PutEnd(Ch*) { assert(false); return 0; }
+
+private:
+    MyOStreamWrapper(const MyOStreamWrapper&);
+    MyOStreamWrapper& operator=(const MyOStreamWrapper&);
+
+    std::ostream& os_;
+};
+~~~~~~~~~~
+
+使用者能用它来包装 `std::stringstream`、`std::ofstream` 的实例。
+
+~~~~~~~~~~cpp
+Document d;
+// ...
+
+std::stringstream ss;
+MyOStreamWrapper os(ss);
+
+Writer<MyOStreamWrapper> writer(os);
+d.Accept(writer);
+~~~~~~~~~~
+
+但要注意，由于标准库的内部开销问，此实现的性能可能不如 RapidJSON 的内存／文件流。
+
+# 总结 {#Summary}
+
+本节描述了 RapidJSON 提供的各种流的类。内存流很简单。若 JSON 存储在文件中，文件流可减少 JSON 解析及生成所需的内存量。编码流在字节流和字符流之间作转换。最后，使用者可使用一个简单接口创建自定义的流。

data/ext/rj_schema/rapidjson/doc/tutorial.md

@@ -0,0 +1,536 @@
+# Tutorial
+
+This tutorial introduces the basics of the Document Object Model(DOM) API.
+
+As shown in [Usage at a glance](@ref index), JSON can be parsed into a DOM, and then the DOM can be queried and modified easily, and finally be converted back to JSON.
+
+[TOC]
+
+# Value & Document {#ValueDocument}
+
+Each JSON value is stored in a type called `Value`. A `Document`, representing the DOM, contains the root `Value` of the DOM tree. All public types and functions of RapidJSON are defined in the `rapidjson` namespace.
+
+# Query Value {#QueryValue}
+
+In this section, we will use excerpt of `example/tutorial/tutorial.cpp`.
+
+Assume we have the following JSON stored in a C string (`const char* json`):
+~~~~~~~~~~js
+{
+    "hello": "world",
+    "t": true ,
+    "f": false,
+    "n": null,
+    "i": 123,
+    "pi": 3.1416,
+    "a": [1, 2, 3, 4]
+}
+~~~~~~~~~~
+
+Parse it into a `Document`:
+~~~~~~~~~~cpp
+#include "rapidjson/document.h"
+
+using namespace rapidjson;
+
+// ...
+Document document;
+document.Parse(json);
+~~~~~~~~~~
+
+The JSON is now parsed into `document` as a *DOM tree*:
+
+![DOM in the tutorial](diagram/tutorial.png)
+
+Since the update to RFC 7159, the root of a conforming JSON document can be any JSON value.  In earlier RFC 4627, only objects or arrays were allowed as root values. In this case, the root is an object.
+~~~~~~~~~~cpp
+assert(document.IsObject());
+~~~~~~~~~~
+
+Let's query whether a `"hello"` member exists in the root object. Since a `Value` can contain different types of value, we may need to verify its type and use suitable API to obtain the value. In this example, `"hello"` member associates with a JSON string.
+~~~~~~~~~~cpp
+assert(document.HasMember("hello"));
+assert(document["hello"].IsString());
+printf("hello = %s\n", document["hello"].GetString());
+~~~~~~~~~~
+
+~~~~~~~~~~
+hello = world
+~~~~~~~~~~
+
+JSON true/false values are represented as `bool`.
+~~~~~~~~~~cpp
+assert(document["t"].IsBool());
+printf("t = %s\n", document["t"].GetBool() ? "true" : "false");
+~~~~~~~~~~
+
+~~~~~~~~~~
+t = true
+~~~~~~~~~~
+
+JSON null can be queried with `IsNull()`.
+~~~~~~~~~~cpp
+printf("n = %s\n", document["n"].IsNull() ? "null" : "?");
+~~~~~~~~~~
+
+~~~~~~~~~~
+n = null
+~~~~~~~~~~
+
+JSON number type represents all numeric values. However, C++ needs more specific type for manipulation.
+
+~~~~~~~~~~cpp
+assert(document["i"].IsNumber());
+
+// In this case, IsUint()/IsInt64()/IsUInt64() also return true.
+assert(document["i"].IsInt());          
+printf("i = %d\n", document["i"].GetInt());
+// Alternative (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 contains a number of elements.
+~~~~~~~~~~cpp
+// Using a reference for consecutive access is handy and faster.
+const Value& a = document["a"];
+assert(a.IsArray());
+for (SizeType i = 0; i < a.Size(); i++) // Uses SizeType instead of size_t
+        printf("a[%d] = %d\n", i, a[i].GetInt());
+~~~~~~~~~~
+
+~~~~~~~~~~
+a[0] = 1
+a[1] = 2
+a[2] = 3
+a[3] = 4
+~~~~~~~~~~
+
+Note that, RapidJSON does not automatically convert values between JSON types. If a value is a string, it is invalid to call `GetInt()`, for example. In debug mode it will fail an assertion. In release mode, the behavior is undefined.
+
+In the following sections we discuss details about querying individual types.
+
+## Query Array {#QueryArray}
+
+By default, `SizeType` is typedef of `unsigned`. In most systems, an array is limited to store up to 2^32-1 elements.
+
+You may access the elements in an array by integer literal, for example, `a[0]`, `a[1]`, `a[2]`.
+
+Array is similar to `std::vector`: instead of using indices, you may also use iterator to access all the elements.
+~~~~~~~~~~cpp
+for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)
+    printf("%d ", itr->GetInt());
+~~~~~~~~~~
+
+And other familiar query functions:
+* `SizeType Capacity() const`
+* `bool Empty() const`
+
+### Range-based For Loop (New in v1.1.0)
+
+When C++11 is enabled, you can use range-based for loop to access all elements in an array.
+
+~~~~~~~~~~cpp
+for (auto& v : a.GetArray())
+    printf("%d ", v.GetInt());
+~~~~~~~~~~
+
+## Query Object {#QueryObject}
+
+Similar to Array, we can access all object members by iterator:
+
+~~~~~~~~~~cpp
+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
+~~~~~~~~~~
+
+Note that, when `operator[](const char*)` cannot find the member, it will fail an assertion.
+
+If we are unsure whether a member exists, we need to call `HasMember()` before calling `operator[](const char*)`. However, this incurs two lookup. A better way is to call `FindMember()`, which can check the existence of member and obtain its value at once:
+
+~~~~~~~~~~cpp
+Value::ConstMemberIterator itr = document.FindMember("hello");
+if (itr != document.MemberEnd())
+    printf("%s\n", itr->value.GetString());
+~~~~~~~~~~
+
+### Range-based For Loop (New in v1.1.0)
+
+When C++11 is enabled, you can use range-based for loop to access all members in an object.
+
+~~~~~~~~~~cpp
+for (auto& m : document.GetObject())
+    printf("Type of member %s is %s\n",
+        m.name.GetString(), kTypeNames[m.value.GetType()]);
+~~~~~~~~~~
+
+## Querying Number {#QueryNumber}
+
+JSON provides a single numerical type called Number. Number can be an integer or a real number. RFC 4627 says the range of Number is specified by the parser implementation.
+
+As C++ provides several integer and floating point number types, the DOM tries to handle these with the widest possible range and good performance.
+
+When a Number is parsed, it is stored in the DOM as one of the following types:
+
+Type       | Description
+-----------|---------------------------------------
+`unsigned` | 32-bit unsigned integer
+`int`      | 32-bit signed integer
+`uint64_t` | 64-bit unsigned integer
+`int64_t`  | 64-bit signed integer
+`double`   | 64-bit double precision floating point
+
+When querying a number, you can check whether the number can be obtained as the target type:
+
+Checking          | Obtaining
+------------------|---------------------
+`bool IsNumber()` | N/A
+`bool IsUint()`   | `unsigned GetUint()`
+`bool IsInt()`    | `int GetInt()`
+`bool IsUint64()` | `uint64_t GetUint64()`
+`bool IsInt64()`  | `int64_t GetInt64()`
+`bool IsDouble()` | `double GetDouble()`
+
+Note that, an integer value may be obtained in various ways without conversion. For example, A value `x` containing 123 will make `x.IsInt() == x.IsUint() == x.IsInt64() == x.IsUint64() == true`. But a value `y` containing -3000000000 will only make `x.IsInt64() == true`.
+
+When obtaining the numeric values, `GetDouble()` will convert internal integer representation to a `double`. Note that, `int` and `unsigned` can be safely converted to `double`, but `int64_t` and `uint64_t` may lose precision (since mantissa of `double` is only 52-bits).
+
+## Query String {#QueryString}
+
+In addition to `GetString()`, the `Value` class also contains `GetStringLength()`. Here explains why.
+
+According to RFC 4627, JSON strings can contain Unicode character `U+0000`, which must be escaped as `"\u0000"`. The problem is that, C/C++ often uses null-terminated string, which treats ``\0'` as the terminator symbol.
+
+To conform RFC 4627, RapidJSON supports string containing `U+0000`. If you need to handle this, you can use `GetStringLength()` to obtain the correct string length.
+
+For example, after parsing a the following JSON to `Document d`:
+
+~~~~~~~~~~js
+{ "s" :  "a\u0000b" }
+~~~~~~~~~~
+The correct length of the value `"a\u0000b"` is 3. But `strlen()` returns 1.
+
+`GetStringLength()` can also improve performance, as user may often need to call `strlen()` for allocating buffer.
+
+Besides, `std::string` also support a constructor:
+
+~~~~~~~~~~cpp
+string(const char* s, size_t count);
+~~~~~~~~~~
+
+which accepts the length of string as parameter. This constructor supports storing null character within the string, and should also provide better performance.
+
+## Comparing values
+
+You can use `==` and `!=` to compare values. Two values are equal if and only if they are have same type and contents. You can also compare values with primitive types. Here is an example.
+
+~~~~~~~~~~cpp
+if (document["hello"] == document["n"]) /*...*/;    // Compare values
+if (document["hello"] == "world") /*...*/;          // Compare value with literal string
+if (document["i"] != 123) /*...*/;                  // Compare with integers
+if (document["pi"] != 3.14) /*...*/;                // Compare with double.
+~~~~~~~~~~
+
+Array/object compares their elements/members in order. They are equal if and only if their whole subtrees are equal.
+
+Note that, currently if an object contains duplicated named member, comparing equality with any object is always `false`.
+
+# Create/Modify Values {#CreateModifyValues}
+
+There are several ways to create values. After a DOM tree is created and/or modified, it can be saved as JSON again using `Writer`.
+
+## Change Value Type {#ChangeValueType}
+When creating a Value or Document by default constructor, its type is Null. To change its type, call `SetXXX()` or assignment operator, for example:
+
+~~~~~~~~~~cpp
+Document d; // Null
+d.SetObject();
+
+Value v;    // Null
+v.SetInt(10);
+v = 10;     // Shortcut, same as above
+~~~~~~~~~~
+
+### Overloaded Constructors
+There are also overloaded constructors for several types:
+
+~~~~~~~~~~cpp
+Value b(true);    // calls Value(bool)
+Value i(-123);    // calls Value(int)
+Value u(123u);    // calls Value(unsigned)
+Value d(1.5);     // calls Value(double)
+~~~~~~~~~~
+
+To create empty object or array, you may use `SetObject()`/`SetArray()` after default constructor, or using the `Value(Type)` in one shot:
+
+~~~~~~~~~~cpp
+Value o(kObjectType);
+Value a(kArrayType);
+~~~~~~~~~~
+
+## Move Semantics {#MoveSemantics}
+
+A very special decision during design of RapidJSON is that, assignment of value does not copy the source value to destination value. Instead, the value from source is moved to the destination. For example,
+
+~~~~~~~~~~cpp
+Value a(123);
+Value b(456);
+b = a;         // a becomes a Null value, b becomes number 123.
+~~~~~~~~~~
+
+![Assignment with move semantics.](diagram/move1.png)
+
+Why? What is the advantage of this semantics?
+
+The simple answer is performance. For fixed size JSON types (Number, True, False, Null), copying them is fast and easy. However, For variable size JSON types (String, Array, Object), copying them will incur a lot of overheads. And these overheads are often unnoticed. Especially when we need to create temporary object, copy it to another variable, and then destruct it.
+
+For example, if normal *copy* semantics was used:
+
+~~~~~~~~~~cpp
+Document d;
+Value o(kObjectType);
+{
+    Value contacts(kArrayType);
+    // adding elements to contacts array.
+    // ...
+    o.AddMember("contacts", contacts, d.GetAllocator());  // deep clone contacts (may be with lots of allocations)
+    // destruct contacts.
+}
+~~~~~~~~~~
+
+![Copy semantics makes a lots of copy operations.](diagram/move2.png)
+
+The object `o` needs to allocate a buffer of same size as contacts, makes a deep clone of it, and then finally contacts is destructed. This will incur a lot of unnecessary allocations/deallocations and memory copying.
+
+There are solutions to prevent actual copying these data, such as reference counting and garbage collection(GC).
+
+To make RapidJSON simple and fast, we chose to use *move* semantics for assignment. It is similar to `std::auto_ptr` which transfer ownership during assignment. Move is much faster and simpler, it just destructs the original value, `memcpy()` the source to destination, and finally sets the source as Null type.
+
+So, with move semantics, the above example becomes:
+
+~~~~~~~~~~cpp
+Document d;
+Value o(kObjectType);
+{
+    Value contacts(kArrayType);
+    // adding elements to contacts array.
+    o.AddMember("contacts", contacts, d.GetAllocator());  // just memcpy() of contacts itself to the value of new member (16 bytes)
+    // contacts became Null here. Its destruction is trivial.
+}
+~~~~~~~~~~
+
+![Move semantics makes no copying.](diagram/move3.png)
+
+This is called move assignment operator in C++11. As RapidJSON supports C++03, it adopts move semantics using assignment operator, and all other modifying function like `AddMember()`, `PushBack()`.
+
+### Move semantics and temporary values {#TemporaryValues}
+
+Sometimes, it is convenient to construct a Value in place, before passing it to one of the "moving" functions, like `PushBack()` or `AddMember()`.  As temporary objects can't be converted to proper Value references, the convenience function `Move()` is available:
+
+~~~~~~~~~~cpp
+Value a(kArrayType);
+Document::AllocatorType& allocator = document.GetAllocator();
+// a.PushBack(Value(42), allocator);       // will not compile
+a.PushBack(Value().SetInt(42), allocator); // fluent API
+a.PushBack(Value(42).Move(), allocator);   // same as above
+~~~~~~~~~~
+
+## Create String {#CreateString}
+RapidJSON provides two strategies for storing string.
+
+1. copy-string: allocates a buffer, and then copy the source data into it.
+2. const-string: simply store a pointer of string.
+
+Copy-string is always safe because it owns a copy of the data. Const-string can be used for storing a string literal, and for in-situ parsing which will be mentioned in the DOM section.
+
+To make memory allocation customizable, RapidJSON requires users to pass an instance of allocator, whenever an operation may require allocation. This design is needed to prevent storing a allocator (or Document) pointer per Value.
+
+Therefore, when we assign a copy-string, we call this overloaded `SetString()` with allocator:
+
+~~~~~~~~~~cpp
+Document document;
+Value author;
+char buffer[10];
+int len = sprintf(buffer, "%s %s", "Milo", "Yip"); // dynamically created string.
+author.SetString(buffer, len, document.GetAllocator());
+memset(buffer, 0, sizeof(buffer));
+// author.GetString() still contains "Milo Yip" after buffer is destroyed
+~~~~~~~~~~
+
+In this example, we get the allocator from a `Document` instance. This is a common idiom when using RapidJSON. But you may use other instances of allocator.
+
+Besides, the above `SetString()` requires length. This can handle null characters within a string. There is another `SetString()` overloaded function without the length parameter. And it assumes the input is null-terminated and calls a `strlen()`-like function to obtain the length.
+
+Finally, for a string literal or string with a safe life-cycle one can use the const-string version of `SetString()`, which lacks an allocator parameter.  For string literals (or constant character arrays), simply passing the literal as parameter is safe and efficient:
+
+~~~~~~~~~~cpp
+Value s;
+s.SetString("rapidjson");    // can contain null character, length derived at compile time
+s = "rapidjson";             // shortcut, same as above
+~~~~~~~~~~
+
+For a character pointer, RapidJSON requires it to be marked as safe before using it without copying. This can be achieved by using the `StringRef` function:
+
+~~~~~~~~~cpp
+const char * cstr = getenv("USER");
+size_t cstr_len = ...;                 // in case length is available
+Value s;
+// s.SetString(cstr);                  // will not compile
+s.SetString(StringRef(cstr));          // ok, assume safe lifetime, null-terminated
+s = StringRef(cstr);                   // shortcut, same as above
+s.SetString(StringRef(cstr,cstr_len)); // faster, can contain null character
+s = StringRef(cstr,cstr_len);          // shortcut, same as above
+
+~~~~~~~~~
+
+## Modify Array {#ModifyArray}
+Value with array type provides an API similar to `std::vector`.
+
+* `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)`
+
+Note that, `Reserve(...)` and `PushBack(...)` may allocate memory for the array elements, therefore requiring an allocator.
+
+Here is an example of `PushBack()`:
+
+~~~~~~~~~~cpp
+Value a(kArrayType);
+Document::AllocatorType& allocator = document.GetAllocator();
+
+for (int i = 5; i <= 10; i++)
+    a.PushBack(i, allocator);   // allocator is needed for potential realloc().
+
+// Fluent interface
+a.PushBack("Lua", allocator).PushBack("Mio", allocator);
+~~~~~~~~~~
+
+This API differs from STL in that `PushBack()`/`PopBack()` return the array reference itself. This is called _fluent interface_.
+
+If you want to add a non-constant string or a string without sufficient lifetime (see [Create String](#CreateString)) to the array, you need to create a string Value by using the copy-string API.  To avoid the need for an intermediate variable, you can use a [temporary value](#TemporaryValues) in place:
+
+~~~~~~~~~~cpp
+// in-place Value parameter
+contact.PushBack(Value("copy", document.GetAllocator()).Move(), // copy string
+                 document.GetAllocator());
+
+// explicit parameters
+Value val("key", document.GetAllocator()); // copy string
+contact.PushBack(val, document.GetAllocator());
+~~~~~~~~~~
+
+## Modify Object {#ModifyObject}
+The Object class is a collection of key-value pairs (members). Each key must be a string value. To modify an object, either add or remove members. The following API is for adding members:
+
+* `Value& AddMember(Value&, Value&, Allocator& allocator)`
+* `Value& AddMember(StringRefType, Value&, Allocator&)`
+* `template <typename T> Value& AddMember(StringRefType, T value, Allocator&)`
+
+Here is an example.
+
+~~~~~~~~~~cpp
+Value contact(kObject);
+contact.AddMember("name", "Milo", document.GetAllocator());
+contact.AddMember("married", true, document.GetAllocator());
+~~~~~~~~~~
+
+The name parameter with `StringRefType` is similar to the interface of the `SetString` function for string values. These overloads are used to avoid the need for copying the `name` string, since constant key names are very common in JSON objects.
+
+If you need to create a name from a non-constant string or a string without sufficient lifetime (see [Create String](#CreateString)), you need to create a string Value by using the copy-string API.  To avoid the need for an intermediate variable, you can use a [temporary value](#TemporaryValues) in place:
+
+~~~~~~~~~~cpp
+// in-place Value parameter
+contact.AddMember(Value("copy", document.GetAllocator()).Move(), // copy string
+                  Value().Move(),                                // null value
+                  document.GetAllocator());
+
+// explicit parameters
+Value key("key", document.GetAllocator()); // copy string name
+Value val(42);                             // some value
+contact.AddMember(key, val, document.GetAllocator());
+~~~~~~~~~~
+
+For removing members, there are several choices: 
+
+* `bool RemoveMember(const Ch* name)`: Remove a member by search its name (linear time complexity).
+* `bool RemoveMember(const Value& name)`: same as above but `name` is a Value.
+* `MemberIterator RemoveMember(MemberIterator)`: Remove a member by iterator (_constant_ time complexity).
+* `MemberIterator EraseMember(MemberIterator)`: similar to the above but it preserves order of members (linear time complexity).
+* `MemberIterator EraseMember(MemberIterator first, MemberIterator last)`: remove a range of members, preserves order (linear time complexity).
+
+`MemberIterator RemoveMember(MemberIterator)` uses a "move-last" trick to achieve constant time complexity. Basically the member at iterator is destructed, and then the last element is moved to that position. So the order of the remaining members are changed.
+
+## Deep Copy Value {#DeepCopyValue}
+If we really need to copy a DOM tree, we can use two APIs for deep copy: constructor with allocator, and `CopyFrom()`.
+
+~~~~~~~~~~cpp
+Document d;
+Document::AllocatorType& a = d.GetAllocator();
+Value v1("foo");
+// Value v2(v1); // not allowed
+
+Value v2(v1, a);                      // make a copy
+assert(v1.IsString());                // v1 untouched
+d.SetArray().PushBack(v1, a).PushBack(v2, a);
+assert(v1.IsNull() && v2.IsNull());   // both moved to d
+
+v2.CopyFrom(d, a);                    // copy whole document to v2
+assert(d.IsArray() && d.Size() == 2); // d untouched
+v1.SetObject().AddMember("array", v2, a);
+d.PushBack(v1, a);
+~~~~~~~~~~
+
+## Swap Values {#SwapValues}
+
+`Swap()` is also provided.
+
+~~~~~~~~~~cpp
+Value a(123);
+Value b("Hello");
+a.Swap(b);
+assert(a.IsString());
+assert(b.IsInt());
+~~~~~~~~~~
+
+Swapping two DOM trees is fast (constant time), despite the complexity of the trees.
+
+# What's next {#WhatsNext}
+
+This tutorial shows the basics of DOM tree query and manipulation. There are several important concepts in RapidJSON:
+
+1. [Streams](doc/stream.md) are channels for reading/writing JSON, which can be a in-memory string, or file stream, etc. User can also create their streams.
+2. [Encoding](doc/encoding.md) defines which character encoding is used in streams and memory. RapidJSON also provide Unicode conversion/validation internally.
+3. [DOM](doc/dom.md)'s basics are already covered in this tutorial. Uncover more advanced features such as *in situ* parsing, other parsing options and advanced usages.
+4. [SAX](doc/sax.md) is the foundation of parsing/generating facility in RapidJSON. Learn how to use `Reader`/`Writer` to implement even faster applications. Also try `PrettyWriter` to format the JSON.
+5. [Performance](doc/performance.md) shows some in-house and third-party benchmarks.
+6. [Internals](doc/internals.md) describes some internal designs and techniques of RapidJSON.
+
+You may also refer to the [FAQ](doc/faq.md), API documentation, examples and unit tests.