JsonCpp 使用指导
前言
JSON 是一种轻量级数据交换格式。它可以表示数据、字符串、有序的值序列以及名称/值对的集合。
JsonCpp 是一个 C++ 库，允许操作 JSON 值，包括字符串之间的序列化和反序列化。它还可以在反序列化/序列化步骤中保留现有注释，使其成为存储用户输入文件的方便格式。
JsonCpp 目前在 github 上托管。
官方网址：https://github.com/open-source-parsers/jsoncpp
安装 JsonCpp 开发包
在 ubuntu 系统既可以通过命令行安装也可以使用界面进行安装。
- 命令行安装：
sudo apt install -y libjsoncpp-dev
- 使用软件包管理器进行安装，启动 Synaptic 软件，搜索
jsoncpp关键字，在过滤出来的条目中点击 libjsoncpp-dev 然后选择 “Mark for Installation”：
扩展阅读：Synaptic 软件的介绍及安装使用教程可参考: Ubuntu 软件包管理利器 - 新立得 (Synaptic)
嵌入式开发
如果需要在嵌入式系统使用 JsonCpp 可以参考《交叉编译 JsonCpp 库》一文，利用交叉编译器编译出 JsonCpp 头文件及静态/动态库文件。
用法
头文件
#include 头文件中包含了 Reader, Writer, Value 这三个重要的类。
读取 json 数据
按照国际惯例，每一项技术的学习都可以从 “Hello World” 开始，以下面的 json 字符串为例：
{"content": "Hello JsonCpp"}
使用 Reader 和 Value 读取 content 的值：
#include 在 ubuntu 系统上编译：
g++ -I/usr/include/jsoncpp -o hello hello.cpp -ljsoncpp
运行结果：
$ ./hello
Hello JsonCpp
在源码第 9~10 行，定义了两个对象 reader 和 root:
Json::Reader reader;
Json::Value root;
在源码第 11~12 行，调用 Reader.parse() 接口尝试解析 json 字符串 str，当 str 满足 json 格式之后，调用 Value 的 [] 操作符将 “content” 的值取出来，然后再进行类型转换，取出实际的类型数据：
if (reader.parse(str, root))
std::cout << root["content"].asString() << std::endl;
关于类型数据的转换在接下来的章节进行详细说明。
值类型
JsonCpp 支持的值类型总共有 8 种：
| enum | ValueType | Description |
|---|---|---|
| 0 | nullValue | ‘null’ value |
| 1 | intValue | signed integer value |
| 2 | unsigned int | unsigned integer value |
| 3 | realValue | double value |
| 4 | stringValue | UTF-8 string value |
| 5 | booleanValue | bool value |
| 6 | arrayValue | array value (ordered list) |
| 7 | objectValue | object value (collection of name/value pairs) |
可以参考 json/value.h 头文件中定义的 enum ValueType。在 Value 类中提供了 type() 用于获取值类型（ValueType），type() 定义如下：
class Value {
...
ValueType type() const;
...
};
类型判断
如果需要进行类型判断，Json::Value 已经提供了完备的类型判断接口供调用：
class Value {
...
bool isNull() const;
bool isBool() const;
bool isInt() const;
bool isInt64() const;
bool isUInt() const;
bool isUInt64() const;
bool isIntegral() const;
bool isDouble() const;
bool isNumeric() const;
bool isString() const;
bool isArray() const;
bool isObject() const;
...
};
其中这里有两个接口比较特殊，一个是 isNumeric() 另一个是 isIntegral()。
先对 isNumeric() 进行说明，字面意思就是“是否为数字”，实际上在 Json::Value 类的实现中等同于 isDouble()，因此这两个函数是等效的，实现代码如下：
bool Value::isNumeric() const { return isDouble(); }
在使用过程中可以直接用 isDouble() 代替 isNumeric()，反之亦然。
isIntegral() 的作用主要是对浮点型数据的值进行了严格限制，如果类型为 int 或者 uint，该接口直接返回真值。如果类型为 double，因为 maxUInt64（ = 2 64 − 1 =2^{64}-1 =264−1）不能精确表示为 double，因此 double（maxUInt64）将四舍五入为 2 64 2^{64} 264。因此，我们要求该值严格小于限制。
类型转换
当需要进行类型转换时，Json::Value 已经提供了常用的类型转换接口供调用：
class Value {
...
const char *asCString() const;
String asString() const;
Int asInt() const;
Int64 asInt64() const;
UInt asUInt() const;
UInt64 asUInt64() const;
float asFloat() const;
double asDouble() const;
bool asBool() const;
...
};
| Type | Interface | Content |
|---|---|---|
const char * |
asCString() |
转换成 C 字符串 const char * |
String |
asString() |
转换成 C++ 字符串 std::string |
Int |
asInt() |
转换成 int 型 |
Int64 |
asInt64() |
转换成 64 位 int 型 |
UInt |
asUInt() |
转换成 unsigned int 型 |
UInt64 |
asUInt64() |
转换成 64 位 unsigned int 型 |
float |
asFloat() |
转换成 float 型 |
double |
asDouble() |
转换成 double 型 |
bool |
asBool() |
转换成 bool 型 |
键值判断
Value.isMember() 接口用于判断 json 字符串中是否存在某个键值，函数原型：
class Value {
...
/// Return true if the object has a member named key.
/// \note 'key' must be null-terminated.
bool isMember(const char* key) const;
/// Return true if the object has a member named key.
/// \param key may contain embedded nulls.
bool isMember(const String& key) const;
/// Same as isMember(String const& key)const
bool isMember(const char* begin, const char* end) const;
...
};
判断 “content” 是否为 json 的键：
root.isMember("content");
结合类型判断接口，如果需要确定 json 中是否存在 “content” 键值，并且 “content” 的值为 string 类型，可以加入这样的判断条件：
if (root.isMember("content") && root["content"].isString()) {
// do something...
val = root["content"].asString();
}
遍历 json 数据
Value::Members 对象存储了 json 的 key 列表，原型是一个字符串的矢量数组：
class Value {
...
using Members = std::vector<String>;
...
};
可以通过 Value.getMemberNames() 接口获取，示例代码如下：
Json::Value root;
if (reader.parse(str, root)) {
Json::Value::Members mem = root.getMemberNames();
for (auto key : mem)
std::cout << key << std::endl;
}
如果需要将 json 的内容全部遍历出来，可以使用递归的方式来达成。
- 从最外层开始进入
- 如果是 Object 类型，利用
getMemberNames()接口遍历所有的key值 - 如果在遍历过程中遇到 Object/Array 类型，则递归从步骤 1 开始
- 如果是普通类型，直接打印
示例代码如下，其中 print_json() 递归执行：
void show_value(const Json::Value &v) {
if (v.isBool()) {
std::cout << v.asBool() << std::endl;
} else if (v.isInt()) {
std::cout << v.asInt() << std::endl;
} else if (v.isInt64()) {
std::cout << v.asInt64() << std::endl;
} else if (v.isUInt()) {
std::cout << v.asUInt() << std::endl;
} else if (v.isUInt64()) {
std::cout << v.asUInt64() << std::endl;
} else if (v.isDouble()) {
std::cout << v.asDouble() << std::endl;
} else if (v.isString()) {
std::cout << v.asString() << std::endl;
}
}
void print_json(const Json::Value &v) {
if (v.isObject() || v.isNull()) {
Json::Value::Members mem = v.getMemberNames();
for (auto key : mem) {
std::cout << key << "\t: ";
if (v[key].isObject()) {
std::cout << std::endl;
print_json(v[key]);
} else if (v[key].isArray()) {
std::cout << std::endl;
for (auto i = 0; i < v[key].size(); i++)
print_json(v[key][i]);
} else
show_value(v[key]);
}
} else
show_value(v);
}
体现在用法上就是直接将 Json::Value 作为参数代入函数接口：
Json::Value root;
if (reader.parse(str, root))
print_json(root);
读取数组
JsonCpp 提供了多种方式来读取数组，可以利用下标进行读取，可以使用 iterator 进行读取，也可以直接使用 C++11 特性进行读取。下面是一个简单例子：
{ "list": [1, 2, 3] }
使用下标方式进行读取:
for (int i = 0; i < root["list"].size(); ++i)
std::cout << root["list"][i].asInt();
使用 Json::ValueIterator 或者 Json::ValueConstIterator 进行读取：
Json::ValueIterator it = root["list"].begin();
for (; it != root["list"].end(); ++it)
std::cout << it->asInt();
使用 C++11 特性（最简单）：
for (auto it : root["list"])
std::cout << it.asInt();
如果数组是 ObjectValue 类型，比如说类似这种：
{
"list": [
{
"name": "John",
"sex": "man"
},
{
"name": "Marry",
"sex": "women"
}
]
}
则数组的读取代码类似于：
for (auto it : root["list"]) {
std::cout << it["name"].asString() << std::endl;
std::cout << it["sex"].asString() << std::endl;
}
写 json 数据
JsonCpp 提供 Writer 类用于写 json 数据。还是从最简单的例子开始，然后逐步展开。比如利用 JsonCpp 创建如下 json 文件：
{"content": "Hello JsonCpp"}
使用 Value 创建 json 字符串然后转换成 std::string 类型并输出：
#include 在 ubuntu 系统上编译：
g++ -I/usr/include/jsoncpp -o hello hello.cpp -ljsoncpp
运行结果：
$ ./hello
{
"content" : "Hello JsonCpp"
}
源码第 6 行定义出 Value 对象，作为 json 的根节点（root node）：
Json::Value root;
源码第 7 行定义 Key/Value 键值对，以此类推，在节点下的基本类型均可使用 [] 操作符进行添加，如：
root["string_key"] = "string value";
root["int_key"] = 256;
root["double_key"] = 128.6;
root["boolean_key"] = true;
源码第 8 行利用 Value 提供的转换接口可将 json 进行格式化，函数原型为：
class Value {
...
String toStyledString() const;
...
};
添加 ObjectValue 类型
如果需要添加嵌套的 json 子节点，可以定义一个 Value 对象来装载内部的 Key/Value 键值对，然后将该对象赋值给 json 的父节点：
Json::Value sub;
sub["province"] = "Guangdong";
sub["city"] = "Huizhou";
root["hometown"] = sub;
sub.clear();
如果嵌套的节点内容较简单，不想重新定义一个新的 Value 变量也可以采用另一种写法：
root["hometown"]["province"] = "Guangdong";
root["hometown"]["city"] = "Huizhou";
以上两种写法最终产生的 json 内容都是一样的，如下所示：
{
"hometown": {
"province": "Guangdong",
"city": "Huizhou"
}
}
添加数组类型
Value.append() 接口用于添加 json 数组类型，凡事宜从最简单的地方入手，一步一步深入:
for (int i = 0; i < 3; ++i)
root["list"].append(i);
生成的 json 内容如下：
{
"list": [0, 1, 2]
}
如果数组内的数据是 ObjectValue 类型，可以定义一个 Value 对象来装载内部的 Key/Value 键值对，然后将该对象添加到数组中：
Json::Value item;
for (int i = 0; i < 2; ++i) {
item["index"] = i;
item["content"] = "Hello Array";
root["data"].append(item);
}
生成的 json 内容如下：
{
"data" : [
{
"content" : "Hello Array",
"index" : 0
},
{
"content" : "Hello Array",
"index" : 1
}
]
}
格式化与非格式化
根据使用场合不同，需要将 json 内容转换为格式化或非格式化字符串，比如为了可视化的输出一般选择格式化 json 字符串，而在网络传输过程中，会尽量选择使用非格式化的字符串来达到减少传输数据量的目的。
Json::Value root;
...// root 中写入数据
// 格式化: 转为格式化字符串，里面加了很多空格及换行符
std::string strJson = root.toStyledString();
// 非格式化: 转为未格式化字符串，无多余空格及换行符
Json::FastWriter writer;
std::string strJson = writer.write(root);
写入文件
在这一小节的介绍中，更多的是说明标准 C++ 的文件流操作，因为上文已经通过格式化与非格式化将 json 字符串导出成一个标准 C++ 的字符串 std::string，接下来直接将 std::string 写入到文件中即可。示例代码：
// root node
Json::Value root;
...
try {
std::ofstream ofs;
ofs.open(filename);
if (ofs.fail()) {
fprintf(stderr, "open '%s' failed: %s", filename, strerror(errno));
return false;
}
ofs << root.toStyledString();
ofs.close();
} catch (std::exception &e) {
fprintf(stderr, "%s", e.what());
return false;
}
源码第 6 行定义输出文件流对象 ofs：
std::ofstream ofs;
源码第 7~11 行尝试打开文件，如果文件无法打开，使用 strerror(errno) 查看具体失败原因。
ofs.open(filename);
if (ofs.fail()) {
...
}
源码 12 行将 json 内容通过流方式写入文件中。
ofs << root.toStyledString();
在文件写入完成之后使用 ofs.close() 接口关闭文件流。因为写入的过程在实际的系统运行会出现较复杂的情况：磁盘満了又或者磁盘损坏导致无法写入等，所以如果在写入的过程中出现异常，我们就需要使用 try...catch... 来捕获异常。
从文件读取
Reader 支持从 std::istream 流读取数据，可以直接将文件流作为输入参数给到 Reader.parse()，函数原型为：
class Reader {
...
bool parse(const std::string& document, Value& root, bool collectComments = true);
bool parse(IStream& is, Value& root, bool collectComments = true);
...
};
比如现在有一个文件 hello.json：
{
"content": "Hello JsonCpp"
}
代码实现：
#include 源码中第 10 行使用 std::ifstream 读取 json 文件，如果文件无法打开，使用 strerror(errno) 查看具体失败原因。
std::ifstream ifs(path);
if (!ifs) {
...
}
源码第 18 行将 ifs 作为参数传入 parse() 接口：
if (reader.parse(ifs, root)) {
...
}
设计经验
从面向对象的设计思想出发，建议将每份 json 的读写设计成一个独立的类，这里面所指的“每份 json”可以是 json 字符串或者是 json 文件，以这样的方式来进行设计之后，业务层只需要关心期望取得的键值即可。