Skip to content

Latest commit

 

History

History
121 lines (82 loc) · 5.42 KB

readme.zh-cn.md

File metadata and controls

121 lines (82 loc) · 5.42 KB
Raw

高效的C++ JSON解析／生成器，提供SAX及DOM风格API

Tencent 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.

Build 状态

Linux Windows Coveralls
lin-badge win-badge cov-badge

简介

RapidJSON是一个C++的JSON解析器及生成器。它的灵感来自RapidXml。

  • RapidJSON小而全。它同时支持SAX和DOM风格的API。SAX解析器只有约500行代码。

  • RapidJSON快。它的性能可与strlen()相比。可支持SSE2/SSE4.2加速。

  • 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"（空字符）。

在这里可读取更多特点。

JSON（JavaScript Object Notation）是一个轻量的数据交换格式。RapidJSON应该完全遵从RFC7159/ECMA-404。 关于JSON的更多信息可参考：

兼容性

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目录中。

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字符串。

// 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

还有许多例子可供参考。