nlohmann/json: Single-Header-JSON für C++11

Single-Header-Verteilung

Die Bibliothek wird als eine Header-Datei json.hpp unter single_include/nlohmann geliefert. Sie ist in C++11 geschrieben und hat keine Abhängigkeiten, kein Unterprojekt und kein Build-System. Sie fügen den Header zu Ihrem Projekt hinzu, binden ihn ein und verwenden die json-Klasse, die ein Alias für basic_json ist. Wenn Sie mit Modulen bauen, zeigt die README ein Beispiel mit import std; und import nlohmann.json, was die Option NLOHMANN_JSON_BUILD_MODULES erfordert.

Designziele und Kompromisse

Die README listet drei Designziele auf: intuitive Syntax, triviale Integration und ernsthafte Tests. Intuitive Syntax bedeutet, dass sich JSON-Werte wie erstklassige Datentypen verhalten, unter Verwendung von Operatorüberladung. Triviale Integration ist der einzelne Header ohne Anpassung der Compiler-Flags. Ernsthafte Tests umfassen 100% Unit-Test-Abdeckung, Valgrind- und Clang-Sanitizer-Prüfungen sowie Fuzz-Tests über Google OSS-Fuzz. Das Projekt folgt außerdem den Best Practices der Core Infrastructure Initiative. Speichereffizienz und Geschwindigkeit wurden ausdrücklich herabgestuft; jedes JSON-Objekt trägt einen Zeiger und ein Enum-Element, und die Standardtypen sind std::string, int64_t, uint64_t, double, std::map, std::vector und bool. Die README weist auf schnellere Bibliotheken hin, wenn rohe Geschwindigkeit Priorität hat.

Parsing, Serialisierung und Streams

Sie können eine JSON-Datei mit json::parse(stream) parsen oder ein String-Literal mit dem benutzerdefinierten Literal _json verwenden, sofern Sie nlohmann::literals in den Geltungsbereich bringen. Die Serialisierung verwendet dump(), das einen String zurückgibt; die Übergabe einer Ganzzahl an dump() aktiviert hübsches Drucken mit so vielen Leerzeichen für Einrückung. Die Bibliothek überlädt auch die Stream-Operatoren, sodass std::cin >> j und std::cout << j funktionieren, und std::setw(4) legt die Einrückung fest. Parsing akzeptiert Iterator-Bereiche, einschließlich benutzerdefinierter Iteratoren, die LegacyInputIterator erfüllen, und eine SAX-Schnittstelle ist für ereignisgesteuertes Parsing verfügbar. Die README warnt, dass nur UTF-8 unterstützt wird; dump() kann für andere Kodierungen eine Ausnahme auslösen, es sei denn, Sie wählen einen Fehlerbehandler.

STL-ähnlicher Zugriff und Container-Konvertierungen

Die json-Klasse ist so konzipiert, dass sie sich wie ein STL-Container anfühlt und die ReversibleContainer-Anforderung erfüllt. Sie unterstützt push_back, emplace_back, Iteratoren, begin/end, size, empty, clear, find, contains, count und erase. Bereichsbasierte for-Schleifen funktionieren, und die Objektiteration legt key() und value() offen. Die Konvertierung von STL-Sequenzcontainern (std::vector, std::deque, std::list usw.) erzeugt Arrays, und assoziative Container (std::map, std::unordered_map) erzeugen Objekte. Multimaps verlieren doppelte Schlüssel; nur ein Wert wird behalten. Sie können auch beliebige Typen konvertieren, indem Sie to_json und from_json im Namensraum des Typs definieren oder die bereitgestellten Makros wie NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE verwenden. Die README warnt vor impliziten Konvertierungen von JSON-Werten und empfiehlt stattdessen get<T>().

JSON Pointer, Patch und Merge Patch

Die Bibliothek implementiert JSON Pointer (RFC 6901), JSON Patch (RFC 6902) und JSON Merge Patch (RFC 7386). Sie können einen Wert mit einem Pointer unter Verwendung des _json_pointer-Literals adressieren, einen Patch mit patch() anwenden, eine Differenz mit json::diff() berechnen und mit merge_patch() zusammenführen. Die README listet auch die Funktionen flatten und unflatten auf. Diese Funktionen ermöglichen es Ihnen, verschachtelte JSON-Dokumente zu manipulieren, ohne Objekte und Arrays manuell zu durchlaufen.

Binärformate und benutzerdefinierte Serializer

Für kompakten Austausch kann die Bibliothek BSON, CBOR, MessagePack, UBJSON und BJData kodieren und dekodieren. Funktionen wie to_bson, from_bson, to_cbor, from_cbor und ihre Gegenstücke für die anderen Formate konvertieren zwischen json-Werten und std::vector<uint8_t>. Binärwerte aus Formaten, die Untertypen unterstützen (wie CBOR-Byte-Strings), werden als binärer Typ gespeichert; Sie können den Untertyp überprüfen und auf den zugrunde liegenden Vektor zugreifen. Für benutzerdefinierte Typen können Sie nlohmann::adl_serializer spezialisieren, und die README zeigt ein Muster für Drittanbieter-Typen wie boost::optional. Es gibt auch ein Makro NLOHMANN_JSON_SERIALIZE_ENUM, um Enums auf JSON-Strings oder andere Werte abzubilden.

Integration, Compiler und Qualität

Die README listet unterstützte Compiler auf: GCC 4.8 bis 14.2, Clang 3.4 bis 21.0, Apple Clang 9.1 bis 16.0, Intel C++ 17.0.2, Nvidia CUDA 11.0.221 und Visual C++ 2015 bis 2022. Nicht unterstützte Versionen werden mit #error abgelehnt, es sei denn, JSON_SKIP_UNSUPPORTED_COMPILER_CHECK ist definiert. Integrationsoptionen umfassen CMake, Paketmanager und pkg-config, aber die README reproduziert keine Installationsbefehle für diese Methoden. Das Projekt wird mit Unit-Tests, Valgrind, Clang Sanitizers und OSS-Fuzz getestet. Die Repository-Metadaten verzeichnen etwa 50.000 Sterne und 7.400 Forks, aber diese Zahlen sind nicht Teil der README.

Redaktionelles Fazit

Die README beschreibt eine Single-Header-C++-Bibliothek, die Benutzerfreundlichkeit und Korrektheit über rohe Geschwindigkeit oder Speichereffizienz stellt. Sie behandelt Parsing, Serialisierung, STL-ähnliche Manipulation, Binärformate und benutzerdefinierte Konvertierungen. Der vollständige Lizenztext ist in der README nicht enthalten; die Repository-Metadaten identifizieren die Lizenz als MIT.

Offizielle Quellen

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