nlohmann/json: READMEと実装範囲を読む

nlohmann/json シングルヘッダー配布

ライブラリは single_include/nlohmann の下にある単一のヘッダーファイル json.hpp として提供されます。C++11 で書かれており、依存関係もサブプロジェクトもビルドシステムもありません。ヘッダーをプロジェクトに追加してインクルードし、basic_json のエイリアスである json クラスを使用します。モジュールでビルドする場合、README は import std; と import nlohmann.json を使用する例を示しており、NLOHMANN_JSON_BUILD_MODULES オプションが必要です。

nlohmann/json 設計目標とトレードオフ

README は3つの設計目標を挙げています: 直感的な構文、簡単な統合、真剣なテスト。直感的な構文とは、演算子オーバーロードを使用して JSON 値がファーストクラスのデータ型のように振る舞うことを意味します。簡単な統合は、コンパイラフラグの調整が不要な単一ヘッダーです。真剣なテストには、100% のユニットテストカバレッジ、Valgrind と Clang Sanitizer のチェック、Google OSS-Fuzz によるファジングテストが含まれます。プロジェクトは Core Infrastructure Initiative のベストプラクティスにも従っています。メモリ効率と速度は明示的に重視されておらず、各 JSON オブジェクトは1つのポインタと1つの列挙要素を持ち、デフォルト型は std::string、int64_t、uint64_t、double、std::map、std::vector、bool です。README は、生の速度が優先される場合にはより高速なライブラリを指摘しています。

nlohmann/json パース、シリアライズ、ストリーム

json::parse(stream) で JSON ファイルをパースするか、_json ユーザー定義リテラルを持つ文字列リテラルを使用できます (nlohmann::literals をスコープに導入する必要があります)。シリアライズは dump() を使用し、文字列を返します。dump() に整数を渡すと、そのスペース数でインデントされたプリティプリントが有効になります。ライブラリはストリーム演算子もオーバーロードするため、std::cin >> j と std::cout << j が機能し、std::setw(4) でインデントを設定します。パースは LegacyInputIterator を満たすカスタムイテレータを含むイテレータ範囲を受け入れ、イベント駆動型パース用の SAX インターフェースも利用できます。README は UTF-8 のみがサポートされていると警告しています。他のエンコーディングでは、エラーハンドラを選択しない限り dump() が例外を投げる可能性があります。

nlohmann/json STL 風アクセスとコンテナ変換

json クラスは STL コンテナのように感じられるように設計されており、ReversibleContainer 要件を満たしています。push_back、emplace_back、イテレータ、begin/end、size、empty、clear、find、contains、count、erase をサポートしています。範囲ベースの for ループが機能し、オブジェクトの反復は key() と value() を公開します。STL シーケンスコンテナ (std::vector、std::deque、std::list など) からの変換は配列を生成し、連想コンテナ (std::map、std::unordered_map) はオブジェクトを生成します。マルチマップは重複キーを失い、1つの値だけが保持されます。また、型の名前空間で to_json と from_json を定義するか、NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE などの提供マクロを使用して、任意の型を変換できます。README は JSON 値からの暗黙的な変換を警告し、代わりに get<T>() を推奨しています。

nlohmann/json JSON Pointer、Patch、Merge Patch

ライブラリは JSON Pointer (RFC 6901)、JSON Patch (RFC 6902)、JSON Merge Patch (RFC 7386) を実装しています。_json_pointer リテラルを使用してポインタで値にアクセスし、patch() でパッチを適用し、json::diff() で差分を計算し、merge_patch() でマージできます。README は flatten と unflatten 関数もリストしています。これらの機能により、オブジェクトと配列を手動で走査することなく、ネストされた JSON ドキュメントを操作できます。

nlohmann/json バイナリ形式とカスタムシリアライザ

コンパクトな交換のために、ライブラリは BSON、CBOR、MessagePack、UBJSON、BJData をエンコードおよびデコードできます。to_bson、from_bson、to_cbor、from_cbor などの関数と、他の形式に対応する関数は、json 値と std::vector<uint8_t> の間で変換します。サブタイプをサポートする形式 (CBOR バイト文字列など) からのバイナリ値はバイナリ型として保存されます。サブタイプを検査し、基になるベクターにアクセスできます。カスタム型の場合、nlohmann::adl_serializer を特殊化でき、README は boost::optional のようなサードパーティ型のパターンを示しています。また、列挙型を JSON 文字列や他の値にマップするマクロ NLOHMANN_JSON_SERIALIZE_ENUM もあります。

nlohmann/json 統合、コンパイラ、品質

README はサポートされているコンパイラをリストしています: GCC 4.8 から 14.2、Clang 3.4 から 21.0、Apple Clang 9.1 から 16.0、Intel C++ 17.0.2、Nvidia CUDA 11.0.221、Visual C++ 2015 から 2022。サポートされていないバージョンは、JSON_SKIP_UNSUPPORTED_COMPILER_CHECK が定義されていない限り、#error で拒否されます。統合オプションには CMake、パッケージマネージャー、pkg-config が含まれますが、README はこれらの方法のインストールコマンドを再現していません。プロジェクトはユニットテスト、Valgrind、Clang Sanitizer、OSS-Fuzz でテストされています。リポジトリのメタデータには約 5 万のスターと 7 千のフォークが記録されていますが、これらの数字は README の一部ではありません。

組み込みではsingle headerをプロジェクトへ導入する方法とCMakeの依存方法を選び、コンパイラの対応表にある版で警告と例外処理を確認します。UTF-8以外の入力を受ける境界では、parse、dump、エラーハンドラの挙動をテストし、暗黙変換ではなくget<T>()を使う方針をコードレビューで固定します。JSON PointerやPatch、CBORなどを利用する場合は、期待するRFC形式とバイナリ値の扱いを入出力テストに含めます。

nlohmann/jsonについては、READMEに書かれた入口と生成物を照合し、未記載の保証を機能として数えない判断が必要です。

編集部の結論

README は、生の速度やメモリ効率よりも使いやすさと正確さを優先するシングルヘッダー C++ ライブラリについて説明しています。パース、シリアライズ、STL 風操作、バイナリ形式、カスタム変換を網羅しています。README にはライセンス全文は含まれておらず、リポジトリのメタデータはライセンスが MIT であると示しています。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes