Skip to content

R
rapidjson
Commit 9b63f39c authored by Milo Yip's avatar Milo Yip
Browse files
Options

Merge pull request #280 from miloyip/zh-cn 

Localize documents to simplified Chinese
parents f5b021d7 d1a345a6
Hide whitespace changes
Inline Side-by-side
Showing with 2680 additions and 20 deletions
doc/Doxyfile.zh-cn.in 0 → 100644
View file @ 9b63f39c
This source diff could not be displayed because it is too large. You can view the blob instead.
doc/diagram/architecture.dot 0 → 100644
View file @ 9b63f39c
digraph {
compound=true
fontname="Inconsolata, Consolas"
fontsize=10
margin="0,0"
ranksep=0.2
nodesep=0.5
penwidth=0.5
colorscheme=spectral7
node [shape=box, fontname="Inconsolata, Consolas", fontsize=10, penwidth=0.5, style=filled, fillcolor=white]
edge [fontname="Inconsolata, Consolas", fontsize=10, penwidth=0.5]
subgraph cluster1 {
margin="10,10"
labeljust="left"
label = "SAX"
style=filled
fillcolor=6
Reader -> Writer [style=invis]
}
subgraph cluster2 {
margin="10,10"
labeljust="left"
label = "DOM"
style=filled
fillcolor=7
Value
Document
}
Handler [label="<<concept>>\nHandler"]
{
edge [arrowtail=onormal, dir=back]
Value -> Document
Handler -> Document
Handler -> Writer
}
{
edge [arrowhead=vee, style=dashed, constraint=false]
Reader -> Handler [label="calls"]
Value -> Handler [label="calls"]
Document -> Reader [label="uses"]
}
}
\ No newline at end of file
doc/diagram/utilityclass.dot 0 → 100644
View file @ 9b63f39c
digraph {
rankdir=LR
compound=true
fontname="Inconsolata, Consolas"
fontsize=10
margin="0,0"
ranksep=0.3
nodesep=0.15
penwidth=0.5
colorscheme=spectral7
node [shape=box, fontname="Inconsolata, Consolas", fontsize=10, penwidth=0.5, style=filled, fillcolor=white]
edge [fontname="Inconsolata, Consolas", fontsize=10, penwidth=0.5]
subgraph cluster0 {
style=filled
fillcolor=4
Encoding [label="<<concept>>\nEncoding"]
edge [arrowtail=onormal, dir=back]
Encoding -> { UTF8; UTF16; UTF32; ASCII; AutoUTF }
UTF16 -> { UTF16LE; UTF16BE }
UTF32 -> { UTF32LE; UTF32BE }
}
subgraph cluster1 {
style=filled
fillcolor=5
Stream [label="<<concept>>\nStream"]
InputByteStream [label="<<concept>>\nInputByteStream"]
OutputByteStream [label="<<concept>>\nOutputByteStream"]
edge [arrowtail=onormal, dir=back]
Stream -> {
StringStream; InsituStringStream; StringBuffer;
EncodedInputStream; EncodedOutputStream;
AutoUTFInputStream; AutoUTFOutputStream
InputByteStream; OutputByteStream
}
InputByteStream -> { MemoryStream; FlieReadStream }
OutputByteStream -> { MemoryBuffer; FileWriteStream }
}
subgraph cluster2 {
style=filled
fillcolor=3
Allocator [label="<<concept>>\nAllocator"]
edge [arrowtail=onormal, dir=back]
Allocator -> { CrtAllocator; MemoryPoolAllocator }
}
{
edge [arrowtail=odiamond, arrowhead=vee, dir=both]
EncodedInputStream -> InputByteStream
EncodedOutputStream -> OutputByteStream
AutoUTFInputStream -> InputByteStream
AutoUTFOutputStream -> OutputByteStream
MemoryPoolAllocator -> Allocator [label="base", tailport=s]
}
{
edge [arrowhead=vee, style=dashed]
AutoUTFInputStream -> AutoUTF
AutoUTFOutputStream -> AutoUTF
}
//UTF32LE -> Stream [style=invis]
}
\ No newline at end of file
doc/dom.zh-cn.md 0 → 100644
View file @ 9b63f39c
# DOM
文档对象模型（Document Object Model, DOM）是一种罝于内存中的JSON表示方式，以供查询及操作。我们己于[教程](doc/tutorial.md)中介绍了DOM的基本用法，本节将讲述一些细节及高级用法。
[TOC]
# 模板 {#Template}
教程中使用了`Value`和`Document`类型。与`std::string`相似，这些类型其实是两个模板类的`typedef`：
~~~~~~~~~~cpp
namespace rapidjson {
template <typename Encoding, typename Allocator = MemoryPoolAllocator<> >
class GenericValue {
// ...
};
template <typename Encoding, typename Allocator = MemoryPoolAllocator<> >
class GenericDocument : public GenericValue<Encoding, Allocator> {
// ...
};
typedef GenericValue<UTF8<> > Value;
typedef GenericDocument<UTF8<> > Document;
} // namespace rapidjson
~~~~~~~~~~
使用者可以自定义这些模板参数。
## 编码 {#Encoding}
`Encoding`参数指明在内存中的JSON String使用哪种编码。可行的选项有`UTF8`、`UTF16`、`UTF32`。要注意这3个类型其实也是模板类。`UTF8<>`等同`UTF8<char>`，这代表它使用`char`来存储字符串。更多细节可以参考[编码](encoding.md)。
这里是一个例子。假设一个Windows应用软件希望查询存储于JSON中的本地化字符串。Windows中含Unicode的函数使用UTF-16（宽字符）编码。无论JSON文件使用哪种编码，我们都可以把字符串以UTF-16形式存储在内存。
~~~~~~~~~~cpp
using namespace rapidjson;
typedef GenericDocument<UTF16<> > WDocument;
typedef GenericValue<UTF16<> > WValue;
FILE* fp = fopen("localization.json", "rb"); // 非Windows平台使用"r"
char readBuffer[256];
FileReadStream bis(fp, readBuffer, sizeof(readBuffer));
AutoUTFInputStream<unsigned, FileReadStream> eis(bis); // 包装bis成eis
WDocument d;
d.ParseStream<0, AutoUTF<unsigned> >(eis);
const WValue locale(L"ja"); // Japanese
MessageBoxW(hWnd, d[locale].GetString(), L"Test", MB_OK);
~~~~~~~~~~
## 分配器 {#Allocator}
`Allocator`定义当`Document`/`Value`分配或释放内存时使用那个分配类。`Document`拥有或引用到一个`Allocator`实例。而为了节省内存，`Value`没有这么做。
`GenericDocument`的缺省分配器是`MemoryPoolAllocator`。此分配器实际上会顺序地分配内存，并且不能逐一释放。当要解析一个JSON并生成DOM，这种分配器是非常合适的。
RapidJSON还提供另一个分配器`CrtAllocator`，当中CRT是C运行库（C RunTime library）的缩写。此分配器简单地读用标准的`malloc()`/`realloc()`/`free()`。当我们需要许多增减操作，这种分配器会更为适合。然而这种分配器远远比`MemoryPoolAllocator`低效。
# 解析 {#Parsing}
`Document`提供几个解析函数。以下的(1)是根本的函数，其他都是调用(1)的协助函数。
~~~~~~~~~~cpp
using namespace rapidjson;
// (1) 根本
template <unsigned parseFlags, typename SourceEncoding, typename InputStream>
GenericDocument& GenericDocument::ParseStream(InputStream& is);
// (2) 使用流的编码
template <unsigned parseFlags, typename InputStream>
GenericDocument& GenericDocument::ParseStream(InputStream& is);
// (3) 使用缺省标志
template <typename InputStream>
GenericDocument& GenericDocument::ParseStream(InputStream& is);
// (4) 原位解析
template <unsigned parseFlags, typename SourceEncoding>
GenericDocument& GenericDocument::ParseInsitu(Ch* str);
// (5) 原位解析，使用Document的编码
template <unsigned parseFlags>
GenericDocument& GenericDocument::ParseInsitu(Ch* str);
// (6) 原位解析，使用缺省标志
GenericDocument& GenericDocument::ParseInsitu(Ch* str);
// (7) 正常解析一个字符串
template <unsigned parseFlags, typename SourceEncoding>
GenericDocument& GenericDocument::Parse(const Ch* str);
// (8) 正常解析一个字符串，使用Document的编码
template <unsigned parseFlags>
GenericDocument& GenericDocument::Parse(const Ch* str);
// (9) 正常解析一个字符串，使用缺省标志
GenericDocument& GenericDocument::Parse(const Ch* str);
~~~~~~~~~~
[教程](tutorial.md)中的例使用(9)去正常解析字符串。而[流](stream.md)的例子使用前3个函数。我们将稍后介绍原位（*In situ*） 解析。
`parseFlags`是以下位标置的组合：
解析位标志 | 意义
------------------------------|-----------------------------------
`kParseNoFlags` | 没有任何标志。
`kParseDefaultFlags` | 缺省的解析选项。它等于`RAPIDJSON_PARSE_DEFAULT_FLAGS`宏，此宏定义为`kParseNoFlags`。
`kParseInsituFlag` | 原位（破坏性）解析。
`kParseValidateEncodingFlag` | 校验JSON字符串的编码。
`kParseIterativeFlag` | 迭代式（调用堆栈大小为常数复杂度）解析。
`kParseStopWhenDoneFlag` | 当从流解析了一个完整的JSON根节点之后，停止继续处理余下的流。当使用了此标志，解析器便不会产生`kParseErrorDocumentRootNotSingular`错误。可使用本标志去解析同一个流里的多个JSON。
`kParseFullPrecisionFlag` | 使用完整的精确度去解析数字（较慢）。如不设置此标节，则会使用正常的精确度（较快）。正常精确度会有最多3个[ULP](http://en.wikipedia.org/wiki/Unit_in_the_last_place)的误差。
由于使用了非类型模板参数，而不是函数参数，C++编译器能为个别组合生成代码，以改善性能及减少代码尺寸（当只用单种特化）。缺点是需要在编译期决定标志。
`SourceEncoding`参数定义流使用了什么编码。这与`Document`的`Encoding`不相同。细节可参考[转码和校验](#TranscodingAndValidation)一节。
此外`InputStream`是输入流的类型。
## 解析错误 {#ParseError}
当解析过程顺利完成，`Document`便会含有解析结果。当过程出现错误，原来的DOM会*维持不便*。可使用`bool HasParseError()`、`ParseErrorCode GetParseError()`及`size_t GetParseOffet()`获取解析的错误状态。
解析错误代号 | 描述
--------------------------------------------|---------------------------------------------------
`kParseErrorNone` | 无错误。
`kParseErrorDocumentEmpty` | 文档是空的。
`kParseErrorDocumentRootNotSingular` | 文档的根后面不能有其它值。
`kParseErrorValueInvalid` | 不合法的值。
`kParseErrorObjectMissName` | Object成员缺少名字。
`kParseErrorObjectMissColon` | Object成员名字后缺少冒号。
`kParseErrorObjectMissCommaOrCurlyBracket` | Object成员后缺少逗号或`}`。
`kParseErrorArrayMissCommaOrSquareBracket` | Array元素后缺少逗号或`]` 。
`kParseErrorStringUnicodeEscapeInvalidHex` | String中的`\\u`转义符后含非十六进位数字。
`kParseErrorStringUnicodeSurrogateInvalid` | String中的代理对（surrogate pair）不合法。
`kParseErrorStringEscapeInvalid` | String含非法转义字符。
`kParseErrorStringMissQuotationMark` | String缺少关闭引号。
`kParseErrorStringInvalidEncoding` | String含非法编码。
`kParseErrorNumberTooBig` | Number的值太大，不能存储于`double`。
`kParseErrorNumberMissFraction` | Number缺少了小数部分。
`kParseErrorNumberMissExponent` | Number缺少了指数。
错误的偏移量定义为从流开始至错误处的字符数量。目前RapidJSON不记录错误行号。
要取得错误讯息，RapidJSON在`rapidjson/error/en.h`中提供了英文错误讯息。使用者可以修改它用于其他语言环境，或使用一个自定义的本地化系统。
以下是一个处理错误的例子。
~~~~~~~~~~cpp
// TODO: example
~~~~~~~~~~
## 原位解析 {#InSituParsing}
根据[维基百科](http://en.wikipedia.org/wiki/In_situ):
> *In situ* ... is a Latin phrase that translates literally to "on site" or "in position". It means "locally", "on site", "on the premises" or "in place" to describe an event where it takes place, and is used in many different contexts.
> ...
> (In computer science) An algorithm is said to be an in situ algorithm, or in-place algorithm, if the extra amount of memory required to execute the algorithm is O(1), that is, does not exceed a constant no matter how large the input. For example, heapsort is an in situ sorting algorithm.
> 翻译：*In situ*……是一个拉丁文片语，字面上的意思是指「现场」、「在位置」。在许多不同语境中，它描述一个事件发生的位置，意指「本地」、「现场」、「在处所」、「就位」。
> ……
> （在计算机科学中）一个算法若称为原位算法，或在位算法，是指执行该算法所需的额外内存空间是O(1)的，换句话说，无论输入大小都只需要常数空间。例如，堆排序是一个原位排序算法。
在正常的解析过程中，对JSON string解码并复制至其他缓冲区是一个很大的开销。原位解析（*in situ* parsing）把这些JSON string直接解码于它原来存储的地方。由于解码后的string长度总是短于或等于原来储存于JSON的string，所以这是可行的。在这个语境下，对JSON string进行解码是指处理转义符，如`"\n"`、`"\u1234"`等，以及在string末端加入空终止符号(`'\0'`)。
以下的图比较正常及原位解析。JSON string值包含指向解码后的字符串。
![正常解析](diagram/normalparsing.png)
在正常解析中，解码后的字符串被复制至全新分配的缓冲区中。`"\\n"`（2个字符）被解码成`"\n"`（1个字符）。`"\\u0073"`（6个字符）被解码成`"s"`（1个字符）。
![原位解析](diagram/insituparsing.png)
原位解析直接修改了原来的JSON。图中高亮了被更新的字符。若JSON string不含转义符，例如`"msg"`，那么解析过程仅仅是以空字符代替结束双引号。
由于原位解析修改了输入，其解析API需要`char*`而非`const char*`。
~~~~~~~~~~cpp
// 把整个文件读入buffer
FILE* fp = fopen("test.json", "r");
fseek(fp, 0, SEEK_END);
size_t filesize = (size_t)ftell(fp);
fseek(fp, 0, SEEK_SET);
char* buffer = (char*)malloc(filesize + 1);
size_t readLength = fread(buffer, 1, filesize, fp);
buffer[readLength] = '\0';
fclose(fp);
// 原位解析buffer至d，buffer内容会被修改。
Document d;
d.ParseInsitu(buffer);
// 在此查询、修改DOM……
free(buffer);
// 注意：在这个位置，d可能含有指向已被释放的buffer的悬空指针
~~~~~~~~~~
JSON string会被打上const-string的标志。但它们可能并非真正的「常数」。它的生命周期取决于存储JSON的缓冲区。
原位解析把分配开销及内存复制减至最小。通常这样做能改善缓存一致性，而这对现代计算机来说是一个重要的性能因素。
原位解析有以下限制：
1. 整个JSON须存储在内存之中。
2. 流的来源缓码与文档的目标编码必须相同。
3. 需要保留缓冲区，直至文档不再被使用。
4. 若DOM需要在解析后被长期使用，而DOM内只有很少JSON string，保留缓冲区可能造成内存浪费。
原位解析最适合用于短期的、用完即弃的JSON。实际应用中，这些场合是非常普遍的，例如反序列化JSON至C++对象、处理以JSON表示的web请求等。
## 转码与校验 {#TranscodingAndValidation}
RapidJSON内部支持不同Unicode格式（正式的术语是UCS变换格式）间的转换。在DOM解析时，流的来源编码与DOM的编码可以不同。例如，来源流可能含有UTF-8的JSON，而DOM则使用UTF-16编码。在[EncodedInputStream](doc/stream.md#EncodedInputStream)一节里有一个例子。
当从DOM输出一个JSON至输出流之时，也可以使用转码功能。在[EncodedOutputStream](stream.md#EncodedOutputStream)一节里有一个例子。
在转码过程中，会把来源string解码成Unicode码点，然后把码点编码成目标格式。在解码时，它会校验来源string的字节序列是否合法。若遇上非合法序列，解析器会停止并返回`kParseErrorStringInvalidEncoding`错误。
当来源编码与DOM的编码相同，解析器缺省地*不会*校验序列。使用者可开启`kParseValidateEncodingFlag`去强制校验。
# 技巧 {#Techniques}
这里讨论一些DOM API的使用技巧。
## 把DOM作为SAX事件发表者
在RapidJSON中，利用`Writer`把DOM生成JSON的做法，看来有点奇怪。
~~~~~~~~~~cpp
// ...
Writer<StringBuffer> writer(buffer);
d.Accept(writer);
~~~~~~~~~~
实际上，`Value::Accept()`是负责发布该值相关的SAX事件至处理器的。通过这个设计，`Value`及`Writer`解除了偶合。`Value`可生成SAX事件，而`Writer`则可以处理这些事件。
使用者可以创建自定义的处理器，去把DOM转换成其它格式。例如，一个把DOM转换成XML的处理器。
~~~~~~~~~~cpp
// TODO: example
~~~~~~~~~~
要知道更多关于SAX事件与处理器，可参阅[SAX](doc/sax.md)。
## 使用者缓冲区{ #UserBuffer}
许多应用软件可能需要尽量减少内存分配。
`MemoryPoolAllocator`可以帮助这方面，它容许使用者提供一个缓冲区。该缓冲区可能置于程序堆栈，或是一个静态分配的「草稿缓冲区（scratch buffer）」（一个静态／全局的数组），用于储存临时数据。
`MemoryPoolAllocator`会先用使用者缓冲区去解决分配请求。当使用者缓冲区用完，就会从基础分配器（缺省为`CrtAllocator`）分配一块内存。
以下是使用堆栈内存的例子，第一个分配器用于存储值，第二个用于解析时的临时缓冲。
~~~~~~~~~~cpp
typedef GenericDocument<UTF8<>, MemoryPoolAllocator<>, MemoryPoolAllocator<>> DocumentType;
char valueBuffer[4096];
char parseBuffer[1024];
MemoryPoolAllocator<> valueAllocator(valueBuffer, sizeof(valueBuffer));
MemoryPoolAllocator<> parseAllocator(parseBuffer, sizeof(parseBuffer));
DocumentType d(&valueAllocator, sizeof(parseBuffer), &parseAllocator);
d.Parse(json);
~~~~~~~~~~
若解析时分配总量少于4096+1024字节时，这段代码不会造成任何堆内存分配（经`new`或`malloc()`）。
使用者可以通过`MemoryPoolAllocator::Size()`查询当前已分的内存大小。那么使用者可以拟定使用者缓冲区的合适大小。
doc/encoding.zh-cn.md 0 → 100644
View file @ 9b63f39c
# 编码
根据[ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf)：
> (in Introduction) JSON text is a sequence of Unicode code points.
>
> 翻译：JSON文本是Unicode码点的序列。
较早的[RFC4627](http://www.ietf.org/rfc/rfc4627.txt)申明：
> (in §3) JSON text SHALL be encoded in Unicode. The default encoding is UTF-8.
>
> 翻译：JSON文本应该以Unicode编码。缺省的编码为UTF-8。
> (in §6) JSON may be represented using UTF-8, UTF-16, or UTF-32. When JSON is written in UTF-8, JSON is 8bit compatible. When JSON is written in UTF-16 or UTF-32, the binary content-transfer-encoding must be used.
>
> 翻译：JSON可使用UTF-8、UTF-16或UTF-18表示。当JSON以UTF-8写入，该JSON是8位兼容的。当JSON以UTF-16或UTF-32写入，就必须使用二进制的内容传送编码。
RapidJSON支持多种编码。它也能检查JSON的编码，以及在不同编码中进行转码。所有这些功能都是在内部实现，无需使用外部的程序库（如[ICU](http://site.icu-project.org/)）。
[TOC]
# Unicode {#Unicode}
根据 [Unicode的官方网站](http://www.unicode.org/standard/translations/t-chinese.html)：
>Unicode给每个字符提供了一个唯一的数字，
不论是什么平台、
不论是什么程序、
不论是什么语言。
这些唯一数字称为码点（code point），其范围介乎`0x0`至`0x10FFFF`之间。
## Unicode转换格式 {#UTF}
存储Unicode码点有多种编码方式。这些称为Unicode转换格式（Unicode Transformation Format, UTF）。RapidJSON支持最常用的UTF，包括：
* UTF-8：8位可变长度编码。它把一个码点映射至1至4个字节。
* UTF-16：16位可变长度编码。它把一个码点映射至1至2个16位编码单元（即2至4个字节）。
* UTF-32：32位固定长度编码。它直接把码点映射至单个32位编码单元（即4字节）。
对于UTF-16及UTF-32来说，字节序（endianness）是有影响的。在内存中，它们通常都是以该计算机的字节序来存储。然而，当要储存在文件中或在网上传输，我们需要指明字节序列的字节序，是小端（little endian, LE）还是大端（big-endian, BE）。
RapidJSON通过`rapidjson/encodings.h`中的struct去提供各种编码：
~~~~~~~~~~cpp
namespace rapidjson {
template<typename CharType = char>
struct UTF8;
template<typename CharType = wchar_t>
struct UTF16;
template<typename CharType = wchar_t>
struct UTF16LE;
template<typename CharType = wchar_t>
struct UTF16BE;
template<typename CharType = unsigned>
struct UTF32;
template<typename CharType = unsigned>
struct UTF32LE;
template<typename CharType = unsigned>
struct UTF32BE;
} // namespace rapidjson
~~~~~~~~~~
对于在内存中的文本，我们正常会使用`UTF8`、`UTF16`或`UTF32`。对于处理经过I/O的文本，我们可使用`UTF8`、`UTF16LE`、`UTF16BE`、`UTF32LE`或`UTF32BE`。
当使用DOM风格的API，`GenericValue<Encoding>`及`GenericDocument<Encoding>`里的`Encoding`模板参数是用于指明内存中存储的JSON字符串使用哪种编码。因此通常我们会在此参数中使用`UTF8`、`UTF16`或`UTF32`。如何选择，视乎应用软件所使用的操作系统及其他程序库。例如，Windows API使用UTF-16表示Unicode字符，而多数的Linux发行版本及应用软件则更喜欢UTF-8。
使用UTF-16的DOM声明例子：
~~~~~~~~~~cpp
typedef GenericDocument<UTF16<> > WDocument;
typedef GenericValue<UTF16<> > WValue;
~~~~~~~~~~
可以在[DOM's Encoding](doc/stream.md#Encoding)一节看到更详细的使用例子。
## 字符类型 {#CharacterType}
从之前的声明中可以看到，每个编码都有一个`CharType`模板参数。这可能比较容易混淆，实际上，每个`CharType`存储一个编码单元，而不是一个字符（码点）。如之前所谈及，在UTF-8中一个码点可能会编码成1至4个编码单元。
对于`UTF16(LE|BE)`及`UTF32(LE|BE)`来说，`CharType`必须分别是一个至少2及4字节的整数类型。
注意C++11新添了`char16_t`及`char32_t`类型，也可分别用于`UTF16`及`UTF32`。
## AutoUTF {#AutoUTF}
上述所介绍的编码都是在编译期静态挷定的。换句话说，使用者必须知道内存或流之中使用了哪种编码。然而，有时候我们可能需要读写不同编码的文件，而且这些编码需要在运行时才能决定。
`AutoUTF`是为此而设计的编码。它根据输入或输出流来选择使用哪种编码。目前它应该与`EncodedInputStream`及`EncodedOutputStream`结合使用。
## ASCII {#ASCII}
虽然JSON标准并未提及[ASCII](http://en.wikipedia.org/wiki/ASCII)，有时候我们希望写入7位的ASCII JSON，以供未能处理UTF-8的应用程序使用。由于任JSON都可以把Unicode字符表示为`\uXXXX`转义序列，JSON总是可用ASCII来编码。
以下的例子把UTF-8的DOM写成ASCII的JSON：
~~~~~~~~~~cpp
using namespace rapidjson;
Document d; // UTF8<>
// ...
StringBuffer buffer;
Writer<StringBuffer, Document::EncodingType, ASCII<> > writer(buffer);
d.Accept(writer);
std::cout << buffer.GetString();
~~~~~~~~~~
ASCII可用于输入流。当输入流包含大于127的字节，就会导致`kParseErrorStringInvalidEncoding`错误。
ASCII *不能* 用于内存（`Document`的编码，或`Reader`的目标编码)，因为它不能表示Unicode码点。
# 校验及转码 {#ValidationTranscoding}
当RapidJSON解析一个JSON时，它能校验输入JSON，判断它是否所标明编码的合法序列。要开启此选项，请把`kParseValidateEncodingFlag`加入`parseFlags`模板参数。
若输入编码和输出编码并不相同，`Reader`及`Writer`会算把文本转码。在这种情况下，并不需要`kParseValidateEncodingFlag`，因为它必须解码输入序列。若序列不能被解码，它必然是不合法的。
## 转码器 {#Transcoder}
虽然RapidJSON的编码功能是为JSON解析／生成而设计，使用者也可以“滥用”它们来为非JSON字符串转码。
以下的例子把UTF-8字符串转码成UTF-16：
~~~~~~~~~~cpp
#include "rapidjson/encodings.h"
using namespace rapidjson;
const char* s = "..."; // UTF-8 string
StringStream source(s);
GenericStringBuffer<UTF16<> > target;
bool hasError = false;
while (source.Peak() != '\0')
if (!Transcoder::Transcode<UTF8<>, UTF16<> >(source, target)) {
hasError = true;
break;
}
if (!hasError) {
const wchar_t* t = target.GetString();
// ...
}
~~~~~~~~~~
你也可以用`AutoUTF`及对应的流来在运行时设置内源／目的之编码。
doc/faq.md
View file @ 9b63f39c
......@@ -42,11 +42,11 @@
10. How RapidJSON is tested?
RapidJSON contains a unit test suite for automatic testing. [Travis](https://travis-ci.org/miloyip/rapidjson/) will compile and run the unit test suite for all modifications. The test process also uses Valgrind to detect memory leaks.
RapidJSON contains a unit test suite for automatic testing. [Travis](https://travis-ci.org/miloyip/rapidjson/)(for Linux) and [AppVeyor](https://ci.appveyor.com/project/miloyip/rapidjson/)(for Windows) will compile and run the unit test suite for all modifications. The test process also uses Valgrind (in Linux) to detect memory leaks.
11. Is RapidJSON well documented?
RapidJSON provides [user guide and API documentationn](http://miloyip.github.io/rapidjson/index.html).
RapidJSON provides user guide and API documentationn.
12. Are there alternatives?
......@@ -86,11 +86,11 @@
4. What is *in situ* parsing?
*in situ* parsing decodes the JSON strings directly into the input JSON. This is an optimization which can reduce memory consumption and improve performance, but the input JSON will be modified. Check [in-situ parsing](http://miloyip.github.io/rapidjson/md_doc_dom.html#InSituParsing) for details.
*in situ* parsing decodes the JSON strings directly into the input JSON. This is an optimization which can reduce memory consumption and improve performance, but the input JSON will be modified. Check [in-situ parsing](doc/dom.md) for details.
5. When does parsing generate an error?
The parser generates an error when the input JSON contains invalid syntax, or a value can not be represented (a number is too big), or the handler of parsers terminate the parsing. Check [parse error](http://miloyip.github.io/rapidjson/md_doc_dom.html#ParseError) for details.
The parser generates an error when the input JSON contains invalid syntax, or a value can not be represented (a number is too big), or the handler of parsers terminate the parsing. Check [parse error](doc/dom.md) for details.
6. What error information is provided?
......@@ -103,44 +103,127 @@
## Document/Value (DOM)
1. What is move semantics? Why?
Instead of copy semantics, move semantics is used in `Value`. That means, when assigning a source value to a target value, the ownership of source value is moved to the target value.
Since moving is faster than copying, this design decision forces user to aware of the copying overhead.
2. How to copy a value?
There are two APIs: constructor with allocator, and `CopyFrom()`. See [Deep Copy Value](doc/tutorial.md) for an example.
3. Why do I need to provide the length of string?
4. Why do I need to provide allocator in many DOM manipulation API?
Since C string is null-terminated, the length of string needs to be computed via `strlen()`, with linear runtime complexity. This incurs an unncessary overhead of many operations, if the user already knows the length of string.
Also, RapidJSON can handle `\u0000` (null character) within a string. If a string contains null characters, `strlen()` cannot return the true length of it. In such case user must provide the length of string explicitly.
4. Why do I need to provide allocator parameter in many DOM manipulation API?
Since the APIs are member functions of `Value`, we do not want to save an allocator pointer in every `Value`.
5. Does it convert between numerical types?
When using `GetInt()`, `GetUint()`, ... conversion may occur. For integer-to-integer conversion, it only convert when it is safe (otherwise it will assert). However, when converting a 64-bit signed/unsigned integer to double, it will convert but be aware that it may lose precision. A number with fraction, or an integer larger than 64-bit, can only be obtained by `GetDouble()`.
## Reader/Writer (SAX)
1. Why not just `printf` a JSON? Why need a `Writer`?
2. Why can't I parse a JSON which is just a number?
3. Can I pause the parsing process and resume it later?
1. Why don't we just `printf` a JSON? Why do we need a `Writer`?
Most importantly, `Writer` will ensure the output JSON is well-formed. Calling SAX events incorrectly (e.g. `StartObject()` pairing with `EndArray()`) will assert. Besides, `Writer` will escapes strings (e.g., `\n`). Finally, the numeric output of `printf()` may not be a valid JSON number, especially in some locale with digit delimiters. And the number-to-string conversion in `Writer` is implemented with very fast algorithms, which outperforms than `printf()` or `iostream`.
2. Can I pause the parsing process and resume it later?
This is not directly supported in the current version due to performance consideration. However, if the execution environment supports multi-threading, user can parse a JSON in a separate thread, and pause it by blocking in the input stream.
## Unicode
1. Does it support UTF-8, UTF-16 and other format?
Yes. It fully support UTF-8, UTF-16 (LE/BE), UTF-32 (LE/BE) and ASCII.
2. Can it validate the encoding?
Yes, just pass `kParseValidateEncodingFlag` to `Parse()`. If there is invalid encoding in the stream, it wil generate `kParseErrorStringInvalidEncoding` error.
3. What is surrogate pair? Does RapidJSON support it?
4. Can it handle '\u0000' (null character) in JSON string?
5. Can I output '\uxxxx' for all non-ASCII character?
JSON uses UTF-16 encoding when escaping unicode character, e.g. `\u5927` representing Chinese character "big". To handle characters other than those in basic multilingual plane (BMP), UTF-16 encodes those characters with two 16-bit values, which is called UTF-16 surrogate pair. For example, the Emoji character U+1F602 can be encoded as `\uD83D\uDE02` in JSON.
RapidJSON fully support parsing/generating UTF-16 surrogates.
4. Can it handle `\u0000` (null character) in JSON string?
Yes. RapidJSON fully support null character in JSON string. However, user need to be aware of it and using `GetStringLength()` and related APIs to obtain the true length of string.
5. Can I output `\uxxxx` for all non-ASCII character?
Yes, use `ASCII<>` as output encoding template parameter in `Writer` can enforce escaping those characters.
## Stream
1. I have a big JSON file. Should I load the whole file to memory?
User can use `FileReadStream` to read the file chunk-by-chunk. But for *in situ* parsing, the whole file must be loaded.
2. Can I parse JSON while it is streamed from network?
3. I don't know what format will the JSON be. How to handle them?
Yes. User can implement a custom stream for this. Please refer to the implementation of `FileReadStream`.
3. I don't know what encoding will the JSON be. How to handle them?
You may use `AutoUTFInputStream` which detects the encoding of input stream automatically. However, it will incur some performance overhead.
4. What is BOM? How RapidJSON handle it?
[Byte order mark (BOM)](http://en.wikipedia.org/wiki/Byte_order_mark) sometimes reside at the beginning of file/stream to indiciate the UTF encoding type of it.
RapidJSON's `EncodedInputStream` can detect/consume BOM. `EncodedOutputStream` can optionally write a BOM. See [Encoded Streams](doc/stream.md) for example.
5. Why little/big endian is related?
little/big endian of stream is an issue for UTF-16 and UTF-32 streams, but not UTF-8 stream.
## Performance
1. Is RapidJSON really fast?
Yes. It may be the fastest open source JSON library. There is a [benchmark](https://github.com/miloyip/nativejson-benchmark) for evaluating performance of C/C++ JSON libaries.
2. Why is it fast?
Many design decisions of RapidJSON is aimed at time/space performance. These may reduce user-friendliness of APIs. Besides, it also employs low-level optimizations (intrinsics, SIMD) and special algorithms (custom double-to-string, string-to-double conversions).
3. What is SIMD? How it is applied in RapidJSON?
[SIMD](http://en.wikipedia.org/wiki/SIMD) instructions can perform parallel computation in modern CPUs. RapidJSON support Intel's SSE2/SSE4.1 to accelerate whitespace skipping. This improves performance of parsing indent formatted JSON.
4. Does it consume a lot of memory?
The design of RapidJSON aims at reducing memory footprint.
In the SAX API, `Reader` consumes memory portional to maximum depth of JSON tree, plus maximum length of JSON string.
In the DOM API, each `Value` consumes exactly 16/24 bytes for 32/64-bit architecture respectively. RapidJSON also uses a special memory allocator to minimize overhead of allocations.
5. What is the purpose of being high performance?
Some applications need to process very large JSON files. Some server-side applications need to process huge amount of JSONs. Being high performance can improve both latency and throuput. In a broad sense, it will also save energy.
## Gossip
1. Who are the developers of RapidJSON?
Milo Yip (@miloyip) is the original author of RapidJSON. Many contributors from the world have improved RapidJSON. Philipp A. Hartmann (@pah) has implemented a lot of improvements, setting up automatic testing and also involves in a lot of discussions for the community. Don Ding (@thebusytypist) implemented the iterative parser. Andrii Senkovych (@jollyroger) completed the CMake migration. Kosta (@Kosta-Github) provided a very neat short-string optimization. Thank you for all other contributors and community members as well.
2. Why do you develop RapidJSON?
It was just a hobby project initially in 2011. Milo Yip is a game programmer and he just knew about JSON at that time and would like to apply JSON in future projects. As JSON seems very simple he would like to write a header-only and fast library.
3. Why there is a long empty period of development?
It is basically due to personal issues, such as getting new family members. Also, Milo Yip has spent a lot of spare time on translating "Game Engine Architecture" by Jason Gregory into Chinese.
4. Why did the repository move from Google Code to GitHub?
This is the trend. And GitHub is much more powerful and convenient.
doc/faq.zh-cn.md 0 → 100644
View file @ 9b63f39c
# 常见问题
## 一般问题
1. RapidJSON是什么？
RapidJSON是一个C++库，用于解析及生成JSON。读者可参考它的所有[特点](doc/features.zh-cn.md)。
2. 为什么称作RapidJSON？
它的灵感来自于[RapidXML](http://rapidxml.sourceforge.net/)，RapidXML是一个高速的XML DOM解析器。
3. RapidJSON与RapidXML相似么？
RapidJSON借镜了RapidXML的一些设计, 包括原位（*in situ*）解析、只有头文件的库。但两者的API是完全不同的。此外RapidJSON也提供许多RapidXML没有的特点。
4. RapidJSON是免费的么？
是的，它在MIT特許條款下免费。它可用于商业软件。详情请参看[license.txt](https://github.com/miloyip/rapidjson/blob/master/license.txt)。
5. RapidJSON很小么？它有何依赖？
是的。在Windows上，一个解析JSON并打印出统计的可执行文件少于30KB。
RapidJSON仅依赖于C++标准库。
6. 怎样安装RapidJSON？
见[安装一节](readme.zh-cn.md)。
7. RapidJSON能否运行于我的平台？
社区已在多个操作系统／编译器／CPU架构的组合上测试RapidJSON。但我们无法确保它能运行于你特定的平台上。只需要生成及执行单元测试便能获取答案。
8. RapidJSON支持C++03么？C++11呢？
RapidJSON开始时在C++03上实现。后来加入了可选的C++11特性支持（如转移构造函数、`noexcept`）。RapidJSON应该兼容所有遵从C++03或C++11的编译器。
9. RapidJSON是否真的用于实际应用？
是的。它被配置于前台及后台的真实应用中。一个社区成员说RapidJSON在他们的系统中每日解析5千万个JSON。
10. RapidJSON是如何被测试的？
RapidJSON包含一组单元测试去执行自动测试。[Travis](https://travis-ci.org/miloyip/rapidjson/)（供Linux平台）及[AppVeyor](https://ci.appveyor.com/project/miloyip/rapidjson/)（供Windows平台）会对所有修改进行编译及执行单元测试。在Linux下还会使用Valgrind去检测内存泄漏。
11. RapidJSON是否有完整的文档？
RapidJSON提供了使用手册及API说明文档。
12. 有没有其他替代品？
有许多替代品。例如nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark)列出了一些开源的C/C++ JSON库。[json.org](http://www.json.org/)也有一个列表。
## JSON
1. 什么是JSON？
JSON (JavaScript Object Notation)是一个轻量的数据交换格式。它使用人类可读的文本格式。更多关于JSON的细节可考[RFC7159](http://www.ietf.org/rfc/rfc7159.txt)及[ECMA-404](http://www.ecma-international.org/publications/standards/Ecma-404.htm)。
2. JSON有什么应用场合？
JSON常用于网页应用程序，以传送结构化数据。它也可作为文件格式用于数据持久化。
2. RapidJSON是否符合JSON标准？
是。RapidJSON完全符合[RFC7159](http://www.ietf.org/rfc/rfc7159.txt)及[ECMA-404](http://www.ecma-international.org/publications/standards/Ecma-404.htm)。它能处理一些特殊情况，例如支持JSON字符串中含有空字符及代理对（surrogate pair）。
3. RapidJSON是否支持宽松的语法？
现时不支持。RapidJSON只支持严格的标准格式。宽松语法现时在这[issue](https://github.com/miloyip/rapidjson/issues/36)中进行讨论。
## DOM与SAX
1. 什么是DOM风格API？
Document Object Model（DOM）是一个储存于内存的JSON表示方式，用于查询及修改JSON。
2. 什么是SAX风格API?
SAX是一个事件驱动的API，用于解析及生成JSON。
3. 我应用DOM还是SAX？
DOM易于查询及修改。SAX则是非常快及省内存的，但通常较难使用。
4. 什么是原位（*in situ*）解析？
原位解析会把JSON字符串直接解码至输入的JSON中。这是一个优化，可减少内存消耗及提升性能，但输入的JSON会被更改。进一步细节请参考[原位解析](doc/dom.md) 。
5. 什么时候会产生解析错误？
当输入的JSON包含非法语法，或不能表示一个值（如Number太大），或解析器的处理器中断解析过程，解析器都会产生一个错误。详情请参考[解析错误](doc/dom.md)。
6. 有什么错误信息？
错误信息存储在`ParseResult`，它包含错误代号及偏移值（从JSON开始至错误处的字符数目）。可以把错误代号翻译为人类可读的错误讯息。
7. 为可不只使用`double`去表示JSON number？
一些应用需要使用64位无号／有号整数。这些整数不能无损地转换成`double`。因此解析器会检测一个JSON number是否能转换至各种整数类型及`double`。
## Document/Value (DOM)
1. 什么是转移语意？为什么？
`Value`不用复制语意，而使用了转移语意。这是指，当把来源值赋值于目标值时，来源值的所有权会转移至目标值。
由于转移快于复制，此设计决定强迫使用者注意到复制的消耗。
2. 怎样去复制一个值？
有两个API可用：含allocator的构造函数，以及`CopyFrom()`。可参考[深复制Value](doc/tutorial.md)里的用例。
3. 为什么我需要提供字符串的长度？
由于C字符串是空字符结尾的，需要使用`strlen()`去计算其长度，这是线性复杂度的操作。若使用者已知字符串的长度，对很多操作来说会造成不必要的消耗。
此外，RapidJSON可处理含有`\u0000`（空字符）的字符串。若一个字符串含有空字符，`strlen()`便不能返回真正的字符串长度。在这种情况下使用者必须明确地提供字符串长度。
4. 为什么在许多DOM操作API中要提供分配器作为参数？
由于这些API是`Value`的成员函数，我们不希望为每个`Value`储存一个分配器指针。
5. 它会转换各种数值类型么？
当使用`GetInt()`、`GetUint()`等API时，可能会发生转换。对于整数至整数转换，仅当保证转换安全才会转换（否则会断言失败）。然而，当把一个64位有号／无号整数转换至double时，它会转换，但有可能会损失精度。含有小数的数字、或大于64位的整数，都只能使用`GetDouble()`获取其值。
## Reader/Writer (SAX)
1. 为什么不仅仅用`printf`输出一个JSON？为什么需要`Writer`？
最重要的是，`Writer`能确保输出的JSON是格式正确的。错误地调用SAX事件（如`StartObject()`错配`EndArray()`）会造成断言失败。此外，`Writer`会把字符串进行转义（如`\n`）。最后，`printf()`的数值输出可能并不是一个合法的JSON number，特别是某些locale会有数字分隔符。而且`Writer`的数值字符串转换是使用非常快的算法来实现的，胜过`printf()`及`iostream`。
2. 我能否暂停解析过程，并在稍后继续？
基于性能考虑，目前版本并不直接支持此功能。然而，若执行环境支持多线程，使用者可以在另一线程解析JSON，并通过阻塞输入流去暂停。
## Unicode
1. 它是否支持UTF-8、UTF-16及其他格式？
是。它完全支持UTF-8、UTF-16（大端／小端）、UTF-32（大端／小端）及ASCII。
2. 它能否检测编码的合法性？
能。只需把`kParseValidateEncodingFlag`参考传给`Parse()`。若发现在输入流中有非法的编码，它就会产生`kParseErrorStringInvalidEncoding`错误。
3. 什么是代理对（surrogate pair)？RapidJSON是否支持？
JSON使用UTF-16编码去转义Unicode字符，例如`\u5927`表示中文字“大”。要处理基本多文种平面（basic multilingual plane，BMP）以外的字符时，UTF-16会把那些字符编码成两个16位值，这称为UTF-16代理对。例如，绘文字字符U+1F602在JSON中可被编码成`\uD83D\uDE02`。
RapidJSON完全支持解析及生成UTF-16代理对。
4. 它能否处理JSON字符串中的`\u0000`（空字符）？
能。RapidJSON完全支持JSON字符串中的空字符。然而，使用者需要注意到这件事，并使用`GetStringLength()`及相关API去取得字符串真正长度。
5. 能否对所有非ASCII字符输出成`\uxxxx`形式？
可以。只要在`Writer`中使用`ASCII<>`作为输出编码参数，就可以强逼转义那些字符。
## 流
1. 我有一个很大的JSON文件。我应否把它整个载入内存中？
使用者可使用`FileReadStream`去逐块读入文件。但若使用于原位解析，必须载入整个文件。
2. 我能否解析一个从网络上串流进来的JSON？
可以。使用者可根据`FileReadStream`的实现，去实现一个自定义的流。
3. 我不知道一些JSON将会使用哪种编码。怎样处理它们？
你可以使用`AutoUTFInputStream`，它能自动检测输入流的编码。然而，它会带来一些性能开销。
4. 什么是BOM？RapidJSON怎样处理它？
[字节顺序标记（byte order mark, BOM）](http://en.wikipedia.org/wiki/Byte_order_mark)有时会出现于文件／流的开始，以表示其UTF编码类型。
RapidJSON的`EncodedInputStream`可检测／跳过BOM。`EncodedOutputStream`可选择是否写入BOM。可参考[编码流](doc/stream.md)中的例子。
5. 为什么会涉及大端／小端？
流的大端／小端是UTF-16及UTF-32流要处理的问题，而UTF-8不需要处理。
## 性能
1. RapidJSON是否真的快？
是。它可能是最快的开源JSON库。有一个[评测](https://github.com/miloyip/nativejson-benchmark)评估C/C++ JSON库的性能。
2. 为什么它会快？
RapidJSON的许多设计是针对时间／空间性能来设计的，这些决定可能会影响API的易用性。此外，它也使用了许多底层优化（内部函数／intrinsic、SIMD）及特别的算法（自定义的double至字符串转换、字符串至double的转换）。
3. 什是是SIMD？它如何用于RapidJSON？
[SIMD](http://en.wikipedia.org/wiki/SIMD)指令可以在现代CPU中执行并行运算。RapidJSON支持了Intel的SSE2/SSE4.1去加速跳过空白字符。在解析含缩进的JSON时，这能提升性能。
4. 它会消耗许多内存么？
RapidJSON的设计目标是减低内存占用。
在SAX API中，`Reader`消耗的内存与JSON树深度加上最长JSON字符成正比。
在DOM API中，每个`Value`在32/64位架构下分别消耗16/24字节。RapidJSON也使用一个特殊的内存分配器去减少分配的额外开销。
5. 高性能的意义何在？
有些应用程序需要处理非常大的JSON文件。而有些后台应用程序需要处理大量的JSON。达到高性能同时改善延时及吞吐量。更广义来说，这也可以节省能源。
## 八挂
1. 谁是RapidJSON的开发者？
叶劲峰（Milo Yip，@miloyip）是RapidJSON的原作者。全世界许多贡献者一直在改善RapidJSON。Philipp A. Hartmann（@pah）实现了许多改进，也设置了自动化测试，而且还参与许多社区讨论。丁欧南（Don Ding，@thebusytypist）实现了迭代式解析器。Andrii Senkovych（@jollyroger）完成了向CMake的迁移。Kosta（@Kosta-Github）提供了一个非常灵巧的短字符串优化。也需要感谢其他献者及社区成员。
2. 为何你要开发RapidJSON？
在2011年开始这项目是，它仅一个兴趣项目。Milo Yip是一个游戏程序员，他在那时候认识到JSON并希望在未来的项目中使用。由于JSON好像很简单，他希望写一个仅有头文件并且快速的程序库。
3. 为什么开发中段有一段长期空档？
主要是个人因素，例如加入新家庭成员。另外，Milo Yip也花了许多业馀时间去翻译Jason Gregory的《Game Engine Architecture》至中文版《游戏引擎架构》。
4. 为什么这个项目从Google Code搬到GitHub？
这是大势所趋，而且GitHub更为强大及方便。
doc/features.zh-cn.md 0 → 100644
View file @ 9b63f39c
# 特点
## 总体
* 跨平台
* 编译器：Visual Studio、gcc、clang等
* 架构：x86、x64、ARM等
* 操作系统：Windows、Mac OS X、Linux、iOS、Android等
* 容易安装
* 只有头文件的库。只需把头文件复制至你的项目中。
* 独立、最小依赖
* 不需依赖STL、BOOST等。
* 只包含`<cstdio>`, `<cstdlib>`, `<cstring>`, `<inttypes.h>`, `<new>`, `<stdint.h>`。
* 没使用C++异常、RTTI
* 高性能
* 使用模版及内联函数去降低函数调用开销。
* 内部经优化的Grisu2及浮点数解析实现。
* 可选的SSE2/SSE4.1支持。
## 符合标准
* RapidJSON应完全符合RFC4627/ECMA-404标准。
* 支持Unicod代理对（surrogate pair）。
* 支持空字符（`"\u0000"`）。
* 例如，可以优雅地解析及处理`["Hello\u0000World"]`。含读写字符串长度的API。
## Unicode
* 支持UTF-8、UTF-16、UTF-32编码，包括小端序和大端序。
* 这些编码用于输入输出流，以及内存中的表示。
* 支持从输入流自动检测编码。
* 内部支持编码的转换。
* 例如，你可以读取一个UTF-8文件，让RapidJSON把JSON字符串转换至UTF-16的DOM。
* 内部支持编码校验。
* 例如，你可以读取一个UTF-8文件，让RapidJSON检查是否所有JSON字符串是合法的UTF-8字节序列。
* 支持自定义的字符类型。
* 预设的字符类型是：UTF-8为`char`，UTF-16为`wchar_t`，UTF32为`uint32_t`。
* 支持自定义的编码。
## API风格
* SAX（Simple API for XML）风格API
* 类似于[SAX](http://en.wikipedia.org/wiki/Simple_API_for_XML), RapidJSON提供一个事件循序访问的解析器API（`rapidjson::GenericReader`）。RapidJSON也提供一个生成器API（`rapidjson::Writer`），可以处理相同的事件集合。
* DOM（Document Object Model）风格API
* 类似于HTML／XML的[DOM](http://en.wikipedia.org/wiki/Document_Object_Model)，RapidJSON可把JSON解析至一个DOM表示方式（`rapidjson::GenericDocument`），以方便操作。如有需要，可把DOM转换（stringify）回JSON。
* DOM风格API（`rapidjson::GenericDocument`）实际上是由SAX风格API（`rapidjson::GenericReader`）实现的。SAX更快，但有时DOM更易用。用户可根据情况作出选择。
## 解析
* 递归式（预设）及迭代式解析器
* 递归式解析器较快，但在极端情况下可出现堆栈溢出。
* 迭代式解析器使用自定义的堆栈去维持解析状态。
* 支持原位（*in situ*）解析。
* 把JSON字符串的值解析至原JSON之中，然后让DOM指向那些字符串。
* 比常规分析更快：不需字符串的内存分配、不需复制（如字符串不含转义符）、缓存友好。
* 对于JSON数字类型，支持32-bit/64-bit的有号／无号整数，以及`double`。
* 错误处理
* 支持详尽的解析错误代号。
* 支持本地化错误信息。
## DOM (Document)
* RapidJSON在类型转换时会检查数值的范围。
* 字符串字面量的优化
* 只储存指针，不作复制
* 优化“短”字符串
* 在`Value`内储存短字符串，无需额外分配。
* 对UTF-8字符串来说，32位架构下可存储最多11字符，64位下15字符。
* 可选地支持`std::string`（定义`RAPIDJSON_HAS_STDSTRING=1`）
## 生成
* 支持`rapidjson::PrettyWriter`去加入换行及缩进。
## 输入输出流
* 支持`rapidjson::GenericStringBuffer`，把输出的JSON储存于字符串内。
* 支持`rapidjson::FileReadStream`及`rapidjson::FileWriteStream`，使用`FILE`对象作输入输出。
* 支持自定义输入输出流。
## 内存
* 最小化DOM的内存开销。
* 对大部分32／64位机器而言，每个JSON值只占16或20字节（不包含字符串）。
* 支持快速的预设分配器。
* 它是一个堆栈形式的分配器（顺序分配，不容许单独释放，适合解析过程之用）。
* 使用者也可提供一个预分配的缓冲区。（有可能达至无需CRT分配就能解析多个JSON）
* 支持标准CRT（C-runtime）分配器。
* 支持自定义分配器。
## 其他
* 一些C++11的支持（可选）
* 右值引用（rvalue reference）
* `noexcept`修饰符
doc/internals.md
View file @ 9b63f39c
......@@ -4,24 +4,234 @@ This section records some design and implementation details.
[TOC]
# Architecture {#Architecture}
## SAX and DOM
The basic relationships of SAX and DOM is shown in the following UML diagram.
![Architecture UML class diagram](diagram/architecture.png)
The core of the relationship is the `Handler` concept. From the SAX side, `Reader` parses a JSON from a stream and publish events to a `Handler`. `Writer` implements the `Handler` concept to handle the same set of events. From the DOM side, `Document` implements the `Handler` concept to build a DOM according to the events. `Value` supports a `Value::Accept(Handler&)` function, which traverses the DOM to publish events.
With this design, SAX is not dependent on DOM. Even `Reader` and `Writer` have no dependencies between them. This provides flexibility to chain event publisher and handlers. Besides, `Value` does not depends on SAX as well. So, in addition to stringify a DOM to JSON, user may also stringify it to a XML writer, or do anything else.
## Utility Classes
Both SAX and DOM APIs depends on 3 additional concepts: `Allocator`, `Encoding` and `Stream`. Their inheritance hierarchy is shown as below.
![Utility classes UML class diagram](diagram/utilityclass.png)
# Value {#Value}
`Value` (actually a typedef of `GenericValue<UTF8<>>`) is the core of DOM API. This section describes the design of it.
## Data Layout {#DataLayout}
`Value` is a [variant type](http://en.wikipedia.org/wiki/Variant_type). In RapidJSON's context, an instance of `Value` can contain 1 of 6 JSON value types. This is possble by using `union`. Each `Value` contains two members: `union Data data_` and a`unsigned flags_`. The `flags_` indiciates the JSON type, and also additional information.
The following tables show the data layout of each type. The 32-bit/64-bit columns indicates the size of the field in bytes.
| Null | |32-bit|64-bit|
|-------------------|----------------------------------|:----:|:----:|
| (unused) | |4 |8 |
| (unused) | |4 |4 |
| (unused) | |4 |4 |
| `unsigned flags_` | `kNullType | kNullFlag` |4 |4 |
| Bool | |32-bit|64-bit|
|-------------------|----------------------------------------------------|:----:|:----:|
| (unused) | |4 |8 |
| (unused) | |4 |4 |
| (unused) | |4 |4 |
| `unsigned flags_` | `kBoolType | `(either `kTrueFlag` or `kFalseFlag`) |4 |4 |
| String | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `Ch* str` | Pointer to the string (may own) |4 |8 |
| `SizeType length` | Length of string |4 |4 |
| (unused) | |4 |4 |
| `unsigned flags_` | `kStringType | kStringFlag | ...` |4 |4 |
| Object | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `Member* members` | Pointer to array of members (owned) |4 |8 |
| `SizeType size` | Number of members |4 |4 |
| `SizeType capacity` | Capacity of members |4 |4 |
| `unsigned flags_` | `kObjectType | kObjectFlag` |4 |4 |
| Array | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `Value* values` | Pointer to array of values (owned) |4 |8 |
| `SizeType size` | Number of values |4 |4 |
| `SizeType capacity` | Capacity of values |4 |4 |
| `unsigned flags_` | `kArrayType | kArrayFlag` |4 |4 |
| Number (Int) | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `int i` | 32-bit signed integer |4 |4 |
| (zero padding) | 0 |4 |4 |
| (unused) | |4 |8 |
| `unsigned flags_` | `kNumberType | kNumberFlag | kIntFlag | kInt64Flag | ...` |4 |4 |
| Number (UInt) | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `unsigned u` | 32-bit unsigned integer |4 |4 |
| (zero padding) | 0 |4 |4 |
| (unused) | |4 |8 |
| `unsigned flags_` | `kNumberType | kNumberFlag | kUIntFlag | kUInt64Flag | ...` |4 |4 |
| Number (Int64) | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `int64_t i64` | 64-bit signed integer |8 |8 |
| (unused) | |4 |8 |
| `unsigned flags_` | `kNumberType | kNumberFlag | kInt64Flag | ...` |4 |4 |
| Number (Uint64) | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `uint64_t i64` | 64-bit unsigned integer |8 |8 |
| (unused) | |4 |8 |
| `unsigned flags_` | `kNumberType | kNumberFlag | kInt64Flag | ...` |4 |4 |
| Number (Double) | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `uint64_t i64` | Double precision floating-point |8 |8 |
| (unused) | |4 |8 |
| `unsigned flags_` | `kNumberType | kNumberFlag | kDoubleFlag` |4 |4 |
Here are some notes:
* To reduce memory consumption for 64-bit architecture, `SizeType` is typedef as `unsigned` instead of `size_t`.
* Zero padding for 32-bit number may be placed after or before the actual type, according to the endianess. This makes possible for interpreting a 32-bit integer as a 64-bit integer, without any conversion.
* An `Int` is always an `Int64`, but the converse is not always true.
## Flags {#Flags}
The 32-bit `flags_` contains both JSON type and other additional information. As shown in the above tables, each JSON type contains redundant `kXXXType` and `kXXXFlag`. This design is for optimizing the operation of testing bit-flags (`IsNumber()`) and obtaining a sequental number for each type (`GetType()`).
String has two optional flags. `kCopyFlag` means that the string owns a copy of the string. `kInlineStrFlag` means using [Short-String Optimizatoin](#ShortString).
Number is a bit more complicated. For normal integer values, it can contains `kIntFlag`, `kUintFlag`, `kInt64Flag` and/or `kUint64Flag`, according to the range of the integer. For numbers with fraction, and integers larger than 64-bit range, they will be stored as `double` with `kDoubleFlag`.
## Short-String Optimization {#ShortString}
Kosta (@Kosta-Github) provided a very neat short-string optimization. The optimization idea is given as follow. Excluding the `flags_`, a `Value` has 12 or 16 bytes (32-bit or 64-bit) for storing actual data. Instead of storing a pointer to a string, it is possible to store short strings in these space internally. For encoding with 1-byte character type (e.g. `char`), it can store maxium 11 or 15 characters string inside the `Value` type.
| ShortString (Ch=char) | |32-bit|64-bit|
|---------------------|-------------------------------------|:----:|:----:|
| `Ch str[MaxChars]` | String buffer |11 |15 |
| `Ch invLength` | MaxChars - Length |1 |1 |
| `unsigned flags_` | `kStringType | kStringFlag | ...` |4 |4 |
A special technique is applied. Instead of storing the length of string directly, it stores (MaxChars - length). This make it possible to store 11 characters with trailing `\0`.
This optimization can reduce memory usage for copy-string. It can also improve cache-coherence thus improve runtime performance.
# Allocator {#Allocator}
`Allocator` is a concept in RapidJSON:
~~~cpp
concept Allocator {
static const bool kNeedFree; //!< Whether this allocator needs to call Free().
// Allocate a memory block.
// \param size of the memory block in bytes.
// \returns pointer to the memory block.
void* Malloc(size_t size);
// Resize a memory block.
// \param originalPtr The pointer to current memory block. Null pointer is permitted.
// \param originalSize The current size in bytes. (Design issue: since some allocator may not book-keep this, explicitly pass to it can save memory.)
// \param newSize the new size in bytes.
void* Realloc(void* originalPtr, size_t originalSize, size_t newSize);
// Free a memory block.
// \param pointer to the memory block. Null pointer is permitted.
static void Free(void *ptr);
};
~~~
Note that `Malloc()` and `Realloc()` are member functions but `Free()` is static member function.
## MemoryPoolAllocator {#MemoryPoolAllocator}
`MemoryPoolAllocator` is the default allocator for DOM. It allocate but do not free memory. This is suitable for building a DOM tree.
Internally, it allocates chunks of memory from the base allocator (by default `CrtAllocator`) and stores the chunks as a singly linked list. When user requests an allocation, it allocates memory from the following order:
1. User supplied buffer if it is available. (See [User Buffer section in DOM](dom.md))
2. If user supplied buffer is full, use the current memory chunk.
3. If the current block is full, allocate a new block of memory.
# Parsing Optimization {#ParsingOptimization}
## Skip Whitespace with SIMD {#SkipwhitespaceWithSIMD}
## Skip Whitespaces with SIMD {#SkipwhitespaceWithSIMD}
When parsing JSON from a stream, the parser need to skip 4 whitespace characters:
1. Space (`U+0020`)
2. Character Tabulation (`U+000B`)
3. Line Feed (`U+000A`)
4. Carriage Return (`U+000D`)
A simple implementation will be simply:
~~~cpp
void SkipWhitespace(InputStream& s) {
while (s.Peek() == ' ' || s.Peek() == '\n' || s.Peek() == '\r' || s.Peek() == '\t')
s.Take();
}
~~~
## Pow10() {#Pow10}
However, this requires 4 comparisons and a few branching for each character. This was found to be a hot spot.
To accelerate this process, SIMD was applied to compare 16 characters with 4 white spaces for each iteration. Currently RapidJSON only supports SSE2 and SSE4.1 instructions for this. And it is only activated for UTF-8 memory streams, including string stream or *in situ* parsing.
## Local Stream Copy {#LocalStreamCopy}
During optimization, it is found that some compilers cannot localize some member data access of streams into local variables or registers. Experimental results show that for some stream types, making a copy of the stream and used it in inner-loop can improve performance. For example, the actual (non-SIMD) implementation of `SkipWhitespace()` is implemented as:
~~~cpp
template<typename InputStream>
void SkipWhitespace(InputStream& is) {
internal::StreamLocalCopy<InputStream> copy(is);
InputStream& s(copy.s);
while (s.Peek() == ' ' || s.Peek() == '\n' || s.Peek() == '\r' || s.Peek() == '\t')
s.Take();
}
~~~
Depending on the traits of stream, `StreamLocalCopy` will make (or not make) a copy of the stream object, use it locally and copy the states of stream back to the original stream.
## Parsing to Double {#ParsingDouble}
Parsing string into `double` is difficult. The standard library function `strtod()` can do the job but it is slow. By default, the parsers use normal precision setting. This has has maximum 3 [ULP](http://en.wikipedia.org/wiki/Unit_in_the_last_place) error and implemented in `internal::StrtodNormalPrecision()`.
When using `kParseFullPrecisionFlag`, the parsers calls `internal::StrtodFullPrecision()` instead, and this function actually implemented 3 versions of conversion methods.
1. [Fast-Path](http://www.exploringbinary.com/fast-path-decimal-to-floating-point-conversion/).
2. Custom DIY-FP implementation as in [double-conversion](https://github.com/floitsch/double-conversion).
3. Big Integer Method as in (Clinger, William D. How to read floating point numbers accurately. Vol. 25. No. 6. ACM, 1990).
If the first conversion methods fail, it will try the second, and so on.
# Generation Optimizatoin {#GenerationOptimization}
## Integer-to-String conversion {#itoa}
The naive algorithm for integer-to-string conversion involves division per each decimal digit. We have implemented various implementations and evaluated them in [itoa-benchmark](https://github.com/miloyip/itoa-benchmark).
Although SSE2 version is the fastest but the difference is minor by comparing to the first running-up `branchlut`. And `branchlut` is pure C++ implementation so we adopt `branchlut` in RapidJSON.
## Double-to-String conversion {#dtoa}
Originally RapidJSON uses `snprintf(..., ..., "%g")` to achieve double-to-string conversion. This is not accurate as the default precision is 6. Later we also find that this is slow and there is an alternative.
Google's V8 [double-conversion](https://github.com/floitsch/double-conversion
) implemented a newer, fast algorithm called Grisu3 (Loitsch, Florian. "Printing floating-point numbers quickly and accurately with integers." ACM Sigplan Notices 45.6 (2010): 233-243.).
However, since it is not header-only so that we implemented a header-only version of Grisu2. This algorithm guarantees that the result is always accurate. And in most of cases it produces the shortest (optimal) string representation.
The header-only conversion function has been evaluated in [dtoa-benchmark](https://github.com/miloyip/dtoa-benchmark).
# Parser {#Parser}
## Iterative Parser {#IterativeParser}
......
doc/performance.md
View file @ 9b63f39c
# Performance
The old performance article for RapidJSON 0.1 is provided [here](https://code.google.com/p/rapidjson/wiki/Performance).
The (third-party) performance tests have been removed from this repository
and are now part of a dedicated [native JSON benchmark collection] [1].
This file will be updated with a summary of benchmarking results based on
the above benchmark collection in the future.
There is a [native JSON benchmark collection] [1] which evaluates speed, memory usage and code size of various operations among 20 JSON libaries.
[1]: https://github.com/miloyip/nativejson-benchmark
The old performance article for RapidJSON 0.1 is provided [here](https://code.google.com/p/rapidjson/wiki/Performance).
Additionally, you may refer to the following third-party benchmarks.
## Third-party benchmarks
......
doc/performance.zh-cn.md 0 → 100644
View file @ 9b63f39c
# 性能
有一个[native JSON benchmark collection][1]项目，能评估20个JSON库在不同操作下的速度、內存用量及代码大小。
[1]: https://github.com/miloyip/nativejson-benchmark
RapidJSON 0.1版本的性能测试文章位于[这里](https://code.google.com/p/rapidjson/wiki/Performance).
此外，你也可以参考以下这些第三方的评测。
## 第三方评测
* [Basic benchmarks for miscellaneous C++ JSON parsers and generators](https://github.com/mloskot/json_benchmark) by Mateusz Loskot (Jun 2013)
* [casablanca](https://casablanca.codeplex.com/)
* [json_spirit](https://github.com/cierelabs/json_spirit)
* [jsoncpp](http://jsoncpp.sourceforge.net/)
* [libjson](http://sourceforge.net/projects/libjson/)
* [rapidjson](https://github.com/miloyip/rapidjson/)
* [QJsonDocument](http://qt-project.org/doc/qt-5.0/qtcore/qjsondocument.html)
* [JSON Parser Benchmarking](http://chadaustin.me/2013/01/json-parser-benchmarking/) by Chad Austin (Jan 2013)
* [sajson](https://github.com/chadaustin/sajson)
* [rapidjson](https://github.com/miloyip/rapidjson/)
* [vjson](https://code.google.com/p/vjson/)
* [YAJL](http://lloyd.github.com/yajl/)
* [Jansson](http://www.digip.org/jansson/)
doc/sax.zh-cn.md 0 → 100644
View file @ 9b63f39c
# SAX
"SAX"此术语源于[Simple API for XML](http://en.wikipedia.org/wiki/Simple_API_for_XML)。我们借了此术语去套用在JSON的解析及生成。
在RapidJSON中，`Reader`（`GenericReader<...>`的typedef）是JSON的SAX风格解析器，而`Writer`（`GenericWriter<...>`的typedef）则是JSON的SAX风格生成器。
[TOC]
# Reader {#Reader}
`Reader`从输入流解析一个JSON。当它从流中读取字符时，它会基于JSON的语法去分析字符，并向处理器发送事件。
例如，以下是一个JSON。
~~~~~~~~~~js
{
"hello": "world",
"t": true ,
"f": false,
"n": null,
"i": 123,
"pi": 3.1416,
"a": [1, 2, 3, 4]
}
~~~~~~~~~~
当一个`Reader`解析此JSON时，它会顺序地向处理器发送以下的事件：
~~~~~~~~~~
StartObject()
Key("hello", 5, true)
String("world", 5, true)
Key("t", 1, true)
Bool(true)
Key("f", 1, true)
Bool(false)
Key("n", 1, true)
Null()
Key("i")
UInt(123)
Key("pi")
Double(3.1416)
Key("a")
StartArray()
Uint(1)
Uint(2)
Uint(3)
Uint(4)
EndArray(4)
EndObject(7)
~~~~~~~~~~
除了一些事件参数需要再作解释，这些事件可以轻松地与JSON对上。我们可以看看`simplereader`例子怎样产生和以上完全相同的结果：
~~~~~~~~~~cpp
#include "rapidjson/reader.h"
#include <iostream>
using namespace rapidjson;
using namespace std;
struct MyHandler {
bool Null() { cout << "Null()" << endl; return true; }
bool Bool(bool b) { cout << "Bool(" << boolalpha << b << ")" << endl; return true; }
bool Int(int i) { cout << "Int(" << i << ")" << endl; return true; }
bool Uint(unsigned u) { cout << "Uint(" << u << ")" << endl; return true; }
bool Int64(int64_t i) { cout << "Int64(" << i << ")" << endl; return true; }
bool Uint64(uint64_t u) { cout << "Uint64(" << u << ")" << endl; return true; }
bool Double(double d) { cout << "Double(" << d << ")" << endl; return true; }
bool String(const char* str, SizeType length, bool copy) {
cout << "String(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl;
return true;
}
bool StartObject() { cout << "StartObject()" << endl; return true; }
bool Key(const char* str, SizeType length, bool copy) {
cout << "Key(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl;
return true;
}
bool EndObject(SizeType memberCount) { cout << "EndObject(" << memberCount << ")" << endl; return true; }
bool StartArray() { cout << "StartArray()" << endl; return true; }
bool EndArray(SizeType elementCount) { cout << "EndArray(" << elementCount << ")" << endl; return true; }
};
void main() {
const char json[] = " { \"hello\" : \"world\", \"t\" : true , \"f\" : false, \"n\": null, \"i\":123, \"pi\": 3.1416, \"a\":[1, 2, 3, 4] } ";
MyHandler handler;
Reader reader;
StringStream ss(json);
reader.Parse(ss, handler);
}
~~~~~~~~~~
注意RapidJSON使用模板去静态挷定`Reader`类型及处理器的类形，而不是使用含虚函数的类。这个范式可以通过把函数内联而改善性能。
## 处理器 {#Handler}
如前例所示，使用者需要实现一个处理器（handler），用于处理来自`Reader`的事件（函数调用）。处理器必须包含以下的成员函数。
~~~~~~~~~~cpp
class Handler {
bool Null();
bool Bool(bool b);
bool Int(int i);
bool Uint(unsigned i);
bool Int64(int64_t i);
bool Uint64(uint64_t i);
bool Double(double d);
bool String(const Ch* str, SizeType length, bool copy);
bool StartObject();
bool Key(const Ch* str, SizeType length, bool copy);
bool EndObject(SizeType memberCount);
bool StartArray();
bool EndArray(SizeType elementCount);
};
~~~~~~~~~~
当`Reader`遇到JSON null值时会调用`Null()`。
当`Reader`遇到JSON true或false值时会调用`Bool(bool)`。
当`Reader`遇到JSON number，它会选择一个合适的C++类型映射，然后调用`Int(int)`、`Uint(unsigned)`、`Int64(int64_t)`、`Uint64(uint64_t)`及`Double(double)`的*其中之一个*。
当`Reader`遇到JSON string，它会调用`String(const char* str, SizeType length, bool copy)`。第一个参数是字符串的指针。第二个参数是字符串的长度（不包含空终止符号）。注意RapidJSON支持字串中含有空字符`'\0'`。若出现这种情况，便会有`strlen(str) < length`。最后的`copy`参数表示处理器是否需要复制该字符串。在正常解析时，`copy = true`。仅当使用原位解析时，`copy = false`。此外，还要注意字符的类型与目标编码相关，我们稍后会再谈这一点。
当`Reader`遇到JSON object的开始之时，它会调用`StartObject()`。JSON的object是一个键值对（成员）的集合。若object包含成员，它会先为成员的名字调用`Key()`，然后再按值的类型调用函数。它不断调用这些键值对，直至最终调用`EndObject(SizeType memberCount)`。注意`memberCount`参数对处理器来说只是协助性质，使用者可能不需要此参数。
JSON array与object相似，但更简单。在array开始时，`Reader`会调用`BeginArary()`。若array含有元素，它会按元素的类型来读用函数。相似地，最后它会调用`EndArray(SizeType elementCount)`，其中`elementCount`参数对处理器来说只是协助性质。
每个处理器函数都返回一个`bool`。正常它们应返回`true`。若处理器遇到错误，它可以返回`false`去通知事件发送方停止继续处理。
例如，当我们用`Reader`解析一个JSON时，处理器检测到该JSON并不符合所需的schema，那么处理器可以返回`false`，令`Reader`停止之后的解析工作。而`Reader`会进入一个错误状态，并以`kParseErrorTermination`错误码标识。
## GenericReader {#GenericReader}
前面提及，`Reader`是`GenericReader`模板类的typedef：
~~~~~~~~~~cpp
namespace rapidjson {
template <typename SourceEncoding, typename TargetEncoding, typename Allocator = MemoryPoolAllocator<> >
class GenericReader {
// ...
};
typedef GenericReader<UTF8<>, UTF8<> > Reader;
} // namespace rapidjson
~~~~~~~~~~
`Reader`使用UTF-8作为来源及目标编码。来源编码是指JSON流的编码。目标编码是指`String()`的`str`参数所用的编码。例如，要解析一个UTF-8流并输出至UTF-16 string事件，你需要这么定义一个reader：
~~~~~~~~~~cpp
GenericReader<UTF8<>, UTF16<> > reader;
~~~~~~~~~~
注意到`UTF16`的缺省类型是`wchar_t`。因此这个`reader`需要调用处理器的`String(const wchar_t*, SizeType, bool)`。
第三个模板参数`Allocator`是内部数据结构（实际上是一个堆栈）的分配器类型。
## 解析 {#Parsing}
`Reader`的唯一功能就是解析JSON。
~~~~~~~~~~cpp
template <unsigned parseFlags, typename InputStream, typename Handler>
bool Parse(InputStream& is, Handler& handler);
// 使用 parseFlags = kDefaultParseFlags
template <typename InputStream, typename Handler>
bool Parse(InputStream& is, Handler& handler);
~~~~~~~~~~
若在解析中出现错误，它会返回`false`。使用者可调用`bool HasParseEror()`, `ParseErrorCode GetParseErrorCode()`及`size_t GetErrorOffset()`获取错误状态。实际上`Document`使用这些`Reader`函数去获取解析错误。请参考[DOM](doc/dom.md)去了解有关解析错误的细节。
# Writer {#Writer}
`Reader`把JSON转换（解析）成为事件。`Writer`完全做相反的事情。它把事件转换成JSON。
`Writer`是非常容易使用的。若你的应用程序只需把一些数据转换成JSON，可能直接使用`Writer`，会比建立一个`Document`然后用`Writer`把它转换成JSON更加方便。
在`simplewriter`例子里，我们做`simplereader`完全相反的事情。
~~~~~~~~~~cpp
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>
using namespace rapidjson;
using namespace std;
void main() {
StringBuffer s;
Writer<StringBuffer> writer(s);
writer.StartObject();
writer.Key("hello");
writer.String("world");
writer.Key("t");
writer.Bool(true);
writer.Key("f");
writer.Bool(false);
writer.Key("n");
writer.Null();
writer.Key("i");
writer.Uint(123);
writer.Key("pi");
writer.Double(3.1416);
writer.Key("a");
writer.StartArray();
for (unsigned i = 0; i < 4; i++)
writer.Uint(i);
writer.EndArray();
writer.EndObject();
cout << s.GetString() << endl;
}
~~~~~~~~~~
~~~~~~~~~~
{"hello":"world","t":true,"f":false,"n":null,"i":123,"pi":3.1416,"a":[0,1,2,3]}
~~~~~~~~~~
`String()`及`Key()`各有两个重载。一个是如处理器concept般，有3个参数。它能处理含空字符的字符串。另一个是如上中使用的较简单版本。
注意到，例子代码中的`EndArray()`及`EndObject()`并没有参数。可以传递一个`SizeType`的参数，但它会被`Writer`忽略。
你可能会怀疑，为什么不使用`sprintf()`或`std::stringstream`去建立一个JSON？
这有几个原因：
1. `Writer`必然会输出一个结构良好（well-formed）的JSON。若然有错误的事件次序（如`Int()`紧随`StartObject()`出现），它会在调试模式中产生断言失败。
2. `Writer::String()`可处理字符串转义（如把码点`U+000A`转换成`\n`）及进行Unicode转码。
3. `Writer`一致地处理number的输出。
4. `Writer`实现了事件处理器concept。可用于处理来自`Reader`、`Document`或其他事件发生器。
5. `Writer`可对不同平台进行优化。
无论如何，使用`Writer` API去生成JSON甚至乎比这些临时方法更简单。
## 模板 {#WriterTemplate}
`Writer`与`Reader`有少许设计区别。`Writer`是一个模板类，而不是一个typedef。 并没有`GenericWriter`。以下是`Writer`的声明。
~~~~~~~~~~cpp
namespace rapidjson {
template<typename OutputStream, typename SourceEncoding = UTF8<>, typename TargetEncoding = UTF8<>, typename Allocator = CrtAllocator<> >
class Writer {
public:
Writer(OutputStream& os, Allocator* allocator = 0, size_t levelDepth = kDefaultLevelDepth)
// ...
};
} // namespace rapidjson
~~~~~~~~~~
`OutputStream`模板参数是输出流的类型。它的类型不可以被自动推断，必须由使用者提供。
`SourceEncoding`模板参数指定了`String(const Ch*, ...)`的编码。
`TargetEncoding`模板参数指定输出流的编码。
最后一个`Allocator`是分配器的类型，用于分配内部数据结构（一个堆栈）。
此外，`Writer`的构造函数有一`levelDepth`参数。存储每层阶信息的初始内存分配量受此参数影响。
## PrettyWriter {#PrettyWriter}
`Writer`所输出的是没有空格字符的最紧凑JSON，适合网络传输或储存，但就适合人类阅读。
因此，RapidJSON提供了一个`PrettyWriter`，它在输出中加入缩进及换行。
`PrettyWriter`的用法与`Writer`几乎一样，不同之处是`PrettyWriter`提供了一个`SetIndent(Ch indentChar, unsigned indentCharCount)`函数。缺省的缩进是4个空格。
## 完整性及重置 {#CompletenessReset}
一个`Writer`只可输出单个JSON，其根节点可以是任何JSON类型。当处理完单个根节点事件（如`String()`），或匹配的最后`EndObject()`或`EndArray()`事件，输出的JSON是结构完整（well-formed）及完整的。使用者可调用`Writer::IsComplete()`去检测完整性。
当JSON完整时，`Writer`不能再接受新的事件。不然其输出便会是不合法的（例如有超过一个根节点）。为了重新利用`Writer`对象，使用者可调用`Writer::Reset(OutputStream& os)`去重置其所有内部状态及设置新的输出流。
# 技巧 {#Techniques}
## 解析JSON至自定义结构 {#CustomDataStructure}
`Document`的解析功能完全依靠`Reader`。实际上`Document`是一个处理器，在解析JSON时接收事件去建立一个DOM。
使用者可以直接使用`Reader`去建立其他数据结构。这消除了建立DOM的步骤，从而减少了内存开销并改善性能。
在以下的`messagereader`例子中，`ParseMessages()`解析一个JSON，该JSON应该是一个含键值对的object。
~~~~~~~~~~cpp
#include "rapidjson/reader.h"
#include "rapidjson/error/en.h"
#include <iostream>
#include <string>
#include <map>
using namespace std;
using namespace rapidjson;
typedef map<string, string> MessageMap;
struct MessageHandler
: public BaseReaderHandler<UTF8<>, MessageHandler> {
MessageHandler() : state_(kExpectObjectStart) {
}
bool StartObject() {
switch (state_) {
case kExpectObjectStart:
state_ = kExpectNameOrObjectEnd;
return true;
default:
return false;
}
}
bool String(const char* str, SizeType length, bool) {
switch (state_) {
case kExpectNameOrObjectEnd:
name_ = string(str, length);
state_ = kExpectValue;
return true;
case kExpectValue:
messages_.insert(MessageMap::value_type(name_, string(str, length)));
state_ = kExpectNameOrObjectEnd;
return true;
default:
return false;
}
}
bool EndObject(SizeType) { return state_ == kExpectNameOrObjectEnd; }
bool Default() { return false; } // All other events are invalid.
MessageMap messages_;
enum State {
kExpectObjectStart,
kExpectNameOrObjectEnd,
kExpectValue,
}state_;
std::string name_;
};
void ParseMessages(const char* json, MessageMap& messages) {
Reader reader;
MessageHandler handler;
StringStream ss(json);
if (reader.Parse(ss, handler))
messages.swap(handler.messages_); // Only change it if success.
else {
ParseErrorCode e = reader.GetParseErrorCode();
size_t o = reader.GetErrorOffset();
cout << "Error: " << GetParseError_En(e) << endl;;
cout << " at offset " << o << " near '" << string(json).substr(o, 10) << "...'" << endl;
}
}
int main() {
MessageMap messages;
const char* json1 = "{ \"greeting\" : \"Hello!\", \"farewell\" : \"bye-bye!\" }";
cout << json1 << endl;
ParseMessages(json1, messages);
for (MessageMap::const_iterator itr = messages.begin(); itr != messages.end(); ++itr)
cout << itr->first << ": " << itr->second << endl;
cout << endl << "Parse a JSON with invalid schema." << endl;
const char* json2 = "{ \"greeting\" : \"Hello!\", \"farewell\" : \"bye-bye!\", \"foo\" : {} }";
cout << json2 << endl;
ParseMessages(json2, messages);
return 0;
}
~~~~~~~~~~
~~~~~~~~~~
{ "greeting" : "Hello!", "farewell" : "bye-bye!" }
farewell: bye-bye!
greeting: Hello!
Parse a JSON with invalid schema.
{ "greeting" : "Hello!", "farewell" : "bye-bye!", "foo" : {} }
Error: Terminate parsing due to Handler error.
at offset 59 near '} }...'
~~~~~~~~~~
第一个JSON（`json1`）被成功地解析至`MessageMap`。由于`MessageMap`是一个`std::map`，列印次序按键值排序。此次序与JSON中的次序不同。
在第二个JSON（`json2`）中，`foo`的值是一个空object。由于它是一个object，`MessageHandler::StartObject()`会被调用。然而，在`state_ = kExpectValue`的情况下，该函数会返回`false`，并令到解析过程终止。错误代码是`kParseErrorTermination`。
## 过滤JSON {#Filtering}
如前面提及过，`Writer`可处理`Reader`发出的事件。`condense`例子简单地设置`Writer`作为一个`Reader`的处理器，因此它能移除JSON中的所有空白字符。`pretty`例子使用同样的关系，只是以`PrettyWriter`取代`Writer`。因此`pretty`能够重新格式化JSON，加入缩进及换行。
实际上，我们可以使用SAX风格API去加入（多个）中间层去过滤JSON的内容。例如`capitalize`例子可以把所有JSON string改为大写。
~~~~~~~~~~cpp
#include "rapidjson/reader.h"
#include "rapidjson/writer.h"
#include "rapidjson/filereadstream.h"
#include "rapidjson/filewritestream.h"
#include "rapidjson/error/en.h"
#include <vector>
#include <cctype>
using namespace rapidjson;
template<typename OutputHandler>
struct CapitalizeFilter {
CapitalizeFilter(OutputHandler& out) : out_(out), buffer_() {
}
bool Null() { return out_.Null(); }
bool Bool(bool b) { return out_.Bool(b); }
bool Int(int i) { return out_.Int(i); }
bool Uint(unsigned u) { return out_.Uint(u); }
bool Int64(int64_t i) { return out_.Int64(i); }
bool Uint64(uint64_t u) { return out_.Uint64(u); }
bool Double(double d) { return out_.Double(d); }
bool String(const char* str, SizeType length, bool) {
buffer_.clear();
for (SizeType i = 0; i < length; i++)
buffer_.push_back(std::toupper(str[i]));
return out_.String(&buffer_.front(), length, true); // true = output handler need to copy the string
}
bool StartObject() { return out_.StartObject(); }
bool Key(const char* str, SizeType length, bool copy) { return String(str, length, copy); }
bool EndObject(SizeType memberCount) { return out_.EndObject(memberCount); }
bool StartArray() { return out_.StartArray(); }
bool EndArray(SizeType elementCount) { return out_.EndArray(elementCount); }
OutputHandler& out_;
std::vector<char> buffer_;
};
int main(int, char*[]) {
// Prepare JSON reader and input stream.
Reader reader;
char readBuffer[65536];
FileReadStream is(stdin, readBuffer, sizeof(readBuffer));
// Prepare JSON writer and output stream.
char writeBuffer[65536];
FileWriteStream os(stdout, writeBuffer, sizeof(writeBuffer));
Writer<FileWriteStream> writer(os);
// JSON reader parse from the input stream and let writer generate the output.
CapitalizeFilter<Writer<FileWriteStream> > filter(writer);
if (!reader.Parse(is, filter)) {
fprintf(stderr, "\nError(%u): %s\n", (unsigned)reader.GetErrorOffset(), GetParseError_En(reader.GetParseErrorCode()));
return 1;
}
return 0;
}
~~~~~~~~~~
注意到，不可简单地把JSON当作字符串去改为大写。例如：
~~~~~~~~~~
["Hello\nWorld"]
~~~~~~~~~~
简单地把整个JSON转为大写的话会产生错误的转义符：
~~~~~~~~~~
["HELLO\NWORLD"]
~~~~~~~~~~
而`capitalize`就会产生正确的结果：
~~~~~~~~~~
["HELLO\nWORLD"]
~~~~~~~~~~
我们还可以开发更复杂的过滤器。然而，由于SAX风格API在某一时间点只能提供单一事件的信息，使用者需要自行记录一些上下文信息（例如从根节点起的路径、储存其他相关值）。对些一些处理情况，用DOM会比SAX更容易实现。
doc/stream.zh-cn.md 0 → 100644
View file @ 9b63f39c
# 流
在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`。
# 编码流 {#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 IStreamWrapper {
public:
typedef char Ch;
IStreamWrapper(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:
IStreamWrapper(const IStreamWrapper&);
IStreamWrapper& operator=(const IStreamWrapper&);
std::istream& is_;
};
~~~~~~~~~~
使用者能用它来包装`std::stringstream`、`std::ifstream`的实例。
~~~~~~~~~~cpp
const char* json = "[1,2,3,4]";
std::stringstream ss(json);
IStreamWrapper is(ss);
Document d;
d.Parse(is);
~~~~~~~~~~
但要注意，由于标准库的内部开销问，此实现的性能可能不如RapidJSON的内存／文件流。
## 例子：ostream的包装类 {#ExampleOStreamWrapper}
以下的例子是`std::istream`的包装类，它只需实现2个函数。
~~~~~~~~~~cpp
class OStreamWrapper {
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:
OStreamWrapper(const OStreamWrapper&);
OStreamWrapper& operator=(const OStreamWrapper&);
std::ostream& os_;
};
~~~~~~~~~~
使用者能用它来包装`std::stringstream`、`std::ofstream`的实例。
~~~~~~~~~~cpp
Document d;
// ...
std::stringstream ss;
OSStreamWrapper os(ss);
Writer<OStreamWrapper> writer(os);
d.Accept(writer);
~~~~~~~~~~
但要注意，由于标准库的内部开销问，此实现的性能可能不如RapidJSON的内存／文件流。
# 总结 {#Summary}
本节描述了RapidJSON提供的各种流的类。内存流很简单。若JSON存储在文件中，文件流可减少JSON解析及生成所需的内存量。编码流在字节流和字符流之间作转换。最后，使用者可使用一个简单接口创建自定义的流。
doc/tutorial.zh-cn.md 0 → 100644
View file @ 9b63f39c
# 教程
本教程简介文件对象模型（Document Object Model, DOM）API。
如[用法一览](readme.zh-cn.md)中所示，可以解析一个JSON至DOM，然后就可以轻松查询及修改DOM，并最终转换回JSON。
[TOC]
# Value 及 Document {#ValueDocument}
每个JSON值都储存为`Value`类，而`Document`类则表示整个DOM，它存储了一个DOM树的根`Value`。RapidJSON的所有公开类型及函数都在`rapidjson`命名空间中。
# 查询Value {#QueryValue}
在本节中，我们会使用到`example/tutorial/tutorial.cpp`中的代码片段。
假设我们用C语言的字符串储存一个JSON（`const char* json`）：
~~~~~~~~~~js
{
"hello": "world",
"t": true ,
"f": false,
"n": null,
"i": 123,
"pi": 3.1416,
"a": [1, 2, 3, 4]
}
~~~~~~~~~~
把它解析至一个`Document`：
~~~~~~~~~~cpp
#include "rapidjson/document.h"
using namespace rapidjson;
// ...
Document document;
document.Parse(json);
~~~~~~~~~~
那么现在该JSON就会被解析至`document`中，成为一棵*DOM树*:
![教程中的DOM](diagram/tutorial.png)
自从RFC 7159作出更新，合法JSON文件的根可以是任何类型的JSON值。而在较早的RFC 4627中，根值只允许是Object或Array。而在上述例子中，根是一个Object。
~~~~~~~~~~cpp
assert(document.IsObject());
~~~~~~~~~~
让我们查询一下根Object中有没有`"hello"`成员。由于一个`Value`可包含不同类型的值，我们可能需要验证它的类型，并使用合适的API去获取其值。在此例中，`"hello"`成员关联到一个JSON String。
~~~~~~~~~~cpp
assert(document.HasMember("hello"));
assert(document["hello"].IsString());
printf("hello = %s\n", document["hello"].GetString());
~~~~~~~~~~
~~~~~~~~~~
world
~~~~~~~~~~
JSON True/False值是以`bool`表示的。
~~~~~~~~~~cpp
assert(document["t"].IsBool());
printf("t = %s\n", document["t"].GetBool() ? "true" : "false");
~~~~~~~~~~
~~~~~~~~~~
true
~~~~~~~~~~
JSON Null值可用`IsNull()`查询。
~~~~~~~~~~cpp
printf("n = %s\n", document["n"].IsNull() ? "null" : "?");
~~~~~~~~~~
~~~~~~~~~~
null
~~~~~~~~~~
JSON Number类型表示所有数值。然而，C++需要使用更专门的类型。
~~~~~~~~~~cpp
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包含一些元素。
~~~~~~~~~~cpp
// 使用引用来连续访问，方便之余还更高效。
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 {#QueryArray}
缺省情况下，`SizeType`是`unsigned`的typedef。在多数系统中，Array最多能存储2^32-1个元素。
你可以用整数字面量访问元素，如`a[0]`、`a[1]`、`a[2]`。
Array与`std::vector`相似，除了使用索引，也可使用迭待器来访问所有元素。
~~~~~~~~~~cpp
for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)
printf("%d ", itr->GetInt());
~~~~~~~~~~
还有一些熟悉的查询函数：
* `SizeType Capacity() const`
* `bool Empty() const`
## 查询Object {#QueryObject}
和Array相似，我们可以用迭代器去访问所有Object成员：
~~~~~~~~~~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
~~~~~~~~~~
注意，当`operator[](const char*)`找不到成员，它会断言失败。
若我们不确定一个成员是否存在，便需要在调用`operator[](const char*)`前先调用`HasMember()`。然而，这会导致两次查找。更好的做法是调用`FindMember()`，它能同时检查成员是否存在并返回它的Value：
~~~~~~~~~~cpp
Value::ConstMemberIterator itr = document.FindMember("hello");
if (itr != document.MemberEnd())
printf("%s %s\n", itr->value.GetString());
~~~~~~~~~~
## 查询Number {#QueryNumber}
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 GetUint()`
`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`。注意`int` 和`unsigned`可以安全地转换至`double`，但`int64_t`及`uint64_t`可能会丧失精度（因为`double`的尾数只有52位）。
## 查询String {#QueryString}
除了`GetString()`，`Value`类也有一个`GetStringLength()`。这里会解释个中原因。
根据RFC 4627，JSON String可包含Unicode字符`U+0000`，在JSON中会表示为`"\u0000"`。问题是，C/C++通常使用空字符结尾字符串（null-terminated string），这种字符串把``\0'`作为结束符号。
为了符合RFC 4627，RapidJSON支持包含`U+0000`的String。若你需要处理这些String，便可使用`GetStringLength()`去获得正确的字符串长度。
例如，当解析以下的JSON至`Document d`之后：
~~~~~~~~~~js
{ "s" : "a\u0000b" }
~~~~~~~~~~
`"a\u0000b"`值的正确长度应该是3。但`strlen()`会返回1。
`GetStringLength()`也可以提高性能，因为用户可能需要调用`strlen()`去分配缓冲。
此外，`std::string`也支持这个构造函数：
~~~~~~~~~~cpp
string(const char* s, size_t count);
~~~~~~~~~~
此构造函数接受字符串长度作为参数。它支持在字符串中存储空字符，也应该会有更好的性能。
## 比较两个Value
你可使用`==`及`!=`去比较两个Value。当且仅当两个Value的类型及内容相同，它们才当作相等。你也可以比较Value和它的原生类型值。以下是一个例子。
~~~~~~~~~~cpp
if (document["hello"] == document["n"]) /*...*/; // 比较两个值
if (document["hello"] == "world") /*...*/; // 与字符串家面量作比较
if (document["i"] != 123) /*...*/; // 与整数作比较
if (document["pi"] != 3.14) /*...*/; // 与double作比较
~~~~~~~~~~
Array／Object顺序以它们的元素／成员作比较。当且仅当它们的整个子树相等，它们才当作相等。
注意，现时若一个Object含有重复命名的成员，它与任何Object作比较都总会返回`false`。
# 创建／修改值 {#CreateModifyValues}
有多种方法去创建值。 当一个DOM树被创建或修改后，可使用`Writer`再次存储为JSON。
## 改变Value类型 {#ChangeValueType}
当使用默认构造函数创建一个Value或Document，它的类型便会是Null。要改变其类型，需调用`SetXXX()`或赋值操作，例如：
~~~~~~~~~~cpp
Document d; // Null
d.SetObject();
Value v; // Null
v.SetInt(10);
v = 10; // 简写，和上面的相同
~~~~~~~~~~
### 构造函数的各个重载
几个类型也有重载构造函数：
~~~~~~~~~~cpp
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)`：
~~~~~~~~~~cpp
Value o(kObjectType);
Value a(kArrayType);
~~~~~~~~~~
## 转移语意（Move Semantics） {#MoveSemantics}
在设计RapidJSON时有一个非常特别的决定，就是Value赋值并不是把来源Value复制至目的Value，而是把把来源Value转移（move）至目的Value。例如：
~~~~~~~~~~cpp
Value a(123);
Value b(456);
b = a; // a变成Null，b变成数字123。
~~~~~~~~~~
![使用移动语意赋值。](diagram/move1.png)
为什么？此语意有何优点？
最简单的答案就是性能。对于固定大小的JSON类型（Number、True、False、Null），复制它们是简单快捷。然而，对于可变大小的JSON类型（String、Array、Object），复制它们会产生大量开销，而且这些开销常常不被察觉。尤其是当我们需要创建临时Object，把它复制至另一变量，然后再析构它。
例如，若使用正常*复制*语意：
~~~~~~~~~~cpp
Value o(kObjectType);
{
Value contacts(kArrayType);
// 把元素加进contacts数组。
// ...
o.AddMember("contacts", contacts); // 深度复制contacts （可能有大量内存分配）
// 析构contacts。
}
~~~~~~~~~~
![复制语意产生大量的复制操作。](diagram/move2.png)
那个`o` Object需要分配一个和contacts相同大小的缓冲区，对conacts做深度复制，并最终要析构contacts。这样会产生大量无必要的内存分配／释放，以及内存复制。
有一些方案可避免实质地复制这些数据，例如引用计数（reference counting）、垃圾回收（garbage collection, GC）。
为了使RapidJSON简单及快速，我们选择了对赋值采用*转移*语意。这方法与`std::auto_ptr`相似，都是在赋值时转移拥有权。转移快得多简单得多，只需要析构原来的Value，把来源`memcpy()`至目标，最后把来源设置为Null类型。
因此，使用转移语意后，上面的例子变成：
~~~~~~~~~~cpp
Value o(kObjectType);
{
Value contacts(kArrayType);
// adding elements to contacts array.
o.AddMember("contacts", contacts); // 只需 memcpy() contacts本身至新成员的Value（16字节）
// contacts在这里变成Null。它的析构是平凡的。
}
~~~~~~~~~~
![转移语意不需复制。](diagram/move3.png)
在C++11中这称为转移赋值操作（move assignment operator）。由于RapidJSON 支持C++03，它在赋值操作采用转移语意，其它修改形函数如`AddMember()`, `PushBack()`也采用转移语意。
### 转移语意及临时值 {#TemporaryValues}
有时候，我们想直接构造一个Value并传递给一个“转移”函数（如`PushBack()`、`AddMember()`）。由于临时对象是不能转换为正常的Value引用，我们加入了一个方便的`Move()`函数：
~~~~~~~~~~cpp
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 {#CreateString}
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()`重载函数：
~~~~~~~~~~cpp
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参数。对于字符串家面量（或字符数组常量），只需简单地传递字面量，又安全又高效：
~~~~~~~~~~cpp
Value s;
s.SetString("rapidjson"); // 可包含空字符，长度在编译萁推导
s = "rapidjson"; // 上行的缩写
~~~~~~~~~~
对于字符指针，RapidJSON需要作一个标记，代表它不复制也是安全的。可以使用`StringRef`函数：
~~~~~~~~~cpp
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 {#ModifyArray}
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()`的例子：
~~~~~~~~~~cpp
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](#CreateString)），你需要使用copy-string API去创建一个String。为了避免加入中间变量，可以就地使用一个[临时值](#TemporaryValues)：
~~~~~~~~~~cpp
// 就地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 {#ModifyObject}
Object是键值对的集合。每个键必须为String。要修改Object，方法是增加或移除成员。以下的API用来增加城员：
* `Value& AddMember(Value&, Value&, Allocator& allocator)`
* `Value& AddMember(StringRefType, Value&, Allocator&)`
* `template <typename T> Value& AddMember(StringRefType, T value, Allocator&)`
以下是一个例子。
~~~~~~~~~~cpp
Value contact(kObject);
contact.AddMember("name", "Milo", document.GetAllocator());
contact.AddMember("married", true, document.GetAllocator());
~~~~~~~~~~
使用`StringRefType`作为name参数的重载版本与字符串的`SetString`的接口相似。 这些重载是为了避免复制`name`字符串，因为JSON object中经常会使用常数键名。
如果你需要从非常数字符串或生命周期不足的字符串创建键名（见[创建String](#CreateString)），你需要使用copy-string API。为了避免中间变量，可以就地使用[临时值](#TemporaryValues)：
~~~~~~~~~~cpp
// 就地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 {#DeepCopyValue}
若我们真的要复制一个DOM树，我们可使用两个APIs作深复制：含allocator的构造函数及`CopyFrom()`。
~~~~~~~~~~cpp
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 {#SwapValues}
RapidJSON也提供`Swap()`。
~~~~~~~~~~cpp
Value a(123);
Value b("Hello");
a.Swap(b);
assert(a.IsString());
assert(b.IsInt());
~~~~~~~~~~
无论两棵DOM树有多复杂，交换是很快的（常数时间）。
# 下一部分 {#WhatsNext}
本教程展示了如何询查及修改DOM树。RapidJSON还有一个重要概念：
1. [流](doc/stream.zh-cn.md) 是读写JSON的通道。流可以是内存字符串、文件流等。用户也可以自定义流。
2. [编码](doc/encoding.zh-cn.md)定义在流或内存中使用的字符编码。RapidJSON也在内部提供Unicode转换及校验功能。
3. [DOM](doc/dom.zh-cn.md)的基本功能已在本教程里介绍。还有更高级的功能，如原位（*in situ*）解析、其他解析选项及高级用法。
4. [SAX](doc/sax.zh-cn.md) 是RapidJSON解析／生成功能的基础。学习使用`Reader`/`Writer`去实现更高性能的应用程序。也可以使用`PrettyWriter`去格式化JSON。
5. [性能](doc/performance.zh-cn.md)展示一些我们做的及第三方的性能测试。
6. [技术内幕](doc/internals.zh-cn.md)讲述一些RapidJSON内部的设计及技术。
你也可以参考[常见问题](faq.zh-cn.md)、API文档、例子及单元测试。
readme.zh-cn.md 0 → 100644
View file @ 9b63f39c
![](doc/logo/rapidjson.png)
Copyright (c) 2011-2014 Milo Yip (miloyip@gmail.com)
[RapidJSON GitHub](https://github.com/miloyip/rapidjson/)
[RapidJSON 文档](http://miloyip.github.io/rapidjson/)
## 简介
RapidJSON是一个C++的JSON解析器及生成器。它的灵感来自[RapidXml](http://rapidxml.sourceforge.net/)。
* RapidJSON小而全。它同时支持SAX和DOM风格的API。SAX解析器只有约500行代码。
* RapidJSON快。它的性能可与`strlen()`相比。可支持SSE2/SSE4.1加速。
* RapidJSON独立。它不依赖于BOOST等外部库。它甚至不依赖于STL。
* RapidJSON对内存友好。在大部分32/64位机器上，每个JSON值只占16或20字节（除字符串外）。它预设使用一个快速的内存分配器，令分析器可以紧凑地分配内存。
* RapidJSON对Unicode友好。它支持UTF-8、UTF-16、UTF-32 (大端序／小端序)，并内部支持这些编码的检测、校验及转码。例如，RapidJSON可以在分析一个UTF-8文件至DOM时，把当中的JSON字符串转码至UTF-16。它也支持代理对（surrogate pair）及`"\u0000"`（空字符）。
在[这里](doc/features.md)可读取更多特点。
JSON（JavaScript Object Notation）是一个轻量的数据交换格式。RapidJSON应该完全遵从RFC7159/ECMA-404。 关于JSON的更多信息可参考：
* [Introducing JSON](http://json.org/)
* [RFC7159: The JavaScript Object Notation (JSON) Data Interchange Format](http://www.ietf.org/rfc/rfc7159.txt)
* [Standard ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/standards/Ecma-404.htm)
## 兼容性
RapidJSON是跨平台的。以下是一些曾测试的平台／编译器组合：
* Visual C++ 2008/2010/2013 在 Windows (32/64-bit)
* GNU C++ 3.8.x 在 Cygwin
* Clang 3.4 在 Mac OS X (32/64-bit) 及 iOS
* Clang 3.4 在 Android NDK
用户也可以在他们的平台上生成及执行单元测试。
## 安装
RapidJSON是只有头文件的C++库。只需把`include/rapidjson`目录复制至系统或项目的include目录中。
生成测试及例子的步骤：
1. 执行 `git submodule update --init` 去获取 thirdparty submodules (google test)。
2. 下载 [premake4](http://industriousone.com/premake/download)。
3. 复制 premake4 可执行文件至 `rapidjson/build` （或系统路径）。
4. 进入`rapidjson/build/`目录，在Windows下执行`premake.bat`，在Linux或其他平台下执行`premake.sh`。
5. 在Windows上，生成位于`rapidjson/build/vs2008/`或`/vs2010/`内的项目方案.
6. 在其他平台上，在`rapidjson/build/gmake/`目录执行GNU `make`（如 `make -f test.make config=release32`、`make -f example.make config=debug32`）。
7. 若成功，可执行文件会生成在`rapidjson/bin`目录。
生成[Doxygen](http://doxygen.org)文档的步骤：
1. 下载及安装[Doxygen](http://doxygen.org/download.html)。
2. 在顶层目录执行`doxygen build/Doxyfile`。
3. 在`doc/html`浏览文档。
## 用法一览
此简单例子解析一个JSON字符串至一个document (DOM)，对DOM作出简单修改，最终把DOM转换（stringify）至JSON字符串。
~~~~~~~~~~cpp
// rapidjson/example/simpledom/simpledom.cpp`
#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>
using namespace rapidjson;
int main() {
// 1. 把JSON解析至DOM。
const char* json = "{\"project\":\"rapidjson\",\"stars\":10}";
Document d;
d.Parse(json);
// 2. 利用DOM作出修改。
Value& s = d["stars"];
s.SetInt(s.GetInt() + 1);
// 3. 把DOM转换（stringify）成JSON。
StringBuffer buffer;
Writer<StringBuffer> writer(buffer);
d.Accept(writer);
// Output {"project":"rapidjson","stars":11}
std::cout << buffer.GetString() << std::endl;
return 0;
}
~~~~~~~~~~
注意此例子并没有处理潜在错误。
下图展示执行过程。
![simpledom](doc/diagram/simpledom.png)
还有许多[例子](https://github.com/miloyip/rapidjson/tree/master/example)可供参考。
travis-doxygen.sh
View file @ 9b63f39c
......@@ -57,6 +57,7 @@ doxygen_run()
{
cd "${TRAVIS_BUILD_DIR}";
doxygen ${TRAVIS_BUILD_DIR}/build/doc/Doxyfile;
doxygen ${TRAVIS_BUILD_DIR}/build/doc/Doxyfile.zh-cn;
}
gh_pages_prepare()
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment