forked from danielaparker/jsoncons
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
246 lines (235 loc) · 9.76 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
<!doctype html>
<html>
<head>
<link rel="stylesheet" href="css/jsoncons.css" type="text/css"/>
<title>jsoncons</title>
</head>
<body>
<h1>jsoncons: a C++ library for json construction</h1>
<p>
<code>jsoncons</code> is a C++ library for the construction of <a href="http://json.org/">JavaScript Object Notation (JSON)</a>. It supports parsing a JSON file or string into a tree structured <code>json</code> value, building a <code>json</code> value in C++ code, and serializing a <code>json</code> 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.
</p>
<code>jsoncons</code> 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 and clang 3.3 and GCC 4.8.
<p>
The code repository is on <a class="" href="https://github.com/danielaparker/jsoncons" rel="nofollow">github</a>, releases and documentation are on <a class="" href="https://sourceforge.net/projects/jsoncons/?source=navbar">sourceforge</a>.
It is distributed under the <a href="http://www.boost.org/users/license.html">Boost Software License</a>.</p>
The library has a number of features, which are listed below:
</p>
<ul>
<li>Uses the standard C++ input/output streams library</li>
<li>Implements parsing and serializing JSON text in UTF-8 for narrow character strings and streams</li>
<li>Supports UTF16 (UTF32) encodings with size 2 (size 4) wide characters
<li>Correctly handles surrogate pairs in \uXXXX escape sequences
<li>Supports event based JSON parsing and serializing with user defined input and output handlers</li>
<li>Guarantees basic exception safety (no leaks)</li>
<li>Accepts and ignores single line comments that start with <code>//</code>, and multi line comments that start with <code>/*</code> and end with <code>*/</code></li>
<li>Supports optional escaping of the solidus (<code>/</code>) character</li>
<li>Supports <code>Nan</code>, <code>Inf</code> and <code>-Inf</code> replacement</li>
<li>Supports reading multiple json objects from a stream</li>
<li>Supports optional escaping of non-ascii UTF-8 octets</li>
<li>Allows extensions to the types accepted by the <code>json</code> class accessors and modifiers</li>
<li>Supports storing custom data types in a json object, with specialized serialization</li>
<li>Supports reading (writing) JSON values from (to) CSV files</li>
</ul>
<h2>Using the code</h2>
<p>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.</p>
<p>To install the jsoncons library, <a href="http://sourceforge.net/projects/jsoncons/files/?source=navbar">download the zip file</a>, unpack the release, find the <code>jsoncons</code> directory under <code>src</code>, and copy it to your <code>include</code> directory.</p>
<p>The <code>jsoncons</code> classes and functions are in namespace <code>jsoncons</code>. The following using declarations are for the examples that appear below.</p>
<div><code><pre>
#include "jsoncons/json.hpp"
using std::string;
using std::cout;
using std::endl;
using jsoncons::null_type;
using jsoncons::json;
</pre></code></div>
<h3>Reading json values from a file</h3>
<p>Here is a sample file (<code>books.json</code>):</p>
<div><code><pre>
[
{
"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"
}
]
</pre></code></div>
You can read the file into a <code>json</code> value like this
<div><code><pre>
json books = json::parse_file("books.json");
</pre></code></div>
You can then loop through the books
<div><code><pre>
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;
}
}
</pre></code></div>
<p>The output is</p>
<div><code><pre>
Haruki Murakami, Kafka on the Shore, 25.17
Charles Bukowski, Women: A Novel, 12
Member price not found.
</pre></code></div>
<p>Note that the third book is missing a price, which causes an exception to be thrown.</p>
<p>You have a choice of accessors:</p>
<ul>
<li><code>book["price"]</code> will throw if there is no price</li>
<li><code>book.get("price")</code> will return <code>json::null</code> if there is no price</li>
<li><code>book.get("price",default_value)</code> will return <code>default_value</code> if there is no price</li>
</ul>
<p>So if you want to show "n/a" for the missing price, you can use this accessor</p>
<div><code><pre>
string price = book.get("price","n/a").as<string>();
</pre></code></div>
<p>and the output becomes</>
<div><code><pre>
Haruki Murakami, Kafka on the Shore, 25.17
Charles Bukowski, Women: A Novel, 12.0
Ivan Passer, Cutter's Way, n/a
</pre></code></div>
<p>Or you can check if <code>book</code> has a member "price" with the method <code>has_member</code>, and output accordingly,</p>
<div><code><pre>
if (book.has_member("price"))
{
double price = book["price"].as<double>();
cout << price;
}
else
{
cout << "n/a";
}
</pre></code></div>
<h2>Building json values in C++</h2>
<p>To construct an empty <code>json</code> object, use the default constructor:</p>
<div><code><pre>
json image_sizing;
</pre></code></div>
<p>Serializing it to standard out</p>
<div><code><pre>
cout << image_sizing << endl;
</pre></code></div>
<p>produces</p>
<div><code><pre>
{}
</pre></code></div>
<p>Adding some members,</p>
<div><code><pre>
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"] = null_type(); // a null
</pre></code></div>
<p>Serializing it, this time with pretty print,</p>
<div><code><pre>
cout << pretty_print(image_sizing) << endl;
</pre></code></div>
<p>produces</p>
<div><code><pre>
{
"dimension1":9.84,
"dimension2":null,
"resize_to_fit":true,
"resize_unit":"pixels",
"resize_what":"long_edge"
}
</pre></code></div>
<p>To construct a <code>json</code> array, use the copy constructor with a prototype <code>json</code> array:</p>
<div><code><pre>
json image_formats(json::an_array);
</pre></code></div>
<p>Adding some elements,</p>
<div><code><pre>
image_formats.add("JPEG");
image_formats.add("PSD");
image_formats.add("TIFF");
image_formats.add("DNG");
</pre></code></div>
<p>Combining the two</p>
<div><code><pre>
json file_export;
file_export["image_formats"] = std::move(image_formats);
file_export["image_sizing"] = std::move(image_sizing);
</pre></code></div>
<p>and serializing</p>
<div><code><pre>
cout << pretty_print(file_export) << endl;
</pre></code></div>
<p>produces</p>
<div><code><pre>
{
"image_formats":
["JPEG","PSD","TIFF","DNG"],
"image_sizing":
{
"dimension1":9.84,
"dimension2":null,
"resize_to_fit":true,
"resize_unit":"pixels",
"resize_what":"long_edge"
}
}
</pre></code></div>
<h2>Extensibility</h2>
<p>In the <code>json</code> class, accessors and modifiers are templated, for example,</p>
<div><code><pre>
template<typename T>
bool is() const
template<typename T>
T as() const
template <typename T>
basic_json& operator=(T val)
</pre></code></div>
<p>The implementations of these functions and operators make use of the class template <code>value_adapter</code></p>
<div><code><pre>
template <typename Char, typename Storage, typename T>
class value_adapter
{
public:
bool is(const basic_json<Char,Storage>& val) const {return false;}
T as(const basic_json<Char,Storage>& val) const;
void assign(basic_json<Char,Storage>& self, const T val);
};
</pre></code></div>
<p>This class template is extensible, you as a user can extend <code>value_adapter</code> in the <code>jsoncons</code> namespace with your own types. You can, for example, extend <code>value_adapter</code> to access and modify <code>json</code> structures with <code>boost::gregorian::date</code> values, and in your code, write</p>
<div><code><pre>
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;
</pre></code></div>
<p>producing</p>
<div><code><pre>
{
"maturity":"2015-01-01",
"observation_dates":
["2013-10-21","2013-10-28"]
}
</pre></code></div>
</body>
</html>