readme.md 5.87 KB
Newer Older
Milo Yip's avatar
Milo Yip committed
1
![](doc/logo/rapidjson.png)
miloyip's avatar
miloyip committed
2

Milo Yip's avatar
Milo Yip committed
3
![](https://img.shields.io/badge/release-v1.0.2-blue.png)
miloyip's avatar
miloyip committed
4

5
## A fast JSON parser/generator for C++ with both SAX/DOM style API 
Milo Yip's avatar
Milo Yip committed
6

7 8 9
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.
Milo Yip's avatar
Milo Yip committed
10

11
* [RapidJSON GitHub](https://github.com/miloyip/rapidjson/)
miloyip's avatar
miloyip committed
12
* RapidJSON Documentation
miloyip's avatar
miloyip committed
13 14
  * [English](http://rapidjson.org/)
  * [简体中文](http://rapidjson.org/zh-cn/)
miloyip's avatar
miloyip committed
15
  * [GitBook](https://www.gitbook.com/book/miloyip/rapidjson/) with downloadable PDF/EPUB/MOBI, without API reference.
Milo Yip's avatar
Milo Yip committed
16

17
## Build status
18

Milo Yip's avatar
Milo Yip committed
19 20 21
| [Linux][lin-link] | [Windows][win-link] | [Coveralls][cov-link] |
| :---------------: | :-----------------: | :-------------------: |
| ![lin-badge]      | ![win-badge]        | ![cov-badge]          |
22

Milo Yip's avatar
Milo Yip committed
23
[lin-badge]: https://travis-ci.org/miloyip/rapidjson.png?branch=master "Travis build status"
24
[lin-link]:  https://travis-ci.org/miloyip/rapidjson "Travis build status"
Milo Yip's avatar
Milo Yip committed
25
[win-badge]: https://ci.appveyor.com/api/projects/status/u658dcuwxo14a8m9/branch/master "AppVeyor build status"
26
[win-link]:  https://ci.appveyor.com/project/miloyip/rapidjson/branch/master "AppVeyor build status"
Milo Yip's avatar
Milo Yip committed
27 28
[cov-badge]: https://coveralls.io/repos/miloyip/rapidjson/badge.png?branch=master
[cov-link]:  https://coveralls.io/r/miloyip/rapidjson?branch=master
29

Milo Yip's avatar
Milo Yip committed
30 31
## Introduction

Milo Yip's avatar
Milo Yip committed
32
RapidJSON is a JSON parser and generator for C++. It was inspired by [RapidXml](http://rapidxml.sourceforge.net/).
Milo Yip's avatar
Milo Yip committed
33

34
* RapidJSON is **small** but **complete**. It supports both SAX and DOM style API. The SAX parser is only a half thousand lines of code.
Milo Yip's avatar
Milo Yip committed
35

36
* RapidJSON is **fast**. Its performance can be comparable to `strlen()`. It also optionally supports SSE2/SSE4.2 for acceleration.
Milo Yip's avatar
Milo Yip committed
37

38
* RapidJSON is **self-contained** and **header-only**. It does not depend on external libraries such as BOOST. It even does not depend on STL.
Milo Yip's avatar
Milo Yip committed
39

40
* RapidJSON is **memory-friendly**. Each JSON value occupies exactly 16/20 bytes for most 32/64-bit machines (excluding text string). By default it uses a fast memory allocator, and the parser allocates memory compactly during parsing.
Milo Yip's avatar
Milo Yip committed
41

42
* RapidJSON is **Unicode-friendly**. It supports UTF-8, UTF-16, UTF-32 (LE & BE), and their detection, validation and transcoding internally. For example, you can read a UTF-8 file and let RapidJSON transcode the JSON strings into UTF-16 in the DOM. It also supports surrogates and "\u0000" (null character).
Milo Yip's avatar
Milo Yip committed
43

Milo Yip's avatar
Milo Yip committed
44
More features can be read [here](doc/features.md).
Milo Yip's avatar
Milo Yip committed
45

46
JSON(JavaScript Object Notation) is a light-weight data exchange format. RapidJSON should be in fully compliance with RFC7159/ECMA-404. More information about JSON can be obtained at
Milo Yip's avatar
Milo Yip committed
47
* [Introducing JSON](http://json.org/)
48
* [RFC7159: The JavaScript Object Notation (JSON) Data Interchange Format](http://www.ietf.org/rfc/rfc7159.txt)
Milo Yip's avatar
Milo Yip committed
49 50 51 52
* [Standard ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/standards/Ecma-404.htm)

## Compatibility

Milo Yip's avatar
Milo Yip committed
53
RapidJSON is cross-platform. Some platform/compiler combinations which have been tested are shown as follows.
Milo Yip's avatar
Milo Yip committed
54
* Visual C++ 2008/2010/2013 on Windows (32/64-bit)
Milo Yip's avatar
Milo Yip committed
55
* GNU C++ 3.8.x on Cygwin
Milo Yip's avatar
Milo Yip committed
56 57 58 59
* Clang 3.4 on Mac OS X (32/64-bit) and iOS
* Clang 3.4 on Android NDK

Users can build and run the unit tests on their platform/compiler.
Milo Yip's avatar
Milo Yip committed
60 61 62

## Installation

63
RapidJSON is a header-only C++ library. Just copy the `include/rapidjson` folder to system or project's include path.
Milo Yip's avatar
Milo Yip committed
64

65
RapidJSON uses following software as its dependencies:
66
* [CMake](https://cmake.org/) as a general build tool
unknown's avatar
unknown committed
67
* (optional)[Doxygen](http://www.doxygen.org) to build documentation
68
* (optional)[googletest](https://github.com/google/googletest) for unit and performance testing
Milo Yip's avatar
Milo Yip committed
69

70
To generate user documentation and run tests please proceed with the steps below:
Milo Yip's avatar
Milo Yip committed
71

Milo Yip's avatar
Milo Yip committed
72
1. Execute `git submodule update --init` to get the files of thirdparty submodules (google test).
73 74
2. Create directory called `build` in rapidjson source directory.
3. Change to `build` directory and run `cmake ..` command to configure your build. Windows users can do the same with cmake-gui application.
75 76 77 78 79 80 81 82 83 84 85 86 87
4. On Windows, build the solution found in the build directory. On Linux, run `make` from the build directory.

On successfull build you will find compiled test and example binaries in `bin`
directory. The generated documentation will be available in `doc/html`
directory of the build tree. To run tests after finished build please run `make
test` or `ctest` from your build tree. You can get detailed output using `ctest
-V` command.

It is possible to install library system-wide by running `make install` command
from the build tree with administrative privileges. This will install all files
according to system preferences.  Once RapidJSON is installed, it is possible
to use it from other CMake projects by adding `find_package(RapidJSON)` line to
your CMakeLists.txt.
88

89 90 91 92
## Usage at a glance

This simple example parses a JSON string into a document (DOM), make a simple modification of the DOM, and finally stringify the DOM to a JSON string.

93
~~~~~~~~~~cpp
94
// rapidjson/example/simpledom/simpledom.cpp`
95 96 97 98 99 100 101 102 103 104 105
#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

using namespace rapidjson;

int main() {
    // 1. Parse a JSON string into DOM.
    const char* json = "{\"project\":\"rapidjson\",\"stars\":10}";
    Document d;
106
    d.Parse(json);
107 108

    // 2. Modify it by DOM.
109 110
    Value& s = d["stars"];
    s.SetInt(s.GetInt() + 1);
111 112 113 114 115 116

    // 3. Stringify the DOM
    StringBuffer buffer;
    Writer<StringBuffer> writer(buffer);
    d.Accept(writer);

Milo Yip's avatar
Milo Yip committed
117
    // Output {"project":"rapidjson","stars":11}
118 119 120
    std::cout << buffer.GetString() << std::endl;
    return 0;
}
121
~~~~~~~~~~
122

Milo Yip's avatar
Milo Yip committed
123
Note that this example did not handle potential errors.
124 125 126

The following diagram shows the process.

127
![simpledom](doc/diagram/simpledom.png)
128

129
More [examples](https://github.com/miloyip/rapidjson/tree/master/example) are available.