]>
Commit | Line | Data |
---|---|---|
31f18b77 FG |
1 | ![](doc/logo/rapidjson.png) |
2 | ||
3 | ![](https://img.shields.io/badge/release-v1.1.0-blue.png) | |
4 | ||
5 | ## A fast JSON parser/generator for C++ with both SAX/DOM style API | |
6 | ||
7 | Tencent is pleased to support the open source community by making RapidJSON available. | |
8 | ||
9 | Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. All rights reserved. | |
10 | ||
11 | * [RapidJSON GitHub](https://github.com/miloyip/rapidjson/) | |
12 | * RapidJSON Documentation | |
13 | * [English](http://rapidjson.org/) | |
14 | * [简体中文](http://rapidjson.org/zh-cn/) | |
15 | * [GitBook](https://www.gitbook.com/book/miloyip/rapidjson/) with downloadable PDF/EPUB/MOBI, without API reference. | |
16 | ||
17 | ## Build status | |
18 | ||
19 | | [Linux][lin-link] | [Windows][win-link] | [Coveralls][cov-link] | | |
20 | | :---------------: | :-----------------: | :-------------------: | | |
21 | | ![lin-badge] | ![win-badge] | ![cov-badge] | | |
22 | ||
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" | |
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" | |
27 | [cov-badge]: https://coveralls.io/repos/miloyip/rapidjson/badge.png?branch=master | |
28 | [cov-link]: https://coveralls.io/r/miloyip/rapidjson?branch=master | |
29 | ||
30 | ## Introduction | |
31 | ||
32 | RapidJSON is a JSON parser and generator for C++. It was inspired by [RapidXml](http://rapidxml.sourceforge.net/). | |
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. | |
35 | ||
36 | * RapidJSON is **fast**. Its performance can be comparable to `strlen()`. It also optionally supports SSE2/SSE4.2 for acceleration. | |
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. | |
39 | ||
40 | * RapidJSON is **memory-friendly**. Each JSON value occupies exactly 16 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. | |
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). | |
43 | ||
44 | More features can be read [here](doc/features.md). | |
45 | ||
46 | JSON(JavaScript Object Notation) is a light-weight data exchange format. RapidJSON should be in fully compliance with RFC7159/ECMA-404, with optional support of relaxed syntax. More information about JSON can be obtained at | |
47 | * [Introducing JSON](http://json.org/) | |
48 | * [RFC7159: The JavaScript Object Notation (JSON) Data Interchange Format](http://www.ietf.org/rfc/rfc7159.txt) | |
49 | * [Standard ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/standards/Ecma-404.htm) | |
50 | ||
51 | ## Highlights in v1.1 (2016-8-25) | |
52 | ||
53 | * Added [JSON Pointer](doc/pointer.md) | |
54 | * Added [JSON Schema](doc/schema.md) | |
55 | * Added [relaxed JSON syntax](doc/dom.md) (comment, trailing comma, NaN/Infinity) | |
56 | * Iterating array/object with [C++11 Range-based for loop](doc/tutorial.md) | |
57 | * Reduce memory overhead of each `Value` from 24 bytes to 16 bytes in x86-64 architecture. | |
58 | ||
59 | For other changes please refer to [change log](CHANGELOG.md). | |
60 | ||
61 | ## Compatibility | |
62 | ||
63 | RapidJSON is cross-platform. Some platform/compiler combinations which have been tested are shown as follows. | |
64 | * Visual C++ 2008/2010/2013 on Windows (32/64-bit) | |
65 | * GNU C++ 3.8.x on Cygwin | |
66 | * Clang 3.4 on Mac OS X (32/64-bit) and iOS | |
67 | * Clang 3.4 on Android NDK | |
68 | ||
69 | Users can build and run the unit tests on their platform/compiler. | |
70 | ||
71 | ## Installation | |
72 | ||
73 | RapidJSON is a header-only C++ library. Just copy the `include/rapidjson` folder to system or project's include path. | |
74 | ||
75 | RapidJSON uses following software as its dependencies: | |
76 | * [CMake](https://cmake.org/) as a general build tool | |
77 | * (optional)[Doxygen](http://www.doxygen.org) to build documentation | |
78 | * (optional)[googletest](https://github.com/google/googletest) for unit and performance testing | |
79 | ||
80 | To generate user documentation and run tests please proceed with the steps below: | |
81 | ||
82 | 1. Execute `git submodule update --init` to get the files of thirdparty submodules (google test). | |
83 | 2. Create directory called `build` in rapidjson source directory. | |
84 | 3. Change to `build` directory and run `cmake ..` command to configure your build. Windows users can do the same with cmake-gui application. | |
85 | 4. On Windows, build the solution found in the build directory. On Linux, run `make` from the build directory. | |
86 | ||
87 | On successfull build you will find compiled test and example binaries in `bin` | |
88 | directory. The generated documentation will be available in `doc/html` | |
89 | directory of the build tree. To run tests after finished build please run `make | |
90 | test` or `ctest` from your build tree. You can get detailed output using `ctest | |
91 | -V` command. | |
92 | ||
93 | It is possible to install library system-wide by running `make install` command | |
94 | from the build tree with administrative privileges. This will install all files | |
95 | according to system preferences. Once RapidJSON is installed, it is possible | |
96 | to use it from other CMake projects by adding `find_package(RapidJSON)` line to | |
97 | your CMakeLists.txt. | |
98 | ||
99 | ## Usage at a glance | |
100 | ||
101 | 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. | |
102 | ||
103 | ~~~~~~~~~~cpp | |
104 | // rapidjson/example/simpledom/simpledom.cpp` | |
105 | #include "rapidjson/document.h" | |
106 | #include "rapidjson/writer.h" | |
107 | #include "rapidjson/stringbuffer.h" | |
108 | #include <iostream> | |
109 | ||
110 | using namespace rapidjson; | |
111 | ||
112 | int main() { | |
113 | // 1. Parse a JSON string into DOM. | |
114 | const char* json = "{\"project\":\"rapidjson\",\"stars\":10}"; | |
115 | Document d; | |
116 | d.Parse(json); | |
117 | ||
118 | // 2. Modify it by DOM. | |
119 | Value& s = d["stars"]; | |
120 | s.SetInt(s.GetInt() + 1); | |
121 | ||
122 | // 3. Stringify the DOM | |
123 | StringBuffer buffer; | |
124 | Writer<StringBuffer> writer(buffer); | |
125 | d.Accept(writer); | |
126 | ||
127 | // Output {"project":"rapidjson","stars":11} | |
128 | std::cout << buffer.GetString() << std::endl; | |
129 | return 0; | |
130 | } | |
131 | ~~~~~~~~~~ | |
132 | ||
133 | Note that this example did not handle potential errors. | |
134 | ||
135 | The following diagram shows the process. | |
136 | ||
137 | ![simpledom](doc/diagram/simpledom.png) | |
138 | ||
139 | More [examples](https://github.com/miloyip/rapidjson/tree/master/example) are available: | |
140 | ||
141 | * DOM API | |
142 | * [tutorial](https://github.com/miloyip/rapidjson/blob/master/example/tutorial/tutorial.cpp): Basic usage of DOM API. | |
143 | ||
144 | * SAX API | |
145 | * [simplereader](https://github.com/miloyip/rapidjson/blob/master/example/simplereader/simplereader.cpp): Dumps all SAX events while parsing a JSON by `Reader`. | |
146 | * [condense](https://github.com/miloyip/rapidjson/blob/master/example/condense/condense.cpp): A command line tool to rewrite a JSON, with all whitespaces removed. | |
147 | * [pretty](https://github.com/miloyip/rapidjson/blob/master/example/pretty/pretty.cpp): A command line tool to rewrite a JSON with indents and newlines by `PrettyWriter`. | |
148 | * [capitalize](https://github.com/miloyip/rapidjson/blob/master/example/capitalize/capitalize.cpp): A command line tool to capitalize strings in JSON. | |
149 | * [messagereader](https://github.com/miloyip/rapidjson/blob/master/example/messagereader/messagereader.cpp): Parse a JSON message with SAX API. | |
150 | * [serialize](https://github.com/miloyip/rapidjson/blob/master/example/serialize/serialize.cpp): Serialize a C++ object into JSON with SAX API. | |
151 | * [jsonx](https://github.com/miloyip/rapidjson/blob/master/example/jsonx/jsonx.cpp): Implements a `JsonxWriter` which stringify SAX events into [JSONx](https://www-01.ibm.com/support/knowledgecenter/SS9H2Y_7.1.0/com.ibm.dp.doc/json_jsonx.html) (a kind of XML) format. The example is a command line tool which converts input JSON into JSONx format. | |
152 | ||
153 | * Schema | |
154 | * [schemavalidator](https://github.com/miloyip/rapidjson/blob/master/example/schemavalidator/schemavalidator.cpp) : A command line tool to validate a JSON with a JSON schema. | |
155 | ||
156 | * Advanced | |
157 | * [prettyauto](https://github.com/miloyip/rapidjson/blob/master/example/prettyauto/prettyauto.cpp): A modified version of [pretty](https://github.com/miloyip/rapidjson/blob/master/example/pretty/pretty.cpp) to automatically handle JSON with any UTF encodings. | |
158 | * [parsebyparts](https://github.com/miloyip/rapidjson/blob/master/example/parsebyparts/parsebyparts.cpp): Implements an `AsyncDocumentParser` which can parse JSON in parts, using C++11 thread. | |
159 | * [filterkey](https://github.com/miloyip/rapidjson/blob/master/example/filterkey/filterkey.cpp): A command line tool to remove all values with user-specified key. | |
160 | * [filterkeydom](https://github.com/miloyip/rapidjson/blob/master/example/filterkeydom/filterkeydom.cpp): Same tool as above, but it demonstrates how to use a generator to populate a `Document`. |