Design goals
There are myriads of JSON libraries out there, and each may even have its reason to exist. Our class had these design goals:
Intuitive syntax. In languages such as Python, JSON feels like a first-class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code. Check out the examples below and you'll know what I mean.
Trivial integration. Our whole code consists of a single header file json.hpp. That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings. The library is also included in all popular package managers.
Serious testing. Our code is heavily unit-tested and covers 100% of the code, including all exceptional behavior. Furthermore, we checked with Valgrind and the Clang Sanitizers that there are no memory leaks. Google OSS-Fuzz additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the Core Infrastructure Initiative (CII) best practices. See the quality assurance overview documentation.
Other aspects were not so important to us:
Memory efficiency. Each JSON object has an overhead of one pointer (the maximal size of a union) and one enumeration element (1 byte). The default generalization uses the following C++ data types: std::string for strings, int64_t, uint64_t or double for numbers, std::map for objects, std::vector for arrays, and bool for Booleans. However, you can template the generalized class basic_json to your needs.
Speed. There are certainly faster JSON libraries out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a std::vector or std::map, you are already set.
See the contribution guidelines for more information.
You can sponsor this library at GitHub Sponsors.
Further support
The development of the library is further supported by JetBrains by providing free access to their IDE tools.
Thanks everyone!
Support
:question: If you have a question, please check if it is already answered in the FAQ or the Q&A section. If not, please ask a new question there.
:books: If you want to learn more about how to use the library, check out the rest of the README, have a look at code examples, or browse through the help pages.
:construction: If you want to understand the API better, check out the API Reference or have a look at the quick reference below.
:bug: If you found a bug, please check the FAQ if it is a known issue or the result of a design decision. Please also have a look at the issue list before you create a new issue. Please provide as much information as possible to help us understand and reproduce your issue.
There is also a docset for the documentation browsers Dash, Velocity, and Zeal that contains the full documentation as an offline resource.
Quick reference
- Constructors basic_json, array, binary, object
- Object inspection: type, operator value_t, type_name, is_primitive, is_structured, is_null, is_boolean, is_number, is_number_integer, is_number_unsigned, is_number_float, is_object, is_array, is_string, is_binary, is_discarded
- Value access; get, get_to, get_ptr, get_ref, operator ValueType, get_binary
- Element access: at, operator[], value, front, back
- Lookup: find, count, contains
- Iterators: begin, cbegin, end, cend, rbegin, rend, crbegin, crend, items
- Capacity: empty, size, max_size
- Modifiers: clear, push_back, operator+=, emplace_back, emplace, erase, insert, update, swap
- Lexicographical comparison operators: operator==, operator!=, operator<, operator>, operator<=, operator>=, operator<=>
- Serialization / Dumping: dump
- Deserialization / Parsing: parse, accept, sax_parse
- JSON Pointer functions: flatten, unflatten
- JSON Patch functions: patch, patch_inplace, diff, merge_patch
- Static functions: meta, get_allocator
- Binary formats: from_bjdata, from_bson, from_cbor, from_msgpack, from_ubjson, to_bjdata, to_bson, to_cbor, to_msgpack, to_ubjson
- Non-member functions: operator<<, operator>>, to_string
- Literals: operator""_json
- Helper classes: std::hash<basic_json>, std::swap<basic_json>
Full API documentation
Examples
Here are some examples to give you an idea how to use the class.
Besides the examples below, you may want to:
→ Check the documentation
→ Browse the standalone example files
→ Read the full API Documentation with self-contained examples for every function
Read JSON from a file
The json class provides an API for manipulating a JSON value. To create a json object by reading a JSON file:
#include <fstream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
// ...
std::ifstream f("example.json");
json data = json::parse(f);
If using modules (enabled with NLOHMANN_JSON_BUILD_MODULES), this example becomes:
import std;
import nlohmann.json;
using json = nlohmann::json;
// ...
std::ifstream f("example.json");
json data = json::parse(f);
Creating json objects from JSON literals
Assume you want to hard-code this literal JSON value as a json object:
{
"pi": 3.141,
"happy": true
}
There are various options:
// Using (raw) string literals and json::parse
json ex1 = json::parse(R"(
{
"pi": 3.141,
"happy": true
}
)");
// Using user-defined (raw) string literals
using namespace nlohmann::literals;
json ex2 = R"(
{
"pi": 3.141,
"happy": true
}
)"_json;
// Using initializer lists
json ex3 = {
{"happy", true},
{"pi", 3.141},
};
JSON as a first-class data type
Here are some examples to give you an idea how to use the class.
Assume you want to create the JSON object
{
"pi": 3.141,
"happy": true,
"name": "Niels",
"nothing": null,
"answer": {
"everything": 42
},
"list": [1, 0, 2],
"object": {
"currency": "USD",
"value": 42.99
}
}
With this library, you could write:
// create an empty structure (null)
json j;
// add a number stored as double (note the implicit conversion of j to an object)
j["pi"] = 3.141;
// add a Boolean stored as bool
j["happy"] = true;
// add a string stored as std::string
j["name"] = "Niels";
// add another null object by passing nullptr
j["nothing"] = nullptr;
// add an object inside the object
j["answer"]["everything"] = 42;
// add an array stored as std::vector (using an initializer list)
j["list"] = { 1, 0, 2 };
// add another object (using an initializer list of pairs)
j["object"] = { {"currency", "USD"}, {"value", 42.99} };
// instead, you could also write (which looks very similar to the JSON above)
json j2 = {
{"pi", 3.141},
{"happy", true},
{"name", "Niels"},
{"nothing", nullptr},
{"answer", {
{"everything", 42}
}},
{"list", {1, 0, 2}},
{"object", {
{"currency", "USD"},
{"value", 42.99}
}}
};
Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions json::array() and json::object() will help:
// a way to express the empty array []
json empty_array_explicit = json::array();
// ways to express the empty object {}
json empty_object_implicit = json({});
json empty_object_explicit = json::object();
// a way to express an _array_ of key/value pairs [["currency", "USD"], ["value", 42.99]]
json array_not_object = json::array({ {"currency", "USD"}, {"value", 42.99} });
Serialization / Deserialization
To/from strings
You can create a JSON value (deserialization) by appending _json to a string literal:
// create object from string literal
json j = "{ \"happy\": true, \"pi\": 3
一个面向现代 C++ 的 JSON 库（nlohmann/json），让你可以直接在 C++ 代码中用直观、类似 STL 的语法读取、创建和操作 JSON 数据。