json/README.md

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 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.

• Serious testing. Our class is heavily unit-tested and covers 100% of the code, including all exceptional behavior. Furthermore, we checked with Valgrind that there are no memory leaks.

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 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. We currently implement the parser as naive recursive descent parser with hand coded string handling. It is fast enough, but a LALR-parser with a decent regular expression processor should be even faster (but would consist of more files which makes the integration harder).

• Rigorous Unicode compliance. We did our best to implement some robust Unicode support. There are still some issues with escaping, and if you run into a problem, please tell me.

Updates since last version

As of February 2015, the following updates were made to the library

• Changed: In the generic class basic_json, all JSON value types (array, object, string, bool, integer number, and floating-point) are now templated. That is, you can choose whether you like a std::list for your arrays or an std::unordered_map for your objects. The specialization json sets some reasonable defaults.
• Changed: The library now consists of a single header, called json.hpp. Consequently, build systems such as Automake or CMake are not any longer required.
• Changed: The deserialization is now supported by a lexer generated with re2c from file src/json.hpp.re2c. As a result, we follow the JSON specification more strictly. Note neither the tool re2c nor its input are required to use the class.
• Added: The library now satisfies the ReversibleContainer requirement. It hence provides four different iterators (iterator, const_iterator, reverse_iterator, and const_reverse_iterator), comparison functions, swap(), size(), max_size(), and empty() member functions.
• Added: The class uses user-defined allocators which default to std::allocator, but can be templated via parameter Allocator.
• Added: To simplify pretty-printing, the std::setw stream manipulator has been overloaded to set the desired indentation. Pretty-printing a JSON object j is as simple as std::cout << std::setw(4) << j << '\n'.
• Changed: The type json::value_t::number is now called json::value_t::number_integer to be more symmetric compared to json::value_t::number_float.
• Removed: The key() and value() member functions for object iterators were nonstandard and yielded more problems than benefits. They were removed from the library.

Integration

The single required source, json.hpp file is in the src directory. All you need to do is add

#include "json.hpp"

// for convenience
using json = nlohmann::json;

to the files you want to use JSON objects. That's it. Do not forget to set the necessary switches to enable C++11 (e.g., -std=c++11 for GCC and Clang).

Examples

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 the JSON class, you could write:

// create an empty structure (null)
json j;

// add a number that is stored as double (note the implicit conversion of j to an object)
j["pi"] = 3.141;

// add a Boolean that is stored as bool
j["happy"] = true;

// add a string that is 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 that is 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 theses cases, you never need to "tell" the compiler which JSON value you want to use. If you want to be explicit or express some edge cases, the functions json::array and json::object will help:

// ways to express the empty array []
json empty_array_implicit = {{}};
json empty_array_explicit = json::array();

// a way to express the empty object {}
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"}), json::array({"value", 42.99}) };

Serialization / Deserialization

You can create an object (deserialization) by appending _json to a string literal:

// create object from string literal
json j = "{ \"happy\": true, \"pi\": 3.141 }"_json;

// or even nicer (thanks http://isocpp.org/blog/2015/01/json-for-modern-cpp)
auto j2 = R"(
  {
    "happy": true,
    "pi": 3.141
  }
)"_json;

// or explicitly
auto j3 = json::parse("{ \"happy\": true, \"pi\": 3.141 }");

You can also get a string representation (serialize):

// explicit conversion to string
std::string s = j.dump();    // {\"happy\":true,\"pi\":3.141}

// serialization with pretty printing
// pass in the amount of spaces to indent
std::cout << j.dump(4) << std::endl;
// {
//     "happy": true,
//     "pi": 3.141
// }

You can also use streams to serialize and deserialize:

// deserialize from standard input
json j;
j << std::cin;

// serialize to standard output
std::cout << j;

// the setw manipulator was overloaded to set the indentation for pretty printing
std::cout << std::setw(4) << j << std::endl;

These operators work for any subclasses of std::istream or std::ostream.

STL-like access

We designed the JSON class to behave just like an STL container. In fact, it satisfies the ReversibleContainer requirement.

// create an array using push_back
json j;
j.push_back("foo");
j.push_back(1);
j.push_back(true);

// iterate the array
for (json::iterator it = j.begin(); it != j.end(); ++it) {
  std::cout << *it << '\n';
}

// range-based for
for (auto element : j) {
  std::cout << element << '\n';
}

// getter/setter
const std::string tmp = j[0];
j[1] = 42;
bool foo = j.at(2);

// other stuff
j.size();     // 3 entries
j.empty();    // false
j.type();     // json::value_t::array
j.clear();    // the array is empty again

// convenience type checkers
j.is_null();
j.is_boolean();
j.is_number();
j.is_object();
j.is_array();
j.is_string();

// comparison
j == "[\"foo\", 1, true]"_json;  // true

// create an object
json o;
o["foo"] = 23;
o["bar"] = false;
o["baz"] = 3.141;

// find an entry
if (o.find("foo") != o.end()) {
  // there is an entry with key "foo"
}

Conversion from STL containers

Any sequence container (std::array, std::vector, std::deque, std::forward_list, std::list) whose values can be used to construct JSON types (e.g., integers, floating point numbers, Booleans, string types, or again STL containers described in this section) can be used to create a JSON array. The same holds for similar associative containers (std::set, std::multiset, std::unordered_set, std::unordered_multiset), but in these cases the order of the elements of the array depends how the elements are ordered in the respective STL container.

std::vector<int> c_vector {1, 2, 3, 4};
json j_vec(c_vector);
// [1, 2, 3, 4]

std::deque<float> c_deque {1.2, 2.3, 3.4, 5.6};
json j_deque(c_deque);
// [1.2, 2.3, 3.4, 5.6]

std::list<bool> c_list {true, true, false, true};
json j_list(c_list);
// [true, true, false, true]

std::forward_list<int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
json j_flist(c_flist);
// [12345678909876, 23456789098765, 34567890987654, 45678909876543]

std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
json j_array(c_array);
// [1, 2, 3, 4]

std::set<std::string> c_set {"one", "two", "three", "four", "one"};
json j_set(c_set); // only one entry for "one" is used
// ["four", "one", "three", "two"]

std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
json j_uset(c_uset); // only one entry for "one" is used
// maybe ["two", "three", "four", "one"]

std::multiset<std::string> c_mset {"one", "two", "one", "four"};
json j_mset(c_mset); // only one entry for "one" is used
// maybe ["one", "two", "four"]

std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
json j_umset(c_umset); // both entries for "one" are used
// maybe ["one", "two", "one", "four"]

Likewise, any associative key-value containers (std::map, std::multimap, std::unordered_map, std::unordered_multimap) whose keys are can construct an std::string and whose values can be used to construct JSON types (see examples above) can be used to to create a JSON object. Note that in case of multimaps only one key is used in the JSON object and the value depends on the internal order of the STL container.

std::map<std::string, int> c_map { {"one", 1}, {"two", 2}, {"three", 3} };
json j_map(c_map);
// {"one": 1, "two": 2, "three": 3}

std::unordered_map<const char*, float> c_umap { {"one", 1.2}, {"two", 2.3}, {"three", 3.4} };
json j_umap(c_umap);
// {"one": 1.2, "two": 2.3, "three": 3.4}

std::multimap<std::string, bool> c_mmap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_mmap(c_mmap); // only one entry for key "three" is used
// maybe {"one": true, "two": true, "three": true}

std::unordered_multimap<std::string, bool> c_ummap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_ummap(c_ummap); // only one entry for key "three" is used
// maybe {"one": true, "two": true, "three": true}

Implicit conversions

The type of the JSON object is determined automatically by the expression to store. Likewise, the stored value is implicitly converted.

/// strings
std::string s1 = "Hello, world!";
json js = s1;
std::string s2 = js;

// Booleans
bool b1 = true;
json jb = b1;
bool b2 = jb;

// numbers
int i = 42;
json jn = i;
double f = jn;

// etc.

You can also explicitly ask for the value:

std::string vs = js.get<std::string>();
bool vb = jb.get<bool>();
int vi = jn.get<int>();

// etc.

License

The class is licensed under the MIT License:

Copyright © 2013-2015 Niels Lohmann

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Thanks

I deeply appreciate the help of the following people.

• Teemperor implemented CMake support and lcov integration, realized escape and Unicode handling in the string parser, and fixed the JSON serialization.
• elliotgoodrich fixed an issue with double deletion in the iterator classes.
• kirkshoop made the iterators of the class composable to other libraries.
• wancw fixed a bug that hindered the class to compile with Clang.
• Tomas Åblad found a bug in the iterator implementation.
• Joshua C. Randall fixed a bug in the floating-point serialization and implemented code to parse streams incrementally.

Thanks a lot for helping out!

Execute unit tests

To compile and run the tests, you need to execute

$ make
$ ./json_unit

===============================================================================
All tests passed (4280 assertions in 16 test cases)

For more information, have a look at the file .travis.yml.