【C++】JSON for Modern C++

JSON(JavaScript Object Notation)格式作为一种数据格式，从最初作为JS语言的子集，以其易于阅读和处理的优势，逐渐被多种语言所支持，如Python/Java等，均提供了处理JSON格式文本的标准库/第三方库，因而脱离了某种编程语言的标签，成为一种通用的数据传输格式。

C++也出现了很多的开源库以支持JSON格式文本的处理，其特点各异，本文主要介绍其中一个—— Nlohmann JSON。

Nlohmann JSON库以C++11实现，主要设计目标为易用性，体现在该库可以通过一个头文件集成到任意项目，并且像STL容器一样操作JSON对象。但是并没有把内存消耗和运行速度作为重要的指标，因此在性能上可能不及一些以性能为主要设计目标的JSON库，如果对C++实现的各类JSON库运行性能对比感兴趣可以看这里。

先上开源库地址： https://github.com/nlohmann/json，本文的主要参考资料就是该库的README，下面的例子中使用的库版本为3.10.2。

一、集成

为支持单文件引入，每次Release版本中都会有一个json.hpp，只要下载并把它添加到项目中，然后在要处理JSON的文件中添加如下，并在编译时支持C++11(-std=c++11)就可以使用了。

#include "json.hpp" // 替换成放该json.hpp的路径

// 方便引用
using json = nlohmann::json;

二、使用

本节主要介绍此JSON库四种常用的对象构造方法和一种操作方法

1. 从零构造一个JSON对象

作为JSON库最最基础的用法，假设要创建一个这样的JSON对象：

{
  "pi": 3.141,
  "happy": true,
  "name": "Niels",
  "nothing": null,
  "answer": {
    "everything": 42
  },
  "list": [1, 0, 2],
  "object": {
    "currency": "USD",
    "value": 42.99
  }
}

使用这个库，可以这样写：

// 先创建一个空JSON结构(null)
json j;

// 然后添加一个Number值，在C++中被存储为double，j被隐式转换为object结构
j["pi"] = 3.141;

// 添加一个Boolean值，在C++中被存储为bool
j["happy"] = true;

// 添加一个String值，在C++中被存储为std::string
j["name"] = "Niels";

// 添加一个null对象，在C++中被存储为nullptr
j["nothing"] = nullptr;

// 在Object中添加Object
j["answer"]["everything"] = 42;

// 添加一个Array对象，在C++中被存储为std:vector(使用初始化列表)
j["list"] = { 1, 0, 2 };

// 添加一个Object，使用一对初始化列表
j["object"] = { {"currency", "USD"}, {"value", 42.99} };

// 也可以使用下面这种方法定义和上述相同结构的JSON对象
// 但个人不太推荐，花括号多到数组和对象很容易混
json j2 = {
  {"pi", 3.141},
  {"happy", true},
  {"name", "Niels"},
  {"nothing", nullptr},
  {"answer", {
    {"everything", 42}
  }},
  {"list", {1, 0, 2}},
  {"object", {
    {"currency", "USD"},
    {"value", 42.99}
  }}
};

2. 由字符串序列化

创建和解析JSON字符串是一种常见的操作。

可以通过在字符串后面添加_json创建JSON对象。（由C++11 用户定义字面量 特性支持）

// 通过字符串构造JSON对象
json j = "{ \"happy\": true, \"pi\": 3.141 }"_json;

// 或者使用原生字符串构造
auto j2 = R"(
  {
    "happy": true,
    "pi": 3.141
  }
)"_json;

// 也可以显式通过json::parse解析字符串
auto j3 = json::parse(R"({"happy": true, "pi": 3.141})");

相反的，可以通过.dump()方法将JSON对象转换成字符串

// 显式转换为字符串
std::string s = j.dump();    // {"happy":true,"pi":3.141}

// 向dump传入间隔的空格数，以打印格式易于阅读的字符串
std::cout << j.dump(4) << std::endl;
// {
//     "happy": true,
//     "pi": 3.141
// }

3. 像STL一样操作

为了使C++开发者易于上手，该库对JSON对象的操作模拟了常见的STL容器操作。

// 使用push_back创建Array
json j;
j.push_back("foo");
j.push_back(1);
j.push_back(true);

// 也可以使用C++11标准中的emplace_back
j.emplace_back(1.78);

// 通过iterator遍历这个Array
for (json::iterator it = j.begin(); it != j.end(); ++it) {
  std::cout << *it << '\n';
}

// 或者C++11中的范围for
for (auto& element : j) {
  std::cout << element << '\n';
}

// getter/setter
const auto tmp = j[0].get();   // .get() 显式转换获取值
bool foo = j.at(2); // .at(X) 隐式转换获取值，不过尽量避免使用隐式转换
j[1] = 42;

// 比较
j == R"(["foo", 1, true, 1.78])"_json;  // true

// 其他方法
j.size();     // 4
j.empty();    // false
j.type();     // json::value_t::array
j.clear();

// 类型检查的一些方法
j.is_null();
j.is_boolean();
j.is_number();
j.is_object();
j.is_array();
j.is_string();

// 查找
if (j.contains("foo")) {
    // JSON对象中有键名foo
}

// 或者通过iterator来查找
if (j.find("foo") != j.end()) {
    // JSON对象中有键名foo
}

// 或者用更简单的count()
int foo_present = j.count("foo"); // 1
int fob_present = j.count("fob"); // 0

// 删除
j.erase("foo");

4. 由STL容器构造

JSON对象可以由STL容器直接构造，但是由关联容器构造的JSON对象中键的顺序，由容器中元素的排序顺序决定。

#include "json.hpp" // 替换成放该json.hpp的路径
#include 
#include 
#include 
#include 
#include 

// 方便引用
using json = nlohmann::json;

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

    std::deque 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 c_list {true, true, false, true};
    json j_list(c_list);    // [true, true, false, true]

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

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

    std::set c_set {"one", "two", "three", "four", "one"};
    json j_set(c_set);      // ["four", "one", "three", "two"]

    std::unordered_set c_uset {"one", "two", "three", "four", "one"};
    json j_uset(c_uset);    // maybe ["two", "three", "four", "one"]

    std::multiset c_mset {"one", "two", "one", "four"};
    json j_mset(c_mset);    // maybe ["one", "two", "one", "four"]

    std::unordered_multiset c_umset {"one", "two", "one", "four"};
    json j_umset(c_umset);  // maybe ["one", "two", "one", "four"]


    return 0;
}

同样的，对于有键值对的关联容器，其键要能构造成std::string，它才能直接构造为JSON对象。

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

std::unordered_map 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 c_mmap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_mmap(c_mmap);    // maybe {"one": true, "two": true, "three": true}

std::unordered_multimap c_ummap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_ummap(c_ummap);  // maybe {"one": true, "two": true, "three": true}

5. 由自定义类型构造

除了STL容器，由自定义类型的对象构造JSON对象也是比较常用的操作。

当然，可以通过手动一个个拷贝键值对来完成，如下

// 一个简单的自定义结构
struct person {
    std::string name;
    std::string address;
    int age;
};

person p = {"Ned Flanders", "744 Evergreen Terrace", 60};

// person转换成JSON: 把自定义对象中的每个值都拷贝给JSON对象
json j;
j["name"] = p.name;
j["address"] = p.address;
j["age"] = p.age;

// ...

// 由JSON转成person: 把JSON对象中的每个值拷贝给自定义类型
person p {
    j["name"].get(),
    j["address"].get(),
    j["age"].get()
};

这样确实可行，但实在谈不上易用，所幸该库提供了一个更好的方法：

// 创建person类型对象
person p {"Ned Flanders", "744 Evergreen Terrace", 60};

// person -> json
json j = p;

std::cout << j << std::endl;
// {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}

// json -> person
auto p2 = j.get();

想要可以这样转换自定义类型，需要提供两个方法：

using json = nlohmann::json;

void to_json(json& j, const person& p) {
    j = json{{"name", p.name}, {"address", p.address}, {"age", p.age}};
}

void from_json(const json& j, person& p) {
    j.at("name").get_to(p.name);
    j.at("address").get_to(p.address);
    j.at("age").get_to(p.age);
}

就是这样，当由自定义类型person构造JSON时，会调用上面定义的void to_json(json& j, const person& p)。

相同的，由JSON转成自定义类型person时，会调用定义的void from_json(const json& j, person& p)。

完整范例代码如下：

#include 
#include "json.hpp" // 替换成放json.hpp的路径

// 方便引用
using json = nlohmann::json;

// 一个简单的自定义结构
struct person {
    std::string name;
    std::string address;
    int age;
};

// person -> json
void to_json(json& j, const person& p) {
    j = json{{"name", p.name}, {"address", p.address}, {"age", p.age}};
}

// json -> person
void from_json(const json& j, person& p) {
    j.at("name").get_to(p.name);
    j.at("address").get_to(p.address);
    j.at("age").get_to(p.age);
}

int main()
{
    person p = {"Ned Flanders", "744 Evergreen Terrace", 60};

    json j = p;

    std::cout << j << std::endl;

    auto p2 = j.get();

    return 0;
}

这种转换方法的优点是非侵入式，即无需修改原结构体的代码，在新建的文件中声明转换方法即可。

以上就是Nlohmann JSON库的常用用法了，更详尽的介绍可以详见README或者json.nlohmann.me。