RapidJSON：はじめに | RapidJSON ドキュメント

SAX/DOM両形式のAPIを備えた、C++用の高速なJSONパーサー・生成器

Tencentは、RapidJSONの公開を通じてオープンソースコミュニティーを支援できることを嬉しく思います。

RapidJSON GitHub
RapidJSONドキュメント
- 英語
- 简体中文
- GitBookではPDF/EPUB/MOBIをダウンロードできます。APIリファレンスは含まれません。

ビルド状況

Linux	Windows	Coveralls

はじめに

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（LEとBE）と、それらの検出・妥当性検証・エンコーディング変換を内部で処理します。たとえば、UTF-8ファイルを読み、DOM内のJSON文字列をRapidJSONでUTF-16へ変換できます。サロゲートと「\u0000」（ヌル文字）にも対応します。

さらに詳しい機能は、こちらを参照してください。

JSON（JavaScript Object Notation）は、軽量なデータ交換形式です。RapidJSONはRFC7159/ECMA-404に完全に準拠することを目指し、任意で緩和された構文にも対応します。JSONの詳しい情報は、次の資料で確認できます。

v1.1（2016年8月25日）の主な変更

JSON Pointerを追加。
JSON Schemaを追加。
緩和されたJSON構文を追加（コメント、末尾のカンマ、NaN/Infinity）。
C++11の範囲ベースのforループによる配列・オブジェクトの反復処理。
x86-64アーキテクチャーで、各Valueのメモリーオーバーヘッドを24バイトから16バイトへ削減。

その他の変更は、変更履歴を参照してください。

互換性

RapidJSONはクロスプラットフォームです。テスト済みのプラットフォームとコンパイラーの組み合わせの一部を以下に示します。

Windows（32ビット・64ビット）上のVisual C++ 2008/2010/2013
Cygwin上のGNU C++ 3.8.x
Mac OS X（32ビット・64ビット）とiOS上のClang 3.4
Android NDK上のClang 3.4

利用するプラットフォーム・コンパイラーで、単体テストをビルドして実行できます。

インストール

RapidJSONは、ヘッダーファイルだけのC++ライブラリーです。include/rapidjsonフォルダーを、システムまたはプロジェクトのインクルードパスへコピーするだけで利用できます。

RapidJSONは、依存ソフトウェアとして以下を使います。

汎用ビルドツールとしてCMake。
文書のビルドにDoxygen（任意）。
単体テストと性能テストにgoogletest（任意）。

利用者向け文書を生成してテストを実行するには、次の手順に従ってください。

git submodule update --initを実行し、第三者サブモジュール（google test）のファイルを取得します。
rapidjsonのソースディレクトリに、buildというディレクトリを作成します。
buildディレクトリへ移動し、cmake ..コマンドでビルドを設定します。Windowsではcmake-guiアプリケーションでも同じ操作ができます。
Windowsでは、ビルドディレクトリにあるソリューションをビルドします。Linuxでは、ビルドディレクトリでmakeを実行します。

ビルドに成功すると、コンパイル済みのテストとサンプルの実行ファイルがbinディレクトリにできます。生成した文書は、ビルドツリーのdoc/htmlディレクトリにあります。ビルド後にテストを実行するには、ビルドツリーでmake testかctestを実行してください。ctest -Vコマンドで詳しい出力を取得できます。

ビルドツリーで管理者権限によりmake installを実行すると、ライブラリーをシステム全体へインストールできます。システムの設定に従って、すべてのファイルがインストールされます。RapidJSONをインストールしたら、CMakeLists.txtにfind_package(RapidJSON)という行を追加することで、他のCMakeプロジェクトから利用できます。

使い方の概要

この簡単な例では、JSON文字列を文書（DOM）へ解析し、DOMに簡単な変更を加え、最後にDOMを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. Parse a JSON string into DOM.
    const char* json = "{\"project\":\"rapidjson\",\"stars\":10}";
    Document d;
    d.Parse(json);
 
    // 2. Modify it by DOM.
    Value& s = d["stars"];
    s.SetInt(s.GetInt() + 1);
 
    // 3. Stringify the DOM
    StringBuffer buffer;
    Writer<StringBuffer> writer(buffer);
    d.Accept(writer);
 
    // Output {"project":"rapidjson","stars":11}
    std::cout << buffer.GetString() << std::endl;
    return 0;
}

この例では、起こり得るエラーを処理していないことに注意してください。

以下の図は、この処理を示しています。

simpledom

さらに次のサンプルがあります。

DOM API
- tutorial：DOM APIの基本的な使い方。
SAX API
- simplereader：ReaderでJSONを解析しながら、すべてのSAXイベントを出力します。
- condense：空白をすべて取り除いてJSONを書き直すコマンドラインツール。
- pretty：PrettyWriterでインデントと改行を付け、JSONを書き直すコマンドラインツール。
- capitalize：JSON内の文字列を大文字にするコマンドラインツール。
- messagereader：SAX APIでJSONメッセージを解析します。
- serialize：SAX APIでC++オブジェクトをJSONへシリアライズします。
- jsonx：SAXイベントをJSONx（XMLの一種）形式へ文字列化するJsonxWriterを実装します。この例は、入力JSONをJSONx形式へ変換するコマンドラインツールです。
スキーマ
- schemavalidator：JSON Schemaを用いてJSONを検証するコマンドラインツール。
応用
- prettyauto：任意のUTFエンコーディングのJSONを自動的に扱えるよう、prettyを変更したものです。
- parsebyparts：C++11のスレッドを使い、JSONを分割して解析できるAsyncDocumentParserを実装します。
- filterkey：指定したキーを持つ値をすべて削除するコマンドラインツール。
- filterkeydom：上と同じ処理を行いますが、生成器を使ってDocumentに値を設定する方法を示します。