rapidjson官方开发文档中文版

1.11.21.31.41.51.61.71.81.91.101.111.12Table of ContentsIntroduction特点教程Pointer流编码DOMSAXSchema性能Internals常见问题1高效的 C++ JSON 解析／生成器，提供 SAX 及 DOM 风格 APITencent is pleased to support the open source community by making RapidJSON available.Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. All rights reserved.RapidJSON GitHubRapidJSON 文档English简体中文GitBook 可下载 PDF/EPUB/MOBI，但不含 API 参考手册。Build 状态LinuxWindowsCoveralls简介RapidJSON 是一个 C++ 的 JSON 解析器及生成器。它的灵感来自 RapidXml。RapidJSON 小而全。它同时支持 SAX 和 DOM 风格的 API。SAX 解析器只有约 500 行代码。RapidJSON 快。它的性能可与 strlen() 相比。可支持 SSE2/SSE4.2 加速。RapidJSON 独立。它不依赖于 BOOST 等外部库。它甚至不依赖于 STL。RapidJSON 对内存友好。在大部分 32/64 位机器上，每个 JSON 值只占 16 字节（除字符串外）。它预设使用一个快速的内存分配器，令分析器可以紧凑地分配内存。RapidJSON 对 Unicode 友好。它支持 UTF-8、UTF-16、UTF-32 (大端序／小端序)，并内部支持这些编码的检测、校验及转码。例如，RapidJSON 可以在分析一个 UTF-8 文件至 DOM 时，把当中的JSON 字符串转码至 UTF-16。它也支持代理对（surrogate pair）及 \u0000 （空字符）。在 这里 可读取更多特点。JSON（JavaScript Object Notation）是一个轻量的数据交换格式。RapidJSON 应该完全遵从RFC7159/ECMA-404，并支持可选的放宽语法。 关于 JSON 的更多信息可参考：Introducing JSONRFC7159: The JavaScript Object Notation (JSON) Data Interchange FormatStandard ECMA-404: The JSON Data Interchange Formatv1.1 中的亮点 (2016-8-25)Introduction2加入 JSON Pointer 功能，可更简单地访问及更改 DOM。加入 JSON Schema 功能，可在解析或生成 JSON 时进行校验。加入 放宽的 JSON 语法 （注释、尾随逗号、NaN/Infinity）使用 C++11 范围 for 循环 去遍历 array 和 object。在 x86-64 架构下，缩减每个 Value 的内存开销从 24 字节至 16 字节。其他改动请参考 change log.兼容性RapidJSON 是跨平台的。以下是一些曾测试的平台／编译器组合：Visual C++ 2008/2010/2013 在 Windows (32/64-bit)GNU C++ 3.8.x 在 CygwinClang 3.4 在 Mac OS X (32/64-bit) 及 iOSClang 3.4 在 Android NDK用户也可以在他们的平台上生成及执行单元测试。安装RapidJSON 是只有头文件的 C++ 库。只需把 include/rapidjson 目录复制至系统或项目的 include 目录中。RapidJSON 依赖于以下软件：CMake 作为通用生成工具(optional)Doxygen 用于生成文档(optional)googletest 用于单元及性能测试生成测试及例子的步骤：1. 执行 git submodule update --init 去获取 thirdparty submodules (google test)。2. 在 rapidjson 目渌下，建立一个 build 目录。3. 在 build 目录下执行 cmake .. 命令以设置生成。Windows 用户可使用 cmake-gui 应用程序。4. 在 Windows 下，编译生成在 build 目录中的 solution。在 Linux 下，于 build 目录运行 make 。成功生成后，你会在 bin 的目录下找到编译后的测试及例子可执行文件。而生成的文档将位于 build 下的 doc/html 目录。要执行测试，请在 build 下执行 make test 或 ctest 。使用 ctest -V 命令可获取详细的输出。我们也可以把程序库安装至全系统中，只要在具管理權限下从 build 目录执行 make install 命令。这样会按系统的偏好设置安装所有文件。当安装 RapidJSON 后，其他的 CMake 项目需要使用它时，可以通过在 CMakeLists.txt 加入一句 find_package(RapidJSON) 。用法一览此简单例子解析一个 JSON 字符串至一个 document (DOM)，对 DOM 作出简单修改，最终把 DOM 转换（stringify）至 JSON 字符串。Introduction3// rapidjson/example/simpledom/simpledom.cpp`#include rapidjson/document.h#include rapidjson/writer.h#include rapidjson/stringbuffer.h#include iostreamusing 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; WriterStringBuffer writer(buffer); d.Accept(writer); // Output {project:rapidjson,stars:11} std::cout buffer.GetString() std::endl; return 0;}注意此例子并没有处理潜在错误。下图展示执行过程。Introduction4还有许多 例子 可供参考：DOM APItutorial: DOM API 的基本使用方法。SAX APIsimplereader: 使用 Reader 解析 JSON 时，打印所有 SAX 事件。condense: 移除 JSON 中所有空白符的命令行工具。pretty: 为 JSON 加入缩进与换行的命令行工具，当中使用了 PrettyWriter 。capitalize: 把 JSON 中所有字符串改为大写的命令行工具。messagereader: 使用 SAX API 去解析一个 JSON 报文。serialize: 使用 SAX API 去序列化 C++ 对象，生成 JSON。jsonx: 实现了一个 JsonxWriter ，它能把 SAX 事件写成 JSONx（一种 XML）格式。这个例子是把 JSON 输入转换成 JSONx 格式的命令行工具。Schema APIschemavalidator: 使用 JSON Schema 去校验 JSON 的命令行工具。进阶prettyauto: pretty 的修改版本，可自动处理任何 UTF 编码的 JSON。parsebyparts: 这例子中的 AsyncDocumentParser 类使用 C++ 线程来逐段解析 JSON。filterkey: 移取使用者指定的键值的命令行工具。Introduction5filterkeydom: 如上的工具，但展示如何使用生成器（generator）去填充一个 Document 。Introduction6特点总体跨平台编译器：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.2 支持。符合标准RapidJSON 应完全符合 RFC4627/ECMA-404 标准。支持 JSON Pointer (RFC6901).支持 JSON Schema Draft v4.支持 Unicod 代理对（surrogate pair）。支持空字符（ \u0000 ）。例如，可以优雅地解析及处理 [Hello\u0000World] 。含读写字符串长度的 API。支持可选的放宽语法单行（ // ... ）及多行（ /* ... */ ） 注释 ( kParseCommentsFlag )。在对象和数组结束前含逗号 ( kParseTrailingCommasFlag )。 NaN 、 Inf 、 Infinity 、 -Inf 及 -Infinity 作为 double 值( kParseNanAndInfFlag )NPM 兼容.Unicode支持 UTF-8、UTF-16、UTF-32 编码，包括小端序和大端序。这些编码用于输入输出流，以及内存中的表示。支持从输入流自动检测编码。内部支持编码的转换。例如，你可以读取一个 UTF-8 文件，让 RapidJSON 把 JSON 字符串转换至 UTF-16 的 DOM。内部支持编码校验。例如，你可以读取一个 UTF-8 文件，让 RapidJSON 检查是否所有 JSON 字符串是合法的 UTF-8特点7字节序列。支持自定义的字符类型。预设的字符类型是：UTF-8 为 char ，UTF-16 为 wchar_t ，UTF32 为 uint32_t 。支持自定义的编码。API 风格SAX（Simple API for XML）风格 API类似于 SAX, RapidJSON 提供一个事件循序访问的解析器API（ rapidjson::GenericReader ）。RapidJSON 也提供一个生成器API（ rapidjson::Writer ），可以处理相同的事件集合。DOM（Document Object Model）风格 API类似于 HTML／XML 的 DOM，RapidJSON 可把 JSON 解析至一个 DOM 表示方式（ rapidjson::GenericDocument ），以方便操作。如有需要，可把 DOM 转换（stringif