jsoncons is a C++ library for the construction of JavaScript Object Notation (JSON). It supports parsing a JSON file or string into a tree structured json
value, building a json
value in C++ code, and serializing a json
value to a file or string. It also provides an event-based API for reading and writing JSON documents that are too large to fit into available memory, somewhat analogously to SAX processing in the XML world. The latest documentation and tutorials may be found on the wiki.
jsoncons uses some features that are new to C++ 11, particularly move semantics, however, it has been written to be compatible with VC++ 10 SP1 (note that SP1 is required for VC++ 10, it fixes compiler bugs with move semantics.) It has been tested with MS Visual C++ 10 SP1, Intel C++ Studio XE 2013, clang 3.3 and GCC 4.8.
The code repository and releases are on github. It is distributed under the Boost Software License
The library has a number of features, which are listed below:
- Uses the standard C++ input/output streams library
- Implements parsing and serializing JSON text in UTF-8 for narrow character strings and streams
- Supports UTF16 (UTF32) encodings with size 2 (size 4) wide characters
- Correctly handles surrogate pairs in \uXXXX escape sequences
- Supports event based JSON parsing and serializing with user defined input and output handlers
- Guarantees basic exception safety (no leaks)
- Accepts and ignores single line comments that start with //, and multi line comments that start with /* and end with */
- Supports optional escaping of the solidus (/) character
- Supports Nan, Inf and -Inf replacement
- Supports reading multiple json objects from a stream
- Supports optional escaping of non-ascii UTF-8 octets
- Allows extensions to the types accepted by the json class accessors and modifiers
- Supports storing "any" values in a json object or array, with specialized serialization
- Supports reading (writing) JSON values from (to) CSV files
-
A template method
any_cast
has been added to thejson
class. -
The allocator type parameter in
basic_json
is now supported, it allows you to supply a custom allocator for dynamically allocated, fixed size small objects in the json container. The allocator type is not used for structures including vectors and strings that use large or variable amounts of memory, these always use the default allocators. -
json_input_handler
andjson_output_handler
have been changed to make the interfaces public non-virtual and the implementations private virtual. If you have implemented your own input and output handlers, or have passed json events to serializers or deserializers directly, you will need to make changes to your code, refer to the Changelog, and to the revised documentation and tutorials for details. -
A bug has been fixed in
csv_reader
The jsoncons library is header-only: it consists solely of header files containing templates and inline functions, and requires no separately-compiled library binaries when linking. It has no dependence on other libraries.
To install the jsoncons library, download the zip file, unpack the release, under src
find the directory jsoncons
, and copy it to your include
directory. If you wish to use extensions, copy the jsoncons_ext
directory as well.
The jsoncons classes and functions are in namespace jsoncons
. The following using declarations are for the examples that appear below.
#include "jsoncons/json.hpp"
using std::string;
using std::cout;
using std::endl;
using jsoncons::json;
using jsoncons::pretty_print;
Here is a sample file (books.json):
[
{
"title" : "Kafka on the Shore",
"author" : "Haruki Murakami",
"price" : 25.17
},
{
"title" : "Women: A Novel",
"author" : "Charles Bukowski",
"price" : 12.00
},
{
"title" : "Cutter's Way",
"author" : "Ivan Passer"
}
]
You can read the file into a json value like this
json books = json::parse_file("books.json");
You can then loop through the books
for (size_t i = 0; i < books.size(); ++i)
{
try
{
json& book = books[i];
string author = book["author"].as<string>();
string title = book["title"].as<string>();
double price = book["price"].as<double>();
cout << author << ", " << title << ", " << price << endl;
}
catch (const json_exception& e)
{
cerr << e.what() << endl;
}
}
The output is
Haruki Murakami, Kafka on the Shore, 25.17
Charles Bukowski, Women: A Novel, 12
Member price not found.
Note that the third book is missing a price, which causes an exception to be thrown.
You have a choice of accessors:
book["price"] will throw if there is no price
book.get("price") will return json::null if there is no price
book.get("price",default_value) will return default_value if there is no price
So if you want to show "n/a" for the missing price, you can use this accessor
string price = book.get("price","n/a").as<string>();
and the output becomes
Haruki Murakami, Kafka on the Shore, 25.17
Charles Bukowski, Women: A Novel, 12.0
Ivan Passer, Cutter's Way, n/a
Or you can check if book has a member "price" with the method has_member
, and output accordingly,
if (book.has_member("price"))
{
double price = book["price"].as<double>();
cout << price;
}
else
{
cout << "n/a";
}
To construct an empty json object, use the default constructor:
json image_sizing;
Serializing it to standard out
cout << image_sizing << endl;
produces
{}
Adding some members,
image_sizing["resize_to_fit"] = true; // a boolean
image_sizing["resize_unit"] = "pixels"; // a string
image_sizing["resize_what"] = "long_edge"; // a string
image_sizing["dimension1"] = 9.84; // a double
image_sizing["dimension2"] = json::null; // a null
Serializing it, this time with pretty print,
cout << pretty_print(image_sizing) << endl;
produces
{
"dimension1":9.84,
"dimension2":null,
"resize_to_fit":true,
"resize_unit":"pixels",
"resize_what":"long_edge"
}
To construct a json array, use the copy constructor with a prototype json array:
json image_formats(json::an_array);
Adding some elements,
image_formats.add("JPEG");
image_formats.add("PSD");
image_formats.add("TIFF");
image_formats.add("DNG");
Combining the two
json file_export;
file_export["image_formats"] = std::move(image_formats);
file_export["image_sizing"] = std::move(image_sizing);
and serializing
cout << pretty_print(file_export) << endl;
produces
{
"image_formats":
["JPEG","PSD","TIFF","DNG"],
"image_sizing":
{
"dimension1":9.84,
"dimension2":null,
"resize_to_fit":true,
"resize_unit":"pixels",
"resize_what":"long_edge"
}
}
jsoncons::json
supports iterators for accessing the members of json objects and the elements of json arrays.
An example of iterating over the name-value pairs of a json object:
json person;
person["first_name"] = "Jane";
person["last_name"] = "Roe";
person["events_attended"] = 10;
person["accept_waiver_of_liability"] = true;
for (auto it = person.begin_members(); it != person.end_members(); ++it)
{
cout << "name=" << it->name() << ", value=" << it->value().as<string>() << endl;
}
An example of iterating over the elements of a json array:
json cities(json::an_array);
cities.add("Montreal");
cities.add("Toronto");
cities.add("Ottawa");
cities.add("Vancouver");
for (auto it = cities.begin_elements(); it != cities.end_elements(); ++it)
{
cout << it->as<string>() << endl;
}
The json class is an instantiation of the basic_json
class template that uses char
as the character type
and std::allocator<void>
as the allocator type,
typedef basic_json<char,std::allocator<void>> json
The library includes an instantiation for wide characters as well,
typedef basic_json<wchar_t,std::allocator<void>> wjson
Note that the allocator type allows you to supply a custom allocator for dynamically allocated, fixed size small objects in the json container, the container rebinds it as necessay. For example, if you wish, you can use the boost pool allocator:
#include <boost/pool/pool_alloc.hpp>
#include "jsoncons/json.hpp"
basic_json<char, boost::pool_allocator<void>> o;
o.set("FirstName","Joe");
o.set("LastName","Smith");
This results in a json object class and a string wrapper being allocated from the boost memory pool. The allocator type is not used for structures including vectors and strings that use large or variable amounts of memory, these always use the default allocators.
In the json class, accessors and modifiers are templated, for example,
template<typename T>
bool is() const
template<typename T>
T as() const
template <typename T>
basic_json& operator=(T val)
The implementations of these functions and operators make use of the class template value_adapter
template <typename Char, typename Alloc, typename T>
class value_adapter
{
public:
bool is(const basic_json& val) const {return false;}
T as(const basic_json& val) const;
void assign(basic_json& self, const T val);
};
This class template is extensible, you as a user can extend value_adapter
in the jsoncons
namespace with your own types. You can, for example, extend value_adapter
to access and modify json
structures with boost::gregorian::date values
, and in your code, write
json deal;
deal["maturity"] = boost::gregorian::date(2015,1,1);
json observation_dates(json::an_array);
observation_dates.add(boost::gregorian::date(2013,10,21));
observation_dates.add(boost::gregorian::date(2013,10,28));
deal["observation_dates"] = std::move(observation_dates);
boost::gregorian::date maturity = deal["maturity"].as<boost::gregorian::date>();
cout << deal << endl;
producing
{
"maturity":"2015-01-01",
"observation_dates":
["2013-10-21","2013-10-28"]
}
jsoncons provides a class json::any
that can contain a value of
any type as long as that type supports copy construction and
assignment. This allows you to, for example, insert a boost matrix into a json
object,
and to retrieve it back cast to the appropriate type. You can do so by wrapping it in
a json::any value
, like this:
#include "jsoncons/json.hpp"
#include <boost/numeric/ublas/matrix.hpp>
using jsoncons::json;
using boost::numeric::ublas::matrix;
json obj;
matrix<double> A(2,2);
A(0,0) = 1;
A(0,1) = 2;
A(1,0) = 3;
A(1,1) = 4;
obj.set("mydata",json::any(A));
matrix<double>& B = obj["mydata"].any_cast<matrix<double>>();