Using JSON in Modern C++

In previous lessons, we covered how our programs can interact with data on our file system. We streamed data from our program to create new files, and read input from files to modify our program's state in some way.

In those examples, we read and write our data in unformatted strings. In this lesson, we’ll introduce the JSON format, and how to use it in C++

We’ll be using a popular third-party library, nlohmann::json, which lets us work much more quickly than trying to do everything ourselves.

The JSON Data Format

JSON (JavaScript Object Notation) is a text-based data format that is designed to be readable and understood by humans, whilst also being sufficiently structured to be easily parsed by machines.

Below is an example of a JSON document:

1{
2  "name": "Roderick",
3  "class": "Barbarian",
4  "level": 5,
5  "health": 100,
6  "isOnline": true,
7  "pet": null,
8  "guild": {
9    "name": "The Fellowship",
10    "members": 36
11  },
12  "equipment": [
13    {
14      "name": "Fiery Sword",
15      "damage": 5,
16      "critChance": 0.2
17    },
18    {
19      "name": "Iron Helmet",
20      "armor": 30,
21      "durability": 4
22    }
23  ]
24}

JSON documents are comprised of four primitive types and two structured types.

The primitive types are booleans, numbers, strings, and null. The structured types are objects and arrays.

From composing just these 6 basic types, we can describe almost anything.

Primitive Types: Booleans, Numbers, Strings, and null

Booleans, numbers, and strings in JSON broadly follow the same syntax as C++.

• Booleans are true or false values, which we represent by literals: true and false
• Numbers can be either integers or floating point, and we represent them by literals like 2, 3.14, and -6
• Strings are collections of characters, enclosed within double quotes, eg "Hello"
• The literal null represents an empty value, conceptually similar to keywords like nullptr and void in C++

A string, boolean, number, or null are, in isolation, valid examples of JSON. However, it is somewhat pointless to use JSON to store or transmit something so simple.

More typically, our JSON will be an object or an array.

Structured Type: Objects

Our previous example of an adventurer was a JSON object. Objects start with {, and end with }. Objects contain collections of key-value pairs, separated by commas: ,

1{
2  "movie": "Star Wars",
3  "released": true,
4  "year": 1977
5}

Each key is a string. The keys can contain spaces, but it’s typically avoided because it can make the JSON difficult to work with when it is imported into an environment where variables typically cannot contain spaces.

As such, we tend to use camelCase or snake_case for our key names.

The object values can be any type, including an array or another object:

1{
2  "movie": "Star Wars",
3  "released": true,
4  "year": 1977,
5  "director": {
6    "firstName": "George",
7    "surname": "Lucas",
8    "born": 1944
9  },
10  "cast": [
11    "Mark Hamill",
12    "Harrison Ford",
13    "Carrie Fisher"
14  ]
15}

Structured Type: Arrays

Within our previous example, the value under the "equipment" key was an example of an array. Arrays start with [, end with ] and contain a collection of values, separated by commas: ,

Each element in the array can be a value of any other type, including an object or a nested array.

1[4, null, { "ready": true }, [1, 2, 3], "hello"]

White Space

Similar to C++, JSON is generally not sensitive to spacing. The following are equivalent:

1{
2  "movie": "Star Wars",
3  "year": 1977,
4  "cast": [
5    "Mark Hamill",
6    "Harrison Ford",
7    "Carrie Fisher"
8  ]
9}

1{ "movie": "Star Wars", "year": 1977, "cast":
2[ "Mark Hamill", "Harrison Ford", "Carrie Fisher" ]
3}

When our JSON documents are formatted to be readable by humans, we tend to indent them in a similar way we indent code. However, this is not required - we are free to lay out our documents how we want.

Ordering

How we order keys within JSON objects is not significant. The following two objects are equivalent:

1{
2  "movie": "Star Wars",
3  "year": 1977,
4}

1{
2  "year": 1977,
3  "movie": "Star Wars",
4}

The library we’ll be using in this lesson tends to order keys in alphabetical order, but any ordering is valid.

However, the ordering of items within arrays is important. The following two arrays are not equivalent:

1["Mark Hamill", "Harrison Ford"]

1["Harrison Ford", "Mark Hamill"]

JSON for Modern C++ (nlohmann::json)

C++ does not natively support the JSON data format, but there are many options from third-party libraries we can choose from. In this lesson, we’ll use the "JSON for Modern C++" library, which is commonly referred to nlohmann::json among developers who are familiar with it.

The library’s homepage is available here: https://json.nlohmann.me/

We can install this library through our package manager. For example, vcpkg users can install it using the terminal command:

1.\vcpkg install nlohmann-json

Alternatively, given the library is "header-only", we can just grab the header and copy it into our project. The latest header is available from the GitHub releases page: https://github.com/nlohmann/json/releases/

From the "assets" section at the bottom of the release, we should download json.hpp and copy it into our project.

Once we’ve acquired the library, we then #include it in our files in the normal way. The exact path will depend on how our include directories are set up, and where the header file is located. But, we likely need either:

1#include <nlohmann/json.hpp>

Or:

1#include <json.hpp>

Once included, the most important class within this library is nlohman::json, which we typically alias to json:

1#include <json.hpp>
2using json = nlohmann::json;
3
4int main() {
5  json Document;
6}

Parsing JSON Documents

The nlohmann::json class includes the static method parse, which is one of the ways we can convert a raw JSON string to a nlohmann::json object:

1#include <json.hpp>
2using json = nlohmann::json;
3
4int main() {
5  std::string Data{
6      R"({ "name": "Roderick", "role": "Barbarian" })"};
7
8  json Doc{json::parse(Data)};
9}

Once we’ve created a nlohmann::json object from our string, we can begin working with it using regular C++ techniques.

Similar to standard library containers such as arrays and maps, we can read values from the JSON objects using the [] operator.

When reading from JSON objects, we’d pass the name of the key we want to access:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{
7      R"({ "name": "Roderick", "role": "Barbarian" })"};
8
9  json Doc{json::parse(Data)};
10
11  std::string Name{Doc["name"]};
12  std::string Role{Doc["role"]};
13
14  std::cout << "Name: " << Name;
15  std::cout << "\nRole: " << Role;
16}

1Name: Roderick
2Role: Barbarian

When reading from JSON arrays, we’d instead pass the numeric index we want to read:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(["Roderick", "Anna"])"};
7
8  json Doc{json::parse(Data)};
9
10  std::string Player1{Doc[0]};
11  std::string Player2{Doc[1]};
12
13  std::cout << "Player 1: " << Player1;
14  std::cout << "\nPlayer 2: " << Player2;
15}

1Player 1: Roderick
2Player 2: Anna

We can chain the [] operator to read deeply nested values:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian",
10      "guild": {
11        "name": "The Bandits"
12      },
13      "equipment": [{
14        "name": "Iron Sword",
15        "damage": 5
16      }]
17    }
18  )"};
19
20  json Doc{json::parse(Data)};
21
22  std::string GuildName{Doc["guild"]["name"]};
23  int WeaponDamage{
24      Doc["equipment"][0]["damage"]};
25
26  std::cout << "Guild Name: " << GuildName;
27  std::cout << "\nWeapon Damage: "
28            << WeaponDamage;
29}

1Guild Name: The Bandits
2Weapon Damage: 5

As an alternative to the [] operator, we can instead use the at method.

The main difference is that the at method throws an exception if the key or index we’re trying to access does not exist:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian"
10    }
11  )"};
12
13  json Doc{json::parse(Data)};
14
15  try {
16    Doc.at("does-not-exist");
17  } catch (...) {
18    std::cout << "That didn't work!";
19  }
20}

1That didn't work!

Handling Invalid JSON and Exceptions

Exceptions from the library all inherit from nlohmann::json::exception, which inherits from std::exception:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian"
10    }
11  )"};
12
13  json Doc{json::parse(Data)};
14
15  try {
16    Doc.at("does-not-exist");
17  } catch (json::exception e) {
18    std::cout << e.what();
19  }
20}

1[json.exception.out_of_range.403]
2key 'does-not-exist' not found

The most likely problem we’ll encounter when first using JSON is that our JSON strings are invalid. Attempting to convert such a string to a JSON object will result in a nlohmann::json::parse exception.

In the following example, we removed the closing } from our JSON string, making it invalid:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian"
10    } 
11  )"};
12
13  try {
14    json Doc{json::parse(Data)};
15  } catch (json::parse_error e) {
16    std::cout << e.what();
17  }
18}

1[json.exception.parse_error.101]
2parse error at line 6, column 3
3syntax error while parsing object
4unexpected end of input; expected '}'

The json::accept method can tell us if a string is valid JSON before we try to parse it:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian"
10    }
11  )"};
12
13  if (json::accept(Data)) {
14    std::cout << "It looks valid!";
15  }
16}

1It looks valid!

A thorough list of all exceptions that can occur is available on the official site: https://json.nlohmann.me/home/exceptions/

Mapping JSON Types to C++ Types

The previous examples implicitly map types within the JSON document to C++ types like std::string and int. This is generally okay for simple types like these, but the approach can run into issues when dealing with more complex types.

As such, there are alternative, more recommended ways of converting JSON content to C++ types.

The get method on the nlohmann::json class has a template parameter that allows us to specify the exact conversion we want.

For example, to get the name value from a JSON document as a std::string, we’d use this function call:

1Doc["name"].get<std::string>()

Below, we explicitly create a std::string from a JSON string, and a std::vector from a JSON array:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"({
7    "greeting": "Hello!",
8    "numbers": [1, 2, 3]
9  })"};
10
11  json Doc{json::parse(Data)};
12
13  auto Greeting{
14      Doc["greeting"].get<std::string>()};
15
16  auto Numbers{
17      Doc["numbers"].get<std::vector<int>>()};
18
19  std::cout << Greeting << '\n';
20
21  for (int i : Numbers) {
22    std::cout << i;
23  }
24}

1Hello!
2123

We’re not restricted to using get() on part of the JSON document. Sometimes we’ll want to convert the entire document into a specific C++ type. Below, our entire document is a JSON array, which we insert into a std::vector:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  json Doc{json::parse(R"([1, 2, 3])")};
7
8  auto Numbers{Doc.get<std::vector<int>>()};
9
10  for (int i : Numbers) {
11    std::cout << i;
12  }
13}

1123

When the variable we want to store the data in already exists, we can use the get_to method instead. This can automatically infer the required type, using the type of argument we pass to the function:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  json Doc{json::parse(R"([1, 2, 3])")};
7
8  std::vector<int> Numbers;
9  Doc.get_to(Numbers);
10
11  for (int i : Numbers) {
12    std::cout << i;
13  }
14}

1123

Creating C++ Maps from JSON Objects

We can convert JSON objects to associative containers, such as std::map, using the same get and get_to methods we covered previously:

1#include <iostream>
2#include <json.hpp>
3#include <map>
4using json = nlohmann::json;
5
6int main() {
7  std::string Data{R"(
8    {
9      "name": "Roderick",
10      "role": "Barbarian"
11    }
12  )"};
13
14  json Doc{json::parse(Data)};
15
16  std::map<std::string, std::string> Map;
17  Doc.get_to(Map);
18
19  std::cout << "Name: " << Map["name"];
20  std::cout << "\nRole: " << Map["role"];
21}

Generally, this will only be useful if every value in our JSON object has the same type, such as strings in the previous examples.

More commonly, our object values will span a variety of types, in which case we’ll generally want to store them in a user-defined class or struct. We’ll show you how to set that up later in this lesson.

Outputting JSON to Streams

The nlohmann::json type has been set up to interact with stream operators, so we can easily send its contents to any stream. For example, we can view its contents by sending it to std::cout:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian"
10    }
11  )"};
12
13  json Doc{json::parse(Data)};
14
15  std::cout << Doc;
16}

1{"name":"Roderick","role":"Barbarian"}

We’re not restricted to streaming the entire document - we can stream any sub-part of the JSON tree:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian",
10      "guild": {
11        "name": "The Bandits"
12      }
13    }
14  )"};
15
16  json Doc{json::parse(Data)};
17
18  std::cout << Doc["guild"];
19}

1{"name":"The Bandits"}

Additionally, the dump() method returns the current state of the JSON tree, or any sub-part, as a std::string

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian",
10      "guild": {
11        "name": "The Bandits"
12      }
13    }
14  )"};
15
16  json Doc{json::parse(Data)};
17  std::string JSON{Doc.dump()};
18
19  std::cout << JSON;
20}

1{"guild":{"name":"The Bandits"},"name":"Roderick","role":"Barbarian"}

The dump() method accepts an optional numeric argument. If provided, additional spacing for new lines and indentation will be added to our string. This will make it easier to read for humans.

The value of the numeric argument specifies how many spaces we want to use for indentation. The most common selections are 2 or 4:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian",
10      "guild": {
11        "name": "The Bandits"
12      }
13    }
14  )"};
15
16  json Doc{json::parse(Data)};
17
18  std::cout << Doc.dump(2);
19}

1{
2  "guild": {
3    "name": "The Bandits"
4  },
5  "name": "Roderick",
6  "role": "Barbarian"
7}

This can help with debugging but, generally, we don’t want to use this for real systems. The additional space characters make our JSON documents bigger, and slightly slower to parse for computers.

Meanwhile, humans who are regularly working with JSON documents will already have the tools to format them into a human-friendly format when needed. JSON formatting is a standard feature of most code editors, either natively or as a plugin.

Supporting JSON in User-Defined Types

To make our custom types compatible with nlohmann::json, we need to provide two functions:

• to_json, which provides a reference to a JSON object, and a const reference to our custom object. We update the JSON object based on the state of our custom object.
• from_json, which provides a const reference to a JSON object, and a reference to our custom object. We update our custom object, based on the contents of the JSON object.

The following shows how we can set this up with a simple Character type:

1#pragma once
2#include <json.hpp>
3#include <string>
4using json = nlohmann::json;
5
6class Character {
7 public:
8  std::string Name;
9  int Level;
10};
11
12void to_json(json& j, const Character& C) {
13  j = json{{"Name", C.Name},
14           {"Level", C.Level}};
15}
16
17void from_json(const json& j, Character& C) {
18  j.at("Name").get_to(C.Name);
19  j.at("Level").get_to(C.Level);
20}

With those changes in place, we can use functions like get and get_to with our custom type:

1#include <iostream>
2#include <json.hpp>
3#include "Character.h"
4using json = nlohmann::json;
5
6int main() {
7  std::string Data{R"(
8    {
9      "Name": "Roderick",
10      "Level": 10
11    }
12  )"};
13
14  json Doc{json::parse(Data)};
15
16  Character Player;
17  Doc.get_to(Player);
18
19  std::cout << "Name: " << Player.Name;
20  std::cout << "\nLevel: " << Player.Level;
21}

1Name: Roderick
2Level: 10

Similarly, we can easily generate a JSON representation of our objects:

1#include <iostream>
2#include <json.hpp>
3#include "Character.h"
4using json = nlohmann::json;
5
6int main() {
7  Character Player{"Roderick", 10};
8  json Doc(Player);
9
10  std::cout << Doc.dump(2);
11}

1{
2  "Level": 10,
3  "Name": "Roderick"
4}

Note, our initialization of Doc above is using parenthesis ( and ) when we’d typically use braces { and }

This is because the nlohmann::json type can be created from an initializer list, and that is how our code would have been interpreted had we used braces. Even though we pass only one argument, it would be treated as a list of length 1.

This results in the creation of a JSON array, when we may instead have intended to create a JSON object.

1#include <iostream>
2#include <json.hpp>
3#include "Character.h"
4using json = nlohmann::json;
5
6int main() {
7  Character Player1{"Roderick", 10};
8  Character Player2{"Anna", 15};
9
10  json DocA(Player1);
11  json DocB{Player1};
12  json DocC{Player1, Player2};
13
14  std::cout << "Doc A:\n" << DocA.dump(2);
15  std::cout << "\n\nDoc B:\n" << DocB.dump(2);
16  std::cout << "\n\nDoc C:\n" << DocC.dump(2);
17}

1Doc A:
2{
3  "Level": 10,
4  "Name": "Roderick"
5}
6
7Doc B:
8[
9  {
10    "Level": 10,
11    "Name": "Roderick"
12  }
13]
14
15Doc C:
16[
17  {
18    "Level": 10,
19    "Name": "Roderick"
20  },
21  {
22    "Level": 15,
23    "Name": "Anna"
24  }
25]

Using Serialization Macros in User-Defined Types

In our previous example where we added JSON serialization to our custom type, we defined full-fledged to_json and from_json functions.

1void to_json(json& j, const Character& C) {
2  j = json{{"Name", C.Name},
3           {"Level", C.Level}};
4}
5
6void from_json(const json& j, Character& C) {
7  j.at("Name").get_to(C.Name);
8  j.at("Level").get_to(C.Level);
9}

This gave us a lot of flexibility but is not always necessary. The nlohmann::json library includes some macros that cover most use cases.

The above code can be replaced with this macro call, which will generate the two required functions:

1NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(Character,
2                                   Name,
3                                   Level)

The first argument to the macro is the type we want to add serialization capabilities to. The remaining arguments are the names of the fields we want to serialize. This assumes that the fields we want to serialize are public within our class or struct.

If they’re not public, we can instead use the "intrusive" form of our macro, within the public area of our class:

1#pragma once
2#include <json.hpp>
3#include <string>
4using json = nlohmann::json;
5
6class Character {
7 public:
8  std::string Name;
9  int GetLevel() { return Level; }
10
11  NLOHMANN_DEFINE_TYPE_INTRUSIVE(Character,
12                                 Name,
13                                 Level)
14
15 private:
16  int Level;
17};

Both of these macros also assume the name of the fields we want to serialize within our class in our class identically match the name of the corresponding keys within the JSON. If that’s not the case, we need to revert to writing the to_json and from_json functions manually.

Creating JSON Documents from C++ Data

JSON documents from the nlohmann::json library correctly implement the = operator, so we can create and update their values as we might expect:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  json Doc;
7  Doc["name"] = "Roderick";
8  Doc["role"] = "Barbarian";
9  Doc["guild"]["name"] = "The Bandits";
10
11  std::cout << Doc.dump(2);
12}

1{
2  "guild": {
3    "name": "The Bandits"
4  },
5  "name": "Roderick",
6  "role": "Barbarian"
7}

We can create arrays as lists of values, and objects as lists of pairs, where the first element is the key, and the second element is the value:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  json Doc;
7  Doc["movie"] = "Star Wars";
8  Doc["released"] = true;
9  Doc["year"] = 1977;
10
11  // Array
12  Doc["cast"] = {"Mark Hamill", "Harrison Ford",
13                 "Carrie Fisher"};
14
15  // Object
16  Doc["director"] = {{"name", "George Lucas"},
17                     {"born", 1944}};
18
19  // Array of Objects
20  Doc["similar_movies"] = {
21      {{"name", "Dune"}, {"year", 2021}},
22      {{"name", "Rogue One"}, {"year", 2016}}};
23
24  std::cout << Doc.dump(2);
25}

1{
2  "cast": [
3    "Mark Hamill",
4    "Harrison Ford",
5    "Carrie Fisher"
6  ],
7  "director": {
8    "born": 1944,
9    "name": "George Lucas"
10  },
11  "movie": "Star Wars",
12  "released": true,
13  "similar_movies": [
14    {
15      "name": "Dune",
16      "year": 2021
17    },
18    {
19      "name": "Rogue One",
20      "year": 2016
21    }
22  ],
23  "year": 1977
24}

The library implements appropriate converters for standard library containers, so we can automatically generate JSON arrays from containers like std::array and std::vector. We can also generate JSON objects from associative containers, like a std::map.

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::vector Cast{"Mark Hamill",
7                   "Harrison Ford",
8                   "Carrie Fisher"};
9
10  json Doc;
11  Doc["cast"] = Cast;
12
13  std::cout << Doc.dump(2);
14}

1{
2  "cast": [
3    "Mark Hamill",
4    "Harrison Ford",
5    "Carrie Fisher"
6  ]
7}

When we want to create a JSON document from a string, we can use the parse method, as described right at the start of the lesson.

However, there is a more succinct way of doing it. By including a using statement for the nlohmann::literals namespace, we can create a nlohmann::json by appending _json to the end of a raw string. It looks like this:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  using namespace nlohmann::literals;
7  json Doc{R"({
8    "movie": "Star Wars",
9    "released": true,
10    "year": 1977,
11    "cast": [
12      "Mark Hamill",
13      "Harrison Ford",
14      "Carrie Fisher"
15    ],
16    "director": {
17      "born": 1944,
18      "name": "George Lucas"
19    }
20  })"_json};
21
22  std::cout << Doc.dump(2);
23}

1{
2  "cast": [
3    "Mark Hamill",
4    "Harrison Ford",
5    "Carrie Fisher"
6  ],
7  "director": {
8    "born": 1944,
9    "name": "George Lucas"
10  },
11  "movie": "Star Wars",
12  "released": true,
13  "year": 1977
14}

Alternatively, we can define our JSON document using C++ syntax, by combining a composition of lists and pairs:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  json Doc{
7      {"movie", "Star Wars"},
8      {"released", true},
9      {"year", 1977},
10      {"cast", {1, 0, 2}},
11      {"director",
12       {{"name", "George Lucas"},
13        {"born", 1944}}},
14      {"related_movies",
15       {{{"name", "Rogue One"}, {"year", 2016}},
16        {{"name", "Dune"}, {"year", 2021}}}}};
17
18  std::cout << Doc.dump(2);
19}

This can get quite difficult to follow for more complex documents. The raw string approach is generally going to be more readable.

However, unlike raw strings, the C++ style makes it easier to weave in C++ objects and containers. This is a more common requirement than creating static JSON documents from strings. It looks like this:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5struct Person {
6  std::string name;
7  int born;
8};
9NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(Person,
10                                   name,
11                                   born)
12
13struct RelatedMovie {
14  std::string name;
15  int year;
16};
17NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(RelatedMovie,
18                                   name,
19                                   year)
20
21int main() {
22  Person Director{"George Lucas", 1944};
23
24  std::vector<std::string> Cast{
25      "Mark Hamill", "Harrison Ford",
26      "Carrie Fisher"};
27
28  std::vector<RelatedMovie> RelatedMovies{
29      {"Rogue One", 2016}, {"Dune", 2021}};
30
31  json Doc{{"movie", "Star Wars"},
32           {"released", true},
33           {"year", 1977},
34           {"cast", Cast},
35           {"director", Director},
36           {"related_movies", RelatedMovies}};
37
38  std::cout << Doc.dump(2);
39}

1{
2  "cast": [
3    "Mark Hamill",
4    "Harrison Ford",
5    "Carrie Fisher"
6  ],
7  "director": {
8    "born": 1944,
9    "name": "George Lucas"
10  },
11  "movie": "Star Wars",
12  "related_movies": [
13    {
14      "name": "Rogue One",
15      "year": 2016
16    },
17    {
18      "name": "Dune",
19      "year": 2021
20    }
21  ],
22  "released": true,
23  "year": 1977
24}

Reading and Writing JSON Files

The nlohmann::json type has implemented the stream operators >> and << to allow us to read and write our JSON documents to any stream, including file streams.

We covered accessing the file system, and using file streams in dedicated lessons earlier in the course:

Working with the File System

Create, delete, move, and navigate through directories and files using the standard library's filesystem module.

File Streams

A detailed guide to reading and writing files in C++ using the standard library’s fstream type

Below, we save our JSON to a file on our hard drive:

1#include <fstream>
2#include <json.hpp>
3
4using json = nlohmann::json;
5
6int main() {
7  using namespace nlohmann::literals;
8  json Doc{R"({
9    "movie": "Star Wars",
10    "released": true,
11    "year": 1977
12  })"_json};
13
14  std::fstream File;
15  File.open(R"(c:\test\file.json)",
16            std::ios::out);
17
18  File << Doc;
19}

The json::parse method accepts an input stream as an argument, which allows us to generate a JSON document from a file stream. Below, we read the file from our hard drive that the previous example created:

1#include <fstream>
2#include <iostream>
3#include <json.hpp>
4
5using json = nlohmann::json;
6
7int main() {
8  std::fstream File;
9  File.open(R"(c:\test\file.json)",
10            std::ios::in);
11
12  json Doc{json::parse(File)};
13
14  std::cout << Doc.dump(2);
15}

1{
2  "movie": "Star Wars",
3  "released": true,
4  "year": 1977
5}

Saving and Restoring Program State using JSON

Our previous lesson on file streams included a lesson showing how we can save and load the state of objects in our program using files on the user’s hard drive. That example used unstructured strings. Below, we upgrade our approach to use JSON instead:

1#pragma once
2#include <json.hpp>
3#include <string>
4using json = nlohmann::json;
5
6class Character {
7 public:
8  std::string Name;
9  int Level;
10};
11
12NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(Character,
13                                   Name,
14                                   Level)

1#include <filesystem>
2#include <fstream>
3#include <iostream>
4#include "Character.h"
5
6namespace fs = std::filesystem;
7
8int main() {
9  Character Player;
10
11  std::fstream File;
12  fs::directory_entry SaveFile{
13      R"(c:\test\savefile.json)"};
14
15  if (SaveFile.is_regular_file()) {
16    std::cout << "Loading a saved game\n";
17    File.open(SaveFile, std::ios::in);
18    json Data = json::parse(File);
19    Data.get_to(Player);
20  } else {
21    std::cout << "Starting a new game\n";
22    File.open(SaveFile, std::ios::out);
23    Player.Name = "Conan";
24    Player.Level = 1;
25    json Data = Player;
26    File << Data;  
27  }
28
29  File.close();
30
31  std::cout << "Name: " << Player.Name;
32  std::cout << "\nLevel: " << Player.Level;
33}

The first run of our program saves a file on our hard drive, and generates this output:

1Starting a new game
2Name: Conan
3Level: 1

Subsequent runs read the file, and generate this output:

1Loading a saved game
2Name: Conan
3Level: 1

Iterating Over JSON Documents

JSON documents include support for iterators, allowing us to traverse over values in our JSON objects, or elements in our JSON arrays.

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian",
10      "level": 10,
11      "guild": {"name": "The Bandits" }
12    }
13  )"};
14
15  json Doc{json::parse(Data)};
16
17  for (auto& Item : Doc) {
18    std::cout << Item << '\n';
19  }
20}

1{"name":"The Bandits"}
210
3"Roderick"
4"Barbarian"

If we want access to both keys and values, we have two options. We can directly use the iterators, which include key and value methods:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian",
10      "level": 10,
11      "guild": {"name": "The Bandits" }
12    }
13  )"};
14
15  json Doc{json::parse(Data)};
16
17  for (auto it = Doc.begin(); it != Doc.end();
18       ++it) {
19    std::cout << "Key: " << it.key()
20              << ", Value: " << it.value()
21              << '\n';
22  }
23}

1Key: guild, Value: {"name":"The Bandits"}
2Key: level, Value: 10
3Key: name, Value: "Roderick"
4Key: role, Value: "Barbarian"

Alternatively, we can use the items() method, which returns a collection of key-value pairs. This is compatible with a range-based for loop:

1for (auto& Item : Doc.items()) {
2  std::cout << "Key: " << Item.key()
3            << ", Value: " << Item.value()
4            << '\n';
5}

Each pair also supports structured binding:

1for (auto& [key, value] : Doc.items()) {
2  std::cout << "Key: " << key
3            << ", Value: " << value << '\n';
4}

Note, that neither of these methods is recursive - they only iterate over the first-level keys or values that they’re called upon. If needed, we could build our recursive code to traverse documents deeply. The is_structured() method, covered later in this lesson, would be helpful for this.

Comparing JSON Documents

The nlohmann::json type overloads the == and != operators, allowing us to compare JSON documents:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "role": "Barbarian"
10    }
11  )"};
12
13  std::string Data2{R"(
14    {
15      "role": "Barbarian",
16      "name": "Roderick"
17    }
18  )"};
19
20  json Doc1{json::parse(Data)};
21  json Doc2{json::parse(Data)};
22
23  if (Doc1 == Doc2) {
24    std::cout << "Documents are equivalent\n";
25  }
26
27  Doc1["name"] = "Anna";
28
29  if (Doc1 != Doc2) {
30    std::cout << "Not any more!";
31  }
32}

1Documents are equivalent
2Not any more!

Additional Utility Methods

The nlohmann::json library includes a range of additional methods we may find situationally helpful:

JSON Type Checkers

We can check the type of our JSON document, or any element within it, using a range of helper methods:

• is_number() returns true if the element is any number
• is_number_integer() returns true if the element is an integer
• is_number_float() returns true if the element is a floating point number
• is_boolean() returns true if the element is a boolean
• is_null() returns true if the element is a null
• is_string() returns true if the element is a string
• is_array() returns true if the element is an array
• is_object() returns true if the element is an object
• is_primitive() returns true if the element is a number, boolean, null, or string
• is_structured() returns true if the element is an array or object

Some examples of using these methods are below:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "level": 10
10    }
11  )"};
12
13  json Doc{json::parse(Data)};
14
15  if (Doc.is_object()) {
16    std::cout << "Document is a JSON object\n";
17  }
18
19  if (Doc.at("name").is_string()) {
20    std::cout << "Name is a JSON string\n";
21  }
22
23  if (Doc.at("level").is_number()) {
24    std::cout << "Level is a JSON number\n";
25  }
26}

1Document is a JSON object
2Name is a JSON string
3Level is a JSON number

The size() and empty() Methods

We can use the size() method to find out how big our document, or part of a document, is. The return value varies depending on the JSON type we’re calling it on:

• For objects, size() returns the number of keys
• For arrays, size() returns the number of elements
• For strings, booleans, and numbers, size() returns 1
• For null values or missing keys, size() returns 0

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "level": 10,
10      "equipment": [{}, {}]
11    }
12  )"};
13
14  json Doc{json::parse(Data)};
15
16  std::cout << "Document Size: " << Doc.size();
17  std::cout << "\nEquipment Size: "
18            << Doc.at("equipment").size();
19  std::cout << "\nEquipment[0] Size: "
20            << Doc.at("equipment")[0].size();
21}

1Document Size: 3
2Equipment Size: 2
3Equipment[0] Size: 0

If we want to check if size() == 0, we can use the empty() method instead:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  std::string Data{R"(
7    {
8      "name": "Roderick",
9      "level": 10,
10      "equipment": []
11    }
12  )"};
13
14  json Doc{json::parse(Data)};
15
16  if (Doc.at("equipment").empty()) {
17    std::cout << "No equipment!";
18  }
19}

1No equipment!

The contains() Method

The contains method allows us to check if our JSON contains a specific key. It will return true if it does, even if the corresponding value for that key is null.

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  using namespace nlohmann::literals;
7  json Doc{
8      R"({
9        "name": "Anna",
10        "level": 10,
11        "guild": { "name": null }
12      })"_json};
13
14  if (Doc.contains("name")) {
15    std::cout << "Doc contains name";
16  }
17
18  if (!Doc.contains("age")) {
19    std::cout << "\nDoc does not contain age";
20  }
21
22  if (Doc.at("guild").contains("name")) {
23    std::cout << "\nGuild contains name";
24  }
25}

1Doc contains name
2Doc does not contain age
3Guild contains name

The erase() Method

The erase method is useful for either removing a key from a JSON object, or removing an element from a JSON array.

Below, we erase the element at index 0 of the equipment array, then erase the level from the top-level document:

1#include <iostream>
2#include <json.hpp>
3using json = nlohmann::json;
4
5int main() {
6  using namespace nlohmann::literals;
7  json Doc{
8      R"({
9        "name": "Anna",
10        "level": 10,
11        "equipment": ["Weapon", "Armor"]
12      })"_json};
13
14  Doc.at("equipment").erase(0);
15  std::cout << "Doc:\n" << Doc;
16
17  Doc.erase("level");
18  std::cout << "\n\nDoc:\n" << Doc;
19}

1Doc:
2{"equipment":["Armor"],"level":10,"name":"Anna"}
3
4Doc:
5{"equipment":["Armor"],"name":"Anna"}