2190
|
1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
2 |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
3 |
|
|
4 |
|
|
5 |
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
6 |
<head>
|
|
7 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
8 |
|
|
9 |
<title>API Reference — Jansson 2.7 documentation</title>
|
|
10 |
|
|
11 |
<link rel="stylesheet" href="_static/default.css" type="text/css" />
|
|
12 |
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
13 |
|
|
14 |
<script type="text/javascript">
|
|
15 |
var DOCUMENTATION_OPTIONS = {
|
|
16 |
URL_ROOT: './',
|
|
17 |
VERSION: '2.7',
|
|
18 |
COLLAPSE_INDEX: false,
|
|
19 |
FILE_SUFFIX: '.html',
|
|
20 |
HAS_SOURCE: true
|
|
21 |
};
|
|
22 |
</script>
|
|
23 |
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
24 |
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
25 |
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
26 |
<link rel="top" title="Jansson 2.7 documentation" href="index.html" />
|
|
27 |
<link rel="next" title="Changes in Jansson" href="changes.html" />
|
|
28 |
<link rel="prev" title="Portability" href="portability.html" />
|
|
29 |
</head>
|
|
30 |
<body>
|
|
31 |
<div class="related">
|
|
32 |
<h3>Navigation</h3>
|
|
33 |
<ul>
|
|
34 |
<li class="right" style="margin-right: 10px">
|
|
35 |
<a href="genindex.html" title="General Index"
|
|
36 |
accesskey="I">index</a></li>
|
|
37 |
<li class="right" >
|
|
38 |
<a href="changes.html" title="Changes in Jansson"
|
|
39 |
accesskey="N">next</a> |</li>
|
|
40 |
<li class="right" >
|
|
41 |
<a href="portability.html" title="Portability"
|
|
42 |
accesskey="P">previous</a> |</li>
|
|
43 |
<li><a href="index.html">Jansson 2.7 documentation</a> »</li>
|
|
44 |
</ul>
|
|
45 |
</div>
|
|
46 |
|
|
47 |
<div class="document">
|
|
48 |
<div class="documentwrapper">
|
|
49 |
<div class="bodywrapper">
|
|
50 |
<div class="body">
|
|
51 |
|
|
52 |
<div class="section" id="api-reference">
|
|
53 |
<span id="apiref"></span><h1>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h1>
|
|
54 |
<div class="section" id="preliminaries">
|
|
55 |
<h2>Preliminaries<a class="headerlink" href="#preliminaries" title="Permalink to this headline">¶</a></h2>
|
|
56 |
<p>All declarations are in <tt class="file docutils literal"><span class="pre">jansson.h</span></tt>, so it’s enough to</p>
|
|
57 |
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <jansson.h></span>
|
|
58 |
</pre></div>
|
|
59 |
</div>
|
|
60 |
<p>in each source file.</p>
|
|
61 |
<p>All constants are prefixed with <tt class="docutils literal"><span class="pre">JSON_</span></tt> (except for those describing
|
|
62 |
the library version, prefixed with <tt class="docutils literal"><span class="pre">JANSSON_</span></tt>). Other identifiers
|
|
63 |
are prefixed with <tt class="docutils literal"><span class="pre">json_</span></tt>. Type names are suffixed with <tt class="docutils literal"><span class="pre">_t</span></tt> and
|
|
64 |
<tt class="docutils literal"><span class="pre">typedef</span></tt>‘d so that the <tt class="docutils literal"><span class="pre">struct</span></tt> keyword need not be used.</p>
|
|
65 |
</div>
|
|
66 |
<div class="section" id="library-version">
|
|
67 |
<h2>Library Version<a class="headerlink" href="#library-version" title="Permalink to this headline">¶</a></h2>
|
|
68 |
<p>The Jansson version is of the form <em>A.B.C</em>, where <em>A</em> is the major
|
|
69 |
version, <em>B</em> is the minor version and <em>C</em> is the micro version. If the
|
|
70 |
micro version is zero, it’s omitted from the version string, i.e. the
|
|
71 |
version string is just <em>A.B</em>.</p>
|
|
72 |
<p>When a new release only fixes bugs and doesn’t add new features or
|
|
73 |
functionality, the micro version is incremented. When new features are
|
|
74 |
added in a backwards compatible way, the minor version is incremented
|
|
75 |
and the micro version is set to zero. When there are backwards
|
|
76 |
incompatible changes, the major version is incremented and others are
|
|
77 |
set to zero.</p>
|
|
78 |
<p>The following preprocessor constants specify the current version of
|
|
79 |
the library:</p>
|
|
80 |
<dl class="docutils">
|
|
81 |
<dt><tt class="docutils literal"><span class="pre">JANSSON_MAJOR_VERSION</span></tt>, <tt class="docutils literal"><span class="pre">JANSSON_MINOR_VERSION</span></tt>, <tt class="docutils literal"><span class="pre">JANSSON_MICRO_VERSION</span></tt></dt>
|
|
82 |
<dd>Integers specifying the major, minor and micro versions,
|
|
83 |
respectively.</dd>
|
|
84 |
<dt><tt class="docutils literal"><span class="pre">JANSSON_VERSION</span></tt></dt>
|
|
85 |
<dd>A string representation of the current version, e.g. <tt class="docutils literal"><span class="pre">"1.2.1"</span></tt> or
|
|
86 |
<tt class="docutils literal"><span class="pre">"1.3"</span></tt>.</dd>
|
|
87 |
<dt><tt class="docutils literal"><span class="pre">JANSSON_VERSION_HEX</span></tt></dt>
|
|
88 |
<dd><p class="first">A 3-byte hexadecimal representation of the version, e.g.
|
|
89 |
<tt class="docutils literal"><span class="pre">0x010201</span></tt> for version 1.2.1 and <tt class="docutils literal"><span class="pre">0x010300</span></tt> for version 1.3.
|
|
90 |
This is useful in numeric comparisions, e.g.:</p>
|
|
91 |
<div class="last highlight-c"><div class="highlight"><pre><span class="cp">#if JANSSON_VERSION_HEX >= 0x010300</span>
|
|
92 |
<span class="cm">/* Code specific to version 1.3 and above */</span>
|
|
93 |
<span class="cp">#endif</span>
|
|
94 |
</pre></div>
|
|
95 |
</div>
|
|
96 |
</dd>
|
|
97 |
</dl>
|
|
98 |
</div>
|
|
99 |
<div class="section" id="value-representation">
|
|
100 |
<h2>Value Representation<a class="headerlink" href="#value-representation" title="Permalink to this headline">¶</a></h2>
|
|
101 |
<p>The JSON specification (<span class="target" id="index-0"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc4627.html"><strong>RFC 4627</strong></a>) defines the following data types:
|
|
102 |
<em>object</em>, <em>array</em>, <em>string</em>, <em>number</em>, <em>boolean</em>, and <em>null</em>. JSON
|
|
103 |
types are used dynamically; arrays and objects can hold any other data
|
|
104 |
type, including themselves. For this reason, Jansson’s type system is
|
|
105 |
also dynamic in nature. There’s one C type to represent all JSON
|
|
106 |
values, and this structure knows the type of the JSON value it holds.</p>
|
|
107 |
<dl class="type">
|
|
108 |
<dt id="c.json_t">
|
|
109 |
<tt class="descname">json_t</tt><a class="headerlink" href="#c.json_t" title="Permalink to this definition">¶</a></dt>
|
|
110 |
<dd><p>This data structure is used throughout the library to represent all
|
|
111 |
JSON values. It always contains the type of the JSON value it holds
|
|
112 |
and the value’s reference count. The rest depends on the type of the
|
|
113 |
value.</p>
|
|
114 |
</dd></dl>
|
|
115 |
|
|
116 |
<p>Objects of <a class="reference internal" href="#c.json_t" title="json_t"><tt class="xref c c-type docutils literal"><span class="pre">json_t</span></tt></a> are always used through a pointer. There
|
|
117 |
are APIs for querying the type, manipulating the reference count, and
|
|
118 |
for constructing and manipulating values of different types.</p>
|
|
119 |
<p>Unless noted otherwise, all API functions return an error value if an
|
|
120 |
error occurs. Depending on the function’s signature, the error value
|
|
121 |
is either <em>NULL</em> or -1. Invalid arguments or invalid input are
|
|
122 |
apparent sources for errors. Memory allocation and I/O operations may
|
|
123 |
also cause errors.</p>
|
|
124 |
<div class="section" id="type">
|
|
125 |
<h3>Type<a class="headerlink" href="#type" title="Permalink to this headline">¶</a></h3>
|
|
126 |
<p>The type of a JSON value is queried and tested using the following
|
|
127 |
functions:</p>
|
|
128 |
<dl class="type">
|
|
129 |
<dt id="c.json_type">
|
|
130 |
enum <tt class="descname">json_type</tt><a class="headerlink" href="#c.json_type" title="Permalink to this definition">¶</a></dt>
|
|
131 |
<dd><p>The type of a JSON value. The following members are defined:</p>
|
|
132 |
<table border="1" class="docutils">
|
|
133 |
<colgroup>
|
|
134 |
<col width="100%" />
|
|
135 |
</colgroup>
|
|
136 |
<tbody valign="top">
|
|
137 |
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_OBJECT</span></tt></td>
|
|
138 |
</tr>
|
|
139 |
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_ARRAY</span></tt></td>
|
|
140 |
</tr>
|
|
141 |
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_STRING</span></tt></td>
|
|
142 |
</tr>
|
|
143 |
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_INTEGER</span></tt></td>
|
|
144 |
</tr>
|
|
145 |
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_REAL</span></tt></td>
|
|
146 |
</tr>
|
|
147 |
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_TRUE</span></tt></td>
|
|
148 |
</tr>
|
|
149 |
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_FALSE</span></tt></td>
|
|
150 |
</tr>
|
|
151 |
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_NULL</span></tt></td>
|
|
152 |
</tr>
|
|
153 |
</tbody>
|
|
154 |
</table>
|
|
155 |
<p>These correspond to JSON object, array, string, number, boolean and
|
|
156 |
null. A number is represented by either a value of the type
|
|
157 |
<tt class="docutils literal"><span class="pre">JSON_INTEGER</span></tt> or of the type <tt class="docutils literal"><span class="pre">JSON_REAL</span></tt>. A true boolean value
|
|
158 |
is represented by a value of the type <tt class="docutils literal"><span class="pre">JSON_TRUE</span></tt> and false by a
|
|
159 |
value of the type <tt class="docutils literal"><span class="pre">JSON_FALSE</span></tt>.</p>
|
|
160 |
</dd></dl>
|
|
161 |
|
|
162 |
<dl class="function">
|
|
163 |
<dt id="c.json_typeof">
|
|
164 |
int <tt class="descname">json_typeof</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_typeof" title="Permalink to this definition">¶</a></dt>
|
|
165 |
<dd><p>Return the type of the JSON value (a <a class="reference internal" href="#c.json_type" title="json_type"><tt class="xref c c-type docutils literal"><span class="pre">json_type</span></tt></a> cast to
|
|
166 |
<tt class="xref c c-type docutils literal"><span class="pre">int</span></tt>). <em>json</em> MUST NOT be <em>NULL</em>. This function is actually
|
|
167 |
implemented as a macro for speed.</p>
|
|
168 |
</dd></dl>
|
|
169 |
|
|
170 |
<dl class="function">
|
|
171 |
<dt id="c.json_is_object">
|
|
172 |
<tt class="descname">json_is_object</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_object" title="Permalink to this definition">¶</a></dt>
|
|
173 |
<dt id="c.json_is_array">
|
|
174 |
<tt class="descname">json_is_array</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_array" title="Permalink to this definition">¶</a></dt>
|
|
175 |
<dt id="c.json_is_string">
|
|
176 |
<tt class="descname">json_is_string</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_string" title="Permalink to this definition">¶</a></dt>
|
|
177 |
<dt id="c.json_is_integer">
|
|
178 |
<tt class="descname">json_is_integer</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_integer" title="Permalink to this definition">¶</a></dt>
|
|
179 |
<dt id="c.json_is_real">
|
|
180 |
<tt class="descname">json_is_real</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_real" title="Permalink to this definition">¶</a></dt>
|
|
181 |
<dt id="c.json_is_true">
|
|
182 |
<tt class="descname">json_is_true</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_true" title="Permalink to this definition">¶</a></dt>
|
|
183 |
<dt id="c.json_is_false">
|
|
184 |
<tt class="descname">json_is_false</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_false" title="Permalink to this definition">¶</a></dt>
|
|
185 |
<dt id="c.json_is_null">
|
|
186 |
<tt class="descname">json_is_null</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_null" title="Permalink to this definition">¶</a></dt>
|
|
187 |
<dd><p>These functions (actually macros) return true (non-zero) for values
|
|
188 |
of the given type, and false (zero) for values of other types and
|
|
189 |
for <em>NULL</em>.</p>
|
|
190 |
</dd></dl>
|
|
191 |
|
|
192 |
<dl class="function">
|
|
193 |
<dt id="c.json_is_number">
|
|
194 |
<tt class="descname">json_is_number</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_number" title="Permalink to this definition">¶</a></dt>
|
|
195 |
<dd><p>Returns true for values of types <tt class="docutils literal"><span class="pre">JSON_INTEGER</span></tt> and
|
|
196 |
<tt class="docutils literal"><span class="pre">JSON_REAL</span></tt>, and false for other types and for <em>NULL</em>.</p>
|
|
197 |
</dd></dl>
|
|
198 |
|
|
199 |
<dl class="function">
|
|
200 |
<dt id="c.json_is_boolean">
|
|
201 |
<tt class="descname">json_is_boolean</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_is_boolean" title="Permalink to this definition">¶</a></dt>
|
|
202 |
<dd><p>Returns true for types <tt class="docutils literal"><span class="pre">JSON_TRUE</span></tt> and <tt class="docutils literal"><span class="pre">JSON_FALSE</span></tt>, and false
|
|
203 |
for values of other types and for <em>NULL</em>.</p>
|
|
204 |
</dd></dl>
|
|
205 |
|
|
206 |
<dl class="function">
|
|
207 |
<dt id="c.json_boolean_value">
|
|
208 |
<tt class="descname">json_boolean_value</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_boolean_value" title="Permalink to this definition">¶</a></dt>
|
|
209 |
<dd><p>Alias of <a class="reference internal" href="#c.json_is_true" title="json_is_true"><tt class="xref c c-func docutils literal"><span class="pre">json_is_true()</span></tt></a>, i.e. returns 1 for <tt class="docutils literal"><span class="pre">JSON_TRUE</span></tt>
|
|
210 |
and 0 otherwise.</p>
|
|
211 |
<div class="versionadded">
|
|
212 |
<p><span class="versionmodified">New in version 2.7.</span></p>
|
|
213 |
</div>
|
|
214 |
</dd></dl>
|
|
215 |
|
|
216 |
</div>
|
|
217 |
<div class="section" id="reference-count">
|
|
218 |
<span id="apiref-reference-count"></span><h3>Reference Count<a class="headerlink" href="#reference-count" title="Permalink to this headline">¶</a></h3>
|
|
219 |
<p>The reference count is used to track whether a value is still in use
|
|
220 |
or not. When a value is created, it’s reference count is set to 1. If
|
|
221 |
a reference to a value is kept (e.g. a value is stored somewhere for
|
|
222 |
later use), its reference count is incremented, and when the value is
|
|
223 |
no longer needed, the reference count is decremented. When the
|
|
224 |
reference count drops to zero, there are no references left, and the
|
|
225 |
value can be destroyed.</p>
|
|
226 |
<p>The following functions are used to manipulate the reference count.</p>
|
|
227 |
<dl class="function">
|
|
228 |
<dt id="c.json_incref">
|
|
229 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_incref</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_incref" title="Permalink to this definition">¶</a></dt>
|
|
230 |
<dd><p>Increment the reference count of <em>json</em> if it’s not <em>NULL</em>.
|
|
231 |
Returns <em>json</em>.</p>
|
|
232 |
</dd></dl>
|
|
233 |
|
|
234 |
<dl class="function">
|
|
235 |
<dt id="c.json_decref">
|
|
236 |
void <tt class="descname">json_decref</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_decref" title="Permalink to this definition">¶</a></dt>
|
|
237 |
<dd><p>Decrement the reference count of <em>json</em>. As soon as a call to
|
|
238 |
<a class="reference internal" href="#c.json_decref" title="json_decref"><tt class="xref c c-func docutils literal"><span class="pre">json_decref()</span></tt></a> drops the reference count to zero, the value
|
|
239 |
is destroyed and it can no longer be used.</p>
|
|
240 |
</dd></dl>
|
|
241 |
|
|
242 |
<p>Functions creating new JSON values set the reference count to 1. These
|
|
243 |
functions are said to return a <strong>new reference</strong>. Other functions
|
|
244 |
returning (existing) JSON values do not normally increase the
|
|
245 |
reference count. These functions are said to return a <strong>borrowed
|
|
246 |
reference</strong>. So, if the user will hold a reference to a value returned
|
|
247 |
as a borrowed reference, he must call <a class="reference internal" href="#c.json_incref" title="json_incref"><tt class="xref c c-func docutils literal"><span class="pre">json_incref()</span></tt></a>. As soon as
|
|
248 |
the value is no longer needed, <a class="reference internal" href="#c.json_decref" title="json_decref"><tt class="xref c c-func docutils literal"><span class="pre">json_decref()</span></tt></a> should be called
|
|
249 |
to release the reference.</p>
|
|
250 |
<p>Normally, all functions accepting a JSON value as an argument will
|
|
251 |
manage the reference, i.e. increase and decrease the reference count
|
|
252 |
as needed. However, some functions <strong>steal</strong> the reference, i.e. they
|
|
253 |
have the same result as if the user called <a class="reference internal" href="#c.json_decref" title="json_decref"><tt class="xref c c-func docutils literal"><span class="pre">json_decref()</span></tt></a> on
|
|
254 |
the argument right after calling the function. These functions are
|
|
255 |
suffixed with <tt class="docutils literal"><span class="pre">_new</span></tt> or have <tt class="docutils literal"><span class="pre">_new_</span></tt> somewhere in their name.</p>
|
|
256 |
<p>For example, the following code creates a new JSON array and appends
|
|
257 |
an integer to it:</p>
|
|
258 |
<div class="highlight-c"><div class="highlight"><pre><span class="kt">json_t</span> <span class="o">*</span><span class="n">array</span><span class="p">,</span> <span class="o">*</span><span class="n">integer</span><span class="p">;</span>
|
|
259 |
|
|
260 |
<span class="n">array</span> <span class="o">=</span> <span class="n">json_array</span><span class="p">();</span>
|
|
261 |
<span class="n">integer</span> <span class="o">=</span> <span class="n">json_integer</span><span class="p">(</span><span class="mi">42</span><span class="p">);</span>
|
|
262 |
|
|
263 |
<span class="n">json_array_append</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="n">integer</span><span class="p">);</span>
|
|
264 |
<span class="n">json_decref</span><span class="p">(</span><span class="n">integer</span><span class="p">);</span>
|
|
265 |
</pre></div>
|
|
266 |
</div>
|
|
267 |
<p>Note how the caller has to release the reference to the integer value
|
|
268 |
by calling <a class="reference internal" href="#c.json_decref" title="json_decref"><tt class="xref c c-func docutils literal"><span class="pre">json_decref()</span></tt></a>. By using a reference stealing
|
|
269 |
function <a class="reference internal" href="#c.json_array_append_new" title="json_array_append_new"><tt class="xref c c-func docutils literal"><span class="pre">json_array_append_new()</span></tt></a> instead of
|
|
270 |
<a class="reference internal" href="#c.json_array_append" title="json_array_append"><tt class="xref c c-func docutils literal"><span class="pre">json_array_append()</span></tt></a>, the code becomes much simpler:</p>
|
|
271 |
<div class="highlight-c"><div class="highlight"><pre><span class="kt">json_t</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="n">json_array</span><span class="p">();</span>
|
|
272 |
<span class="n">json_array_append_new</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="n">json_integer</span><span class="p">(</span><span class="mi">42</span><span class="p">));</span>
|
|
273 |
</pre></div>
|
|
274 |
</div>
|
|
275 |
<p>In this case, the user doesn’t have to explicitly release the
|
|
276 |
reference to the integer value, as <a class="reference internal" href="#c.json_array_append_new" title="json_array_append_new"><tt class="xref c c-func docutils literal"><span class="pre">json_array_append_new()</span></tt></a>
|
|
277 |
steals the reference when appending the value to the array.</p>
|
|
278 |
<p>In the following sections it is clearly documented whether a function
|
|
279 |
will return a new or borrowed reference or steal a reference to its
|
|
280 |
argument.</p>
|
|
281 |
</div>
|
|
282 |
<div class="section" id="circular-references">
|
|
283 |
<h3>Circular References<a class="headerlink" href="#circular-references" title="Permalink to this headline">¶</a></h3>
|
|
284 |
<p>A circular reference is created when an object or an array is,
|
|
285 |
directly or indirectly, inserted inside itself. The direct case is
|
|
286 |
simple:</p>
|
|
287 |
<div class="highlight-c"><div class="highlight"><pre><span class="kt">json_t</span> <span class="o">*</span><span class="n">obj</span> <span class="o">=</span> <span class="n">json_object</span><span class="p">();</span>
|
|
288 |
<span class="n">json_object_set</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">"foo"</span><span class="p">,</span> <span class="n">obj</span><span class="p">);</span>
|
|
289 |
</pre></div>
|
|
290 |
</div>
|
|
291 |
<p>Jansson will refuse to do this, and <a class="reference internal" href="#c.json_object_set" title="json_object_set"><tt class="xref c c-func docutils literal"><span class="pre">json_object_set()</span></tt></a> (and
|
|
292 |
all the other such functions for objects and arrays) will return with
|
|
293 |
an error status. The indirect case is the dangerous one:</p>
|
|
294 |
<div class="highlight-c"><div class="highlight"><pre><span class="kt">json_t</span> <span class="o">*</span><span class="n">arr1</span> <span class="o">=</span> <span class="n">json_array</span><span class="p">(),</span> <span class="o">*</span><span class="n">arr2</span> <span class="o">=</span> <span class="n">json_array</span><span class="p">();</span>
|
|
295 |
<span class="n">json_array_append</span><span class="p">(</span><span class="n">arr1</span><span class="p">,</span> <span class="n">arr2</span><span class="p">);</span>
|
|
296 |
<span class="n">json_array_append</span><span class="p">(</span><span class="n">arr2</span><span class="p">,</span> <span class="n">arr1</span><span class="p">);</span>
|
|
297 |
</pre></div>
|
|
298 |
</div>
|
|
299 |
<p>In this example, the array <tt class="docutils literal"><span class="pre">arr2</span></tt> is contained in the array
|
|
300 |
<tt class="docutils literal"><span class="pre">arr1</span></tt>, and vice versa. Jansson cannot check for this kind of
|
|
301 |
indirect circular references without a performance hit, so it’s up to
|
|
302 |
the user to avoid them.</p>
|
|
303 |
<p>If a circular reference is created, the memory consumed by the values
|
|
304 |
cannot be freed by <a class="reference internal" href="#c.json_decref" title="json_decref"><tt class="xref c c-func docutils literal"><span class="pre">json_decref()</span></tt></a>. The reference counts never
|
|
305 |
drops to zero because the values are keeping the references to each
|
|
306 |
other. Moreover, trying to encode the values with any of the encoding
|
|
307 |
functions will fail. The encoder detects circular references and
|
|
308 |
returns an error status.</p>
|
|
309 |
</div>
|
|
310 |
</div>
|
|
311 |
<div class="section" id="true-false-and-null">
|
|
312 |
<h2>True, False and Null<a class="headerlink" href="#true-false-and-null" title="Permalink to this headline">¶</a></h2>
|
|
313 |
<p>These three values are implemented as singletons, so the returned
|
|
314 |
pointers won’t change between invocations of these functions.</p>
|
|
315 |
<dl class="function">
|
|
316 |
<dt id="c.json_true">
|
|
317 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_true</tt><big>(</big>void<big>)</big><a class="headerlink" href="#c.json_true" title="Permalink to this definition">¶</a></dt>
|
|
318 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns the JSON true value.</p>
|
|
319 |
</dd></dl>
|
|
320 |
|
|
321 |
<dl class="function">
|
|
322 |
<dt id="c.json_false">
|
|
323 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_false</tt><big>(</big>void<big>)</big><a class="headerlink" href="#c.json_false" title="Permalink to this definition">¶</a></dt>
|
|
324 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns the JSON false value.</p>
|
|
325 |
</dd></dl>
|
|
326 |
|
|
327 |
<dl class="function">
|
|
328 |
<dt id="c.json_boolean">
|
|
329 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_boolean</tt><big>(</big>val<big>)</big><a class="headerlink" href="#c.json_boolean" title="Permalink to this definition">¶</a></dt>
|
|
330 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns JSON false if <tt class="docutils literal"><span class="pre">val</span></tt> is zero, and JSON true otherwise.
|
|
331 |
This is a macro, and equivalent to <tt class="docutils literal"><span class="pre">val</span> <span class="pre">?</span> <span class="pre">json_true()</span> <span class="pre">:</span>
|
|
332 |
<span class="pre">json_false()</span></tt>.</p>
|
|
333 |
<div class="versionadded">
|
|
334 |
<p><span class="versionmodified">New in version 2.4.</span></p>
|
|
335 |
</div>
|
|
336 |
</dd></dl>
|
|
337 |
|
|
338 |
<dl class="function">
|
|
339 |
<dt id="c.json_null">
|
|
340 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_null</tt><big>(</big>void<big>)</big><a class="headerlink" href="#c.json_null" title="Permalink to this definition">¶</a></dt>
|
|
341 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns the JSON null value.</p>
|
|
342 |
</dd></dl>
|
|
343 |
|
|
344 |
</div>
|
|
345 |
<div class="section" id="string">
|
|
346 |
<h2>String<a class="headerlink" href="#string" title="Permalink to this headline">¶</a></h2>
|
|
347 |
<p>Jansson uses UTF-8 as the character encoding. All JSON strings must be
|
|
348 |
valid UTF-8 (or ASCII, as it’s a subset of UTF-8). All Unicode
|
|
349 |
codepoints U+0000 through U+10FFFF are allowed, but you must use
|
|
350 |
length-aware functions if you wish to embed NUL bytes in strings.</p>
|
|
351 |
<dl class="function">
|
|
352 |
<dt id="c.json_string">
|
|
353 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_string</tt><big>(</big>const char<em> *value</em><big>)</big><a class="headerlink" href="#c.json_string" title="Permalink to this definition">¶</a></dt>
|
|
354 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON string, or <em>NULL</em> on error. <em>value</em> must be a
|
|
355 |
valid null terminated UTF-8 encoded Unicode string.</p>
|
|
356 |
</dd></dl>
|
|
357 |
|
|
358 |
<dl class="function">
|
|
359 |
<dt id="c.json_stringn">
|
|
360 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_stringn</tt><big>(</big>const char<em> *value</em>, size_t<em> len</em><big>)</big><a class="headerlink" href="#c.json_stringn" title="Permalink to this definition">¶</a></dt>
|
|
361 |
<dd><em class="refcount">Return value: New reference.</em><p>Like <a class="reference internal" href="#c.json_string" title="json_string"><tt class="xref c c-func docutils literal"><span class="pre">json_string()</span></tt></a>, but with explicit length, so <em>value</em> may
|
|
362 |
contain null characters or not be null terminated.</p>
|
|
363 |
</dd></dl>
|
|
364 |
|
|
365 |
<dl class="function">
|
|
366 |
<dt id="c.json_string_nocheck">
|
|
367 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_string_nocheck</tt><big>(</big>const char<em> *value</em><big>)</big><a class="headerlink" href="#c.json_string_nocheck" title="Permalink to this definition">¶</a></dt>
|
|
368 |
<dd><em class="refcount">Return value: New reference.</em><p>Like <a class="reference internal" href="#c.json_string" title="json_string"><tt class="xref c c-func docutils literal"><span class="pre">json_string()</span></tt></a>, but doesn’t check that <em>value</em> is valid
|
|
369 |
UTF-8. Use this function only if you are certain that this really
|
|
370 |
is the case (e.g. you have already checked it by other means).</p>
|
|
371 |
</dd></dl>
|
|
372 |
|
|
373 |
<dl class="function">
|
|
374 |
<dt id="c.json_stringn_nocheck">
|
|
375 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_stringn_nocheck</tt><big>(</big>const char<em> *value</em>, size_t<em> len</em><big>)</big><a class="headerlink" href="#c.json_stringn_nocheck" title="Permalink to this definition">¶</a></dt>
|
|
376 |
<dd><em class="refcount">Return value: New reference.</em><p>Like <a class="reference internal" href="#c.json_string_nocheck" title="json_string_nocheck"><tt class="xref c c-func docutils literal"><span class="pre">json_string_nocheck()</span></tt></a>, but with explicit length, so
|
|
377 |
<em>value</em> may contain null characters or not be null terminated.</p>
|
|
378 |
</dd></dl>
|
|
379 |
|
|
380 |
<dl class="function">
|
|
381 |
<dt id="c.json_string_value">
|
|
382 |
const char *<tt class="descname">json_string_value</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *string</em><big>)</big><a class="headerlink" href="#c.json_string_value" title="Permalink to this definition">¶</a></dt>
|
|
383 |
<dd><p>Returns the associated value of <em>string</em> as a null terminated UTF-8
|
|
384 |
encoded string, or <em>NULL</em> if <em>string</em> is not a JSON string.</p>
|
|
385 |
<p>The retuned value is read-only and must not be modified or freed by
|
|
386 |
the user. It is valid as long as <em>string</em> exists, i.e. as long as
|
|
387 |
its reference count has not dropped to zero.</p>
|
|
388 |
</dd></dl>
|
|
389 |
|
|
390 |
<dl class="function">
|
|
391 |
<dt id="c.json_string_length">
|
|
392 |
size_t <tt class="descname">json_string_length</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *string</em><big>)</big><a class="headerlink" href="#c.json_string_length" title="Permalink to this definition">¶</a></dt>
|
|
393 |
<dd><p>Returns the length of <em>string</em> in its UTF-8 presentation, or zero
|
|
394 |
if <em>string</em> is not a JSON string.</p>
|
|
395 |
</dd></dl>
|
|
396 |
|
|
397 |
<dl class="function">
|
|
398 |
<dt id="c.json_string_set">
|
|
399 |
int <tt class="descname">json_string_set</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *string</em>, const char<em> *value</em><big>)</big><a class="headerlink" href="#c.json_string_set" title="Permalink to this definition">¶</a></dt>
|
|
400 |
<dd><p>Sets the associated value of <em>string</em> to <em>value</em>. <em>value</em> must be a
|
|
401 |
valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
|
|
402 |
error.</p>
|
|
403 |
</dd></dl>
|
|
404 |
|
|
405 |
<dl class="function">
|
|
406 |
<dt id="c.json_string_setn">
|
|
407 |
int <tt class="descname">json_string_setn</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *string</em>, const char<em> *value</em>, size_t<em> len</em><big>)</big><a class="headerlink" href="#c.json_string_setn" title="Permalink to this definition">¶</a></dt>
|
|
408 |
<dd><p>Like <a class="reference internal" href="#c.json_string_set" title="json_string_set"><tt class="xref c c-func docutils literal"><span class="pre">json_string_set()</span></tt></a>, but with explicit length, so <em>value</em>
|
|
409 |
may contain null characters or not be null terminated.</p>
|
|
410 |
</dd></dl>
|
|
411 |
|
|
412 |
<dl class="function">
|
|
413 |
<dt id="c.json_string_set_nocheck">
|
|
414 |
int <tt class="descname">json_string_set_nocheck</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *string</em>, const char<em> *value</em><big>)</big><a class="headerlink" href="#c.json_string_set_nocheck" title="Permalink to this definition">¶</a></dt>
|
|
415 |
<dd><p>Like <a class="reference internal" href="#c.json_string_set" title="json_string_set"><tt class="xref c c-func docutils literal"><span class="pre">json_string_set()</span></tt></a>, but doesn’t check that <em>value</em> is
|
|
416 |
valid UTF-8. Use this function only if you are certain that this
|
|
417 |
really is the case (e.g. you have already checked it by other
|
|
418 |
means).</p>
|
|
419 |
</dd></dl>
|
|
420 |
|
|
421 |
<dl class="function">
|
|
422 |
<dt id="c.json_string_setn_nocheck">
|
|
423 |
int <tt class="descname">json_string_setn_nocheck</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *string</em>, const char<em> *value</em>, size_t<em> len</em><big>)</big><a class="headerlink" href="#c.json_string_setn_nocheck" title="Permalink to this definition">¶</a></dt>
|
|
424 |
<dd><p>Like <a class="reference internal" href="#c.json_string_set_nocheck" title="json_string_set_nocheck"><tt class="xref c c-func docutils literal"><span class="pre">json_string_set_nocheck()</span></tt></a>, but with explicit length,
|
|
425 |
so <em>value</em> may contain null characters or not be null terminated.</p>
|
|
426 |
</dd></dl>
|
|
427 |
|
|
428 |
</div>
|
|
429 |
<div class="section" id="number">
|
|
430 |
<h2>Number<a class="headerlink" href="#number" title="Permalink to this headline">¶</a></h2>
|
|
431 |
<p>The JSON specification only contains one numeric type, “number”. The C
|
|
432 |
programming language has distinct types for integer and floating-point
|
|
433 |
numbers, so for practical reasons Jansson also has distinct types for
|
|
434 |
the two. They are called “integer” and “real”, respectively. For more
|
|
435 |
information, see <a class="reference internal" href="conformance.html#rfc-conformance"><em>RFC Conformance</em></a>.</p>
|
|
436 |
<dl class="type">
|
|
437 |
<dt id="c.json_int_t">
|
|
438 |
<tt class="descname">json_int_t</tt><a class="headerlink" href="#c.json_int_t" title="Permalink to this definition">¶</a></dt>
|
|
439 |
<dd><p>This is the C type that is used to store JSON integer values. It
|
|
440 |
represents the widest integer type available on your system. In
|
|
441 |
practice it’s just a typedef of <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> if your compiler
|
|
442 |
supports it, otherwise <tt class="docutils literal"><span class="pre">long</span></tt>.</p>
|
|
443 |
<p>Usually, you can safely use plain <tt class="docutils literal"><span class="pre">int</span></tt> in place of
|
|
444 |
<tt class="docutils literal"><span class="pre">json_int_t</span></tt>, and the implicit C integer conversion handles the
|
|
445 |
rest. Only when you know that you need the full 64-bit range, you
|
|
446 |
should use <tt class="docutils literal"><span class="pre">json_int_t</span></tt> explicitly.</p>
|
|
447 |
</dd></dl>
|
|
448 |
|
|
449 |
<dl class="docutils">
|
|
450 |
<dt><tt class="docutils literal"><span class="pre">JSON_INTEGER_IS_LONG_LONG</span></tt></dt>
|
|
451 |
<dd><p class="first">This is a preprocessor variable that holds the value 1 if
|
|
452 |
<a class="reference internal" href="#c.json_int_t" title="json_int_t"><tt class="xref c c-type docutils literal"><span class="pre">json_int_t</span></tt></a> is <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>, and 0 if it’s <tt class="docutils literal"><span class="pre">long</span></tt>. It
|
|
453 |
can be used as follows:</p>
|
|
454 |
<div class="last highlight-c"><div class="highlight"><pre><span class="cp">#if JSON_INTEGER_IS_LONG_LONG</span>
|
|
455 |
<span class="cm">/* Code specific for long long */</span>
|
|
456 |
<span class="cp">#else</span>
|
|
457 |
<span class="cm">/* Code specific for long */</span>
|
|
458 |
<span class="cp">#endif</span>
|
|
459 |
</pre></div>
|
|
460 |
</div>
|
|
461 |
</dd>
|
|
462 |
<dt><tt class="docutils literal"><span class="pre">JSON_INTEGER_FORMAT</span></tt></dt>
|
|
463 |
<dd><p class="first">This is a macro that expands to a <tt class="xref c c-func docutils literal"><span class="pre">printf()</span></tt> conversion
|
|
464 |
specifier that corresponds to <a class="reference internal" href="#c.json_int_t" title="json_int_t"><tt class="xref c c-type docutils literal"><span class="pre">json_int_t</span></tt></a>, without the
|
|
465 |
leading <tt class="docutils literal"><span class="pre">%</span></tt> sign, i.e. either <tt class="docutils literal"><span class="pre">"lld"</span></tt> or <tt class="docutils literal"><span class="pre">"ld"</span></tt>. This macro
|
|
466 |
is required because the actual type of <a class="reference internal" href="#c.json_int_t" title="json_int_t"><tt class="xref c c-type docutils literal"><span class="pre">json_int_t</span></tt></a> can be
|
|
467 |
either <tt class="docutils literal"><span class="pre">long</span></tt> or <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>, and <tt class="xref c c-func docutils literal"><span class="pre">printf()</span></tt> reuiqres
|
|
468 |
different length modifiers for the two.</p>
|
|
469 |
<p>Example:</p>
|
|
470 |
<div class="last highlight-c"><div class="highlight"><pre><span class="kt">json_int_t</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">123123123</span><span class="p">;</span>
|
|
471 |
<span class="n">printf</span><span class="p">(</span><span class="s">"x is %"</span> <span class="n">JSON_INTEGER_FORMAT</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">x</span><span class="p">);</span>
|
|
472 |
</pre></div>
|
|
473 |
</div>
|
|
474 |
</dd>
|
|
475 |
</dl>
|
|
476 |
<dl class="function">
|
|
477 |
<dt id="c.json_integer">
|
|
478 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_integer</tt><big>(</big><a class="reference internal" href="#c.json_int_t" title="json_int_t">json_int_t</a><em> value</em><big>)</big><a class="headerlink" href="#c.json_integer" title="Permalink to this definition">¶</a></dt>
|
|
479 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON integer, or <em>NULL</em> on error.</p>
|
|
480 |
</dd></dl>
|
|
481 |
|
|
482 |
<dl class="function">
|
|
483 |
<dt id="c.json_integer_value">
|
|
484 |
<a class="reference internal" href="#c.json_int_t" title="json_int_t">json_int_t</a> <tt class="descname">json_integer_value</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *integer</em><big>)</big><a class="headerlink" href="#c.json_integer_value" title="Permalink to this definition">¶</a></dt>
|
|
485 |
<dd><p>Returns the associated value of <em>integer</em>, or 0 if <em>json</em> is not a
|
|
486 |
JSON integer.</p>
|
|
487 |
</dd></dl>
|
|
488 |
|
|
489 |
<dl class="function">
|
|
490 |
<dt id="c.json_integer_set">
|
|
491 |
int <tt class="descname">json_integer_set</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *integer</em>, <a class="reference internal" href="#c.json_int_t" title="json_int_t">json_int_t</a><em> value</em><big>)</big><a class="headerlink" href="#c.json_integer_set" title="Permalink to this definition">¶</a></dt>
|
|
492 |
<dd><p>Sets the associated value of <em>integer</em> to <em>value</em>. Returns 0 on
|
|
493 |
success and -1 if <em>integer</em> is not a JSON integer.</p>
|
|
494 |
</dd></dl>
|
|
495 |
|
|
496 |
<dl class="function">
|
|
497 |
<dt id="c.json_real">
|
|
498 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_real</tt><big>(</big>double<em> value</em><big>)</big><a class="headerlink" href="#c.json_real" title="Permalink to this definition">¶</a></dt>
|
|
499 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON real, or <em>NULL</em> on error.</p>
|
|
500 |
</dd></dl>
|
|
501 |
|
|
502 |
<dl class="function">
|
|
503 |
<dt id="c.json_real_value">
|
|
504 |
double <tt class="descname">json_real_value</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *real</em><big>)</big><a class="headerlink" href="#c.json_real_value" title="Permalink to this definition">¶</a></dt>
|
|
505 |
<dd><p>Returns the associated value of <em>real</em>, or 0.0 if <em>real</em> is not a
|
|
506 |
JSON real.</p>
|
|
507 |
</dd></dl>
|
|
508 |
|
|
509 |
<dl class="function">
|
|
510 |
<dt id="c.json_real_set">
|
|
511 |
int <tt class="descname">json_real_set</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *real</em>, double<em> value</em><big>)</big><a class="headerlink" href="#c.json_real_set" title="Permalink to this definition">¶</a></dt>
|
|
512 |
<dd><p>Sets the associated value of <em>real</em> to <em>value</em>. Returns 0 on
|
|
513 |
success and -1 if <em>real</em> is not a JSON real.</p>
|
|
514 |
</dd></dl>
|
|
515 |
|
|
516 |
<p>In addition to the functions above, there’s a common query function
|
|
517 |
for integers and reals:</p>
|
|
518 |
<dl class="function">
|
|
519 |
<dt id="c.json_number_value">
|
|
520 |
double <tt class="descname">json_number_value</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em><big>)</big><a class="headerlink" href="#c.json_number_value" title="Permalink to this definition">¶</a></dt>
|
|
521 |
<dd><p>Returns the associated value of the JSON integer or JSON real
|
|
522 |
<em>json</em>, cast to double regardless of the actual type. If <em>json</em> is
|
|
523 |
neither JSON real nor JSON integer, 0.0 is returned.</p>
|
|
524 |
</dd></dl>
|
|
525 |
|
|
526 |
</div>
|
|
527 |
<div class="section" id="array">
|
|
528 |
<h2>Array<a class="headerlink" href="#array" title="Permalink to this headline">¶</a></h2>
|
|
529 |
<p>A JSON array is an ordered collection of other JSON values.</p>
|
|
530 |
<dl class="function">
|
|
531 |
<dt id="c.json_array">
|
|
532 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_array</tt><big>(</big>void<big>)</big><a class="headerlink" href="#c.json_array" title="Permalink to this definition">¶</a></dt>
|
|
533 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON array, or <em>NULL</em> on error. Initially, the array
|
|
534 |
is empty.</p>
|
|
535 |
</dd></dl>
|
|
536 |
|
|
537 |
<dl class="function">
|
|
538 |
<dt id="c.json_array_size">
|
|
539 |
size_t <tt class="descname">json_array_size</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em><big>)</big><a class="headerlink" href="#c.json_array_size" title="Permalink to this definition">¶</a></dt>
|
|
540 |
<dd><p>Returns the number of elements in <em>array</em>, or 0 if <em>array</em> is NULL
|
|
541 |
or not a JSON array.</p>
|
|
542 |
</dd></dl>
|
|
543 |
|
|
544 |
<dl class="function">
|
|
545 |
<dt id="c.json_array_get">
|
|
546 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_array_get</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, size_t<em> index</em><big>)</big><a class="headerlink" href="#c.json_array_get" title="Permalink to this definition">¶</a></dt>
|
|
547 |
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Returns the element in <em>array</em> at position <em>index</em>. The valid range
|
|
548 |
for <em>index</em> is from 0 to the return value of
|
|
549 |
<a class="reference internal" href="#c.json_array_size" title="json_array_size"><tt class="xref c c-func docutils literal"><span class="pre">json_array_size()</span></tt></a> minus 1. If <em>array</em> is not a JSON array,
|
|
550 |
if <em>array</em> is <em>NULL</em>, or if <em>index</em> is out of range, <em>NULL</em> is
|
|
551 |
returned.</p>
|
|
552 |
</dd></dl>
|
|
553 |
|
|
554 |
<dl class="function">
|
|
555 |
<dt id="c.json_array_set">
|
|
556 |
int <tt class="descname">json_array_set</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, size_t<em> index</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_array_set" title="Permalink to this definition">¶</a></dt>
|
|
557 |
<dd><p>Replaces the element in <em>array</em> at position <em>index</em> with <em>value</em>.
|
|
558 |
The valid range for <em>index</em> is from 0 to the return value of
|
|
559 |
<a class="reference internal" href="#c.json_array_size" title="json_array_size"><tt class="xref c c-func docutils literal"><span class="pre">json_array_size()</span></tt></a> minus 1. Returns 0 on success and -1 on
|
|
560 |
error.</p>
|
|
561 |
</dd></dl>
|
|
562 |
|
|
563 |
<dl class="function">
|
|
564 |
<dt id="c.json_array_set_new">
|
|
565 |
int <tt class="descname">json_array_set_new</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, size_t<em> index</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_array_set_new" title="Permalink to this definition">¶</a></dt>
|
|
566 |
<dd><p>Like <a class="reference internal" href="#c.json_array_set" title="json_array_set"><tt class="xref c c-func docutils literal"><span class="pre">json_array_set()</span></tt></a> but steals the reference to <em>value</em>.
|
|
567 |
This is useful when <em>value</em> is newly created and not used after
|
|
568 |
the call.</p>
|
|
569 |
</dd></dl>
|
|
570 |
|
|
571 |
<dl class="function">
|
|
572 |
<dt id="c.json_array_append">
|
|
573 |
int <tt class="descname">json_array_append</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_array_append" title="Permalink to this definition">¶</a></dt>
|
|
574 |
<dd><p>Appends <em>value</em> to the end of <em>array</em>, growing the size of <em>array</em>
|
|
575 |
by 1. Returns 0 on success and -1 on error.</p>
|
|
576 |
</dd></dl>
|
|
577 |
|
|
578 |
<dl class="function">
|
|
579 |
<dt id="c.json_array_append_new">
|
|
580 |
int <tt class="descname">json_array_append_new</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_array_append_new" title="Permalink to this definition">¶</a></dt>
|
|
581 |
<dd><p>Like <a class="reference internal" href="#c.json_array_append" title="json_array_append"><tt class="xref c c-func docutils literal"><span class="pre">json_array_append()</span></tt></a> but steals the reference to
|
|
582 |
<em>value</em>. This is useful when <em>value</em> is newly created and not used
|
|
583 |
after the call.</p>
|
|
584 |
</dd></dl>
|
|
585 |
|
|
586 |
<dl class="function">
|
|
587 |
<dt id="c.json_array_insert">
|
|
588 |
int <tt class="descname">json_array_insert</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, size_t<em> index</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_array_insert" title="Permalink to this definition">¶</a></dt>
|
|
589 |
<dd><p>Inserts <em>value</em> to <em>array</em> at position <em>index</em>, shifting the
|
|
590 |
elements at <em>index</em> and after it one position towards the end of
|
|
591 |
the array. Returns 0 on success and -1 on error.</p>
|
|
592 |
</dd></dl>
|
|
593 |
|
|
594 |
<dl class="function">
|
|
595 |
<dt id="c.json_array_insert_new">
|
|
596 |
int <tt class="descname">json_array_insert_new</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, size_t<em> index</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_array_insert_new" title="Permalink to this definition">¶</a></dt>
|
|
597 |
<dd><p>Like <a class="reference internal" href="#c.json_array_insert" title="json_array_insert"><tt class="xref c c-func docutils literal"><span class="pre">json_array_insert()</span></tt></a> but steals the reference to
|
|
598 |
<em>value</em>. This is useful when <em>value</em> is newly created and not used
|
|
599 |
after the call.</p>
|
|
600 |
</dd></dl>
|
|
601 |
|
|
602 |
<dl class="function">
|
|
603 |
<dt id="c.json_array_remove">
|
|
604 |
int <tt class="descname">json_array_remove</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, size_t<em> index</em><big>)</big><a class="headerlink" href="#c.json_array_remove" title="Permalink to this definition">¶</a></dt>
|
|
605 |
<dd><p>Removes the element in <em>array</em> at position <em>index</em>, shifting the
|
|
606 |
elements after <em>index</em> one position towards the start of the array.
|
|
607 |
Returns 0 on success and -1 on error. The reference count of the
|
|
608 |
removed value is decremented.</p>
|
|
609 |
</dd></dl>
|
|
610 |
|
|
611 |
<dl class="function">
|
|
612 |
<dt id="c.json_array_clear">
|
|
613 |
int <tt class="descname">json_array_clear</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em><big>)</big><a class="headerlink" href="#c.json_array_clear" title="Permalink to this definition">¶</a></dt>
|
|
614 |
<dd><p>Removes all elements from <em>array</em>. Returns 0 on sucess and -1 on
|
|
615 |
error. The reference count of all removed values are decremented.</p>
|
|
616 |
</dd></dl>
|
|
617 |
|
|
618 |
<dl class="function">
|
|
619 |
<dt id="c.json_array_extend">
|
|
620 |
int <tt class="descname">json_array_extend</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *array</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *other_array</em><big>)</big><a class="headerlink" href="#c.json_array_extend" title="Permalink to this definition">¶</a></dt>
|
|
621 |
<dd><p>Appends all elements in <em>other_array</em> to the end of <em>array</em>.
|
|
622 |
Returns 0 on success and -1 on error.</p>
|
|
623 |
</dd></dl>
|
|
624 |
|
|
625 |
<p>The following macro can be used to iterate through all elements
|
|
626 |
in an array.</p>
|
|
627 |
<dl class="function">
|
|
628 |
<dt id="c.json_array_foreach">
|
|
629 |
<tt class="descname">json_array_foreach</tt><big>(</big>array, index, value<big>)</big><a class="headerlink" href="#c.json_array_foreach" title="Permalink to this definition">¶</a></dt>
|
|
630 |
<dd><p>Iterate over every element of <tt class="docutils literal"><span class="pre">array</span></tt>, running the block
|
|
631 |
of code that follows each time with the proper values set to
|
|
632 |
variables <tt class="docutils literal"><span class="pre">index</span></tt> and <tt class="docutils literal"><span class="pre">value</span></tt>, of types <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt> and
|
|
633 |
<a class="reference internal" href="#c.json_t" title="json_t"><tt class="xref c c-type docutils literal"><span class="pre">json_t</span> <span class="pre">*</span></tt></a> respectively. Example:</p>
|
|
634 |
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* array is a JSON array */</span>
|
|
635 |
<span class="kt">size_t</span> <span class="n">index</span><span class="p">;</span>
|
|
636 |
<span class="kt">json_t</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
|
|
637 |
|
|
638 |
<span class="n">json_array_foreach</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="n">index</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
|
|
639 |
<span class="cm">/* block of code that uses index and value */</span>
|
|
640 |
<span class="p">}</span>
|
|
641 |
</pre></div>
|
|
642 |
</div>
|
|
643 |
<p>The items are returned in increasing index order.</p>
|
|
644 |
<p>This macro expands to an ordinary <tt class="docutils literal"><span class="pre">for</span></tt> statement upon
|
|
645 |
preprocessing, so its performance is equivalent to that of
|
|
646 |
hand-written code using the array access functions.
|
|
647 |
The main advantage of this macro is that it abstracts
|
|
648 |
away the complexity, and makes for shorter, more
|
|
649 |
concise code.</p>
|
|
650 |
<div class="versionadded">
|
|
651 |
<p><span class="versionmodified">New in version 2.5.</span></p>
|
|
652 |
</div>
|
|
653 |
</dd></dl>
|
|
654 |
|
|
655 |
</div>
|
|
656 |
<div class="section" id="object">
|
|
657 |
<h2>Object<a class="headerlink" href="#object" title="Permalink to this headline">¶</a></h2>
|
|
658 |
<p>A JSON object is a dictionary of key-value pairs, where the key is a
|
|
659 |
Unicode string and the value is any JSON value.</p>
|
|
660 |
<p>Even though NUL bytes are allowed in string values, they are not
|
|
661 |
allowed in object keys.</p>
|
|
662 |
<dl class="function">
|
|
663 |
<dt id="c.json_object">
|
|
664 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_object</tt><big>(</big>void<big>)</big><a class="headerlink" href="#c.json_object" title="Permalink to this definition">¶</a></dt>
|
|
665 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON object, or <em>NULL</em> on error. Initially, the
|
|
666 |
object is empty.</p>
|
|
667 |
</dd></dl>
|
|
668 |
|
|
669 |
<dl class="function">
|
|
670 |
<dt id="c.json_object_size">
|
|
671 |
size_t <tt class="descname">json_object_size</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em><big>)</big><a class="headerlink" href="#c.json_object_size" title="Permalink to this definition">¶</a></dt>
|
|
672 |
<dd><p>Returns the number of elements in <em>object</em>, or 0 if <em>object</em> is not
|
|
673 |
a JSON object.</p>
|
|
674 |
</dd></dl>
|
|
675 |
|
|
676 |
<dl class="function">
|
|
677 |
<dt id="c.json_object_get">
|
|
678 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_object_get</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, const char<em> *key</em><big>)</big><a class="headerlink" href="#c.json_object_get" title="Permalink to this definition">¶</a></dt>
|
|
679 |
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Get a value corresponding to <em>key</em> from <em>object</em>. Returns <em>NULL</em> if
|
|
680 |
<em>key</em> is not found and on error.</p>
|
|
681 |
</dd></dl>
|
|
682 |
|
|
683 |
<dl class="function">
|
|
684 |
<dt id="c.json_object_set">
|
|
685 |
int <tt class="descname">json_object_set</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, const char<em> *key</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_object_set" title="Permalink to this definition">¶</a></dt>
|
|
686 |
<dd><p>Set the value of <em>key</em> to <em>value</em> in <em>object</em>. <em>key</em> must be a
|
|
687 |
valid null terminated UTF-8 encoded Unicode string. If there
|
|
688 |
already is a value for <em>key</em>, it is replaced by the new value.
|
|
689 |
Returns 0 on success and -1 on error.</p>
|
|
690 |
</dd></dl>
|
|
691 |
|
|
692 |
<dl class="function">
|
|
693 |
<dt id="c.json_object_set_nocheck">
|
|
694 |
int <tt class="descname">json_object_set_nocheck</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, const char<em> *key</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_object_set_nocheck" title="Permalink to this definition">¶</a></dt>
|
|
695 |
<dd><p>Like <a class="reference internal" href="#c.json_object_set" title="json_object_set"><tt class="xref c c-func docutils literal"><span class="pre">json_object_set()</span></tt></a>, but doesn’t check that <em>key</em> is
|
|
696 |
valid UTF-8. Use this function only if you are certain that this
|
|
697 |
really is the case (e.g. you have already checked it by other
|
|
698 |
means).</p>
|
|
699 |
</dd></dl>
|
|
700 |
|
|
701 |
<dl class="function">
|
|
702 |
<dt id="c.json_object_set_new">
|
|
703 |
int <tt class="descname">json_object_set_new</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, const char<em> *key</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_object_set_new" title="Permalink to this definition">¶</a></dt>
|
|
704 |
<dd><p>Like <a class="reference internal" href="#c.json_object_set" title="json_object_set"><tt class="xref c c-func docutils literal"><span class="pre">json_object_set()</span></tt></a> but steals the reference to
|
|
705 |
<em>value</em>. This is useful when <em>value</em> is newly created and not used
|
|
706 |
after the call.</p>
|
|
707 |
</dd></dl>
|
|
708 |
|
|
709 |
<dl class="function">
|
|
710 |
<dt id="c.json_object_set_new_nocheck">
|
|
711 |
int <tt class="descname">json_object_set_new_nocheck</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, const char<em> *key</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_object_set_new_nocheck" title="Permalink to this definition">¶</a></dt>
|
|
712 |
<dd><p>Like <a class="reference internal" href="#c.json_object_set_new" title="json_object_set_new"><tt class="xref c c-func docutils literal"><span class="pre">json_object_set_new()</span></tt></a>, but doesn’t check that <em>key</em> is
|
|
713 |
valid UTF-8. Use this function only if you are certain that this
|
|
714 |
really is the case (e.g. you have already checked it by other
|
|
715 |
means).</p>
|
|
716 |
</dd></dl>
|
|
717 |
|
|
718 |
<dl class="function">
|
|
719 |
<dt id="c.json_object_del">
|
|
720 |
int <tt class="descname">json_object_del</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, const char<em> *key</em><big>)</big><a class="headerlink" href="#c.json_object_del" title="Permalink to this definition">¶</a></dt>
|
|
721 |
<dd><p>Delete <em>key</em> from <em>object</em> if it exists. Returns 0 on success, or
|
|
722 |
-1 if <em>key</em> was not found. The reference count of the removed value
|
|
723 |
is decremented.</p>
|
|
724 |
</dd></dl>
|
|
725 |
|
|
726 |
<dl class="function">
|
|
727 |
<dt id="c.json_object_clear">
|
|
728 |
int <tt class="descname">json_object_clear</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em><big>)</big><a class="headerlink" href="#c.json_object_clear" title="Permalink to this definition">¶</a></dt>
|
|
729 |
<dd><p>Remove all elements from <em>object</em>. Returns 0 on success and -1 if
|
|
730 |
<em>object</em> is not a JSON object. The reference count of all removed
|
|
731 |
values are decremented.</p>
|
|
732 |
</dd></dl>
|
|
733 |
|
|
734 |
<dl class="function">
|
|
735 |
<dt id="c.json_object_update">
|
|
736 |
int <tt class="descname">json_object_update</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *other</em><big>)</big><a class="headerlink" href="#c.json_object_update" title="Permalink to this definition">¶</a></dt>
|
|
737 |
<dd><p>Update <em>object</em> with the key-value pairs from <em>other</em>, overwriting
|
|
738 |
existing keys. Returns 0 on success or -1 on error.</p>
|
|
739 |
</dd></dl>
|
|
740 |
|
|
741 |
<dl class="function">
|
|
742 |
<dt id="c.json_object_update_existing">
|
|
743 |
int <tt class="descname">json_object_update_existing</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *other</em><big>)</big><a class="headerlink" href="#c.json_object_update_existing" title="Permalink to this definition">¶</a></dt>
|
|
744 |
<dd><p>Like <a class="reference internal" href="#c.json_object_update" title="json_object_update"><tt class="xref c c-func docutils literal"><span class="pre">json_object_update()</span></tt></a>, but only the values of existing
|
|
745 |
keys are updated. No new keys are created. Returns 0 on success or
|
|
746 |
-1 on error.</p>
|
|
747 |
<div class="versionadded">
|
|
748 |
<p><span class="versionmodified">New in version 2.3.</span></p>
|
|
749 |
</div>
|
|
750 |
</dd></dl>
|
|
751 |
|
|
752 |
<dl class="function">
|
|
753 |
<dt id="c.json_object_update_missing">
|
|
754 |
int <tt class="descname">json_object_update_missing</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *other</em><big>)</big><a class="headerlink" href="#c.json_object_update_missing" title="Permalink to this definition">¶</a></dt>
|
|
755 |
<dd><p>Like <a class="reference internal" href="#c.json_object_update" title="json_object_update"><tt class="xref c c-func docutils literal"><span class="pre">json_object_update()</span></tt></a>, but only new keys are created.
|
|
756 |
The value of any existing key is not changed. Returns 0 on success
|
|
757 |
or -1 on error.</p>
|
|
758 |
<div class="versionadded">
|
|
759 |
<p><span class="versionmodified">New in version 2.3.</span></p>
|
|
760 |
</div>
|
|
761 |
</dd></dl>
|
|
762 |
|
|
763 |
<p>The following macro can be used to iterate through all key-value pairs
|
|
764 |
in an object.</p>
|
|
765 |
<dl class="function">
|
|
766 |
<dt id="c.json_object_foreach">
|
|
767 |
<tt class="descname">json_object_foreach</tt><big>(</big>object, key, value<big>)</big><a class="headerlink" href="#c.json_object_foreach" title="Permalink to this definition">¶</a></dt>
|
|
768 |
<dd><p>Iterate over every key-value pair of <tt class="docutils literal"><span class="pre">object</span></tt>, running the block
|
|
769 |
of code that follows each time with the proper values set to
|
|
770 |
variables <tt class="docutils literal"><span class="pre">key</span></tt> and <tt class="docutils literal"><span class="pre">value</span></tt>, of types <tt class="xref c c-type docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> and
|
|
771 |
<a class="reference internal" href="#c.json_t" title="json_t"><tt class="xref c c-type docutils literal"><span class="pre">json_t</span> <span class="pre">*</span></tt></a> respectively. Example:</p>
|
|
772 |
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* obj is a JSON object */</span>
|
|
773 |
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">key</span><span class="p">;</span>
|
|
774 |
<span class="kt">json_t</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
|
|
775 |
|
|
776 |
<span class="n">json_object_foreach</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
|
|
777 |
<span class="cm">/* block of code that uses key and value */</span>
|
|
778 |
<span class="p">}</span>
|
|
779 |
</pre></div>
|
|
780 |
</div>
|
|
781 |
<p>The items are not returned in any particular order.</p>
|
|
782 |
<p>This macro expands to an ordinary <tt class="docutils literal"><span class="pre">for</span></tt> statement upon
|
|
783 |
preprocessing, so its performance is equivalent to that of
|
|
784 |
hand-written iteration code using the object iteration protocol
|
|
785 |
(see below). The main advantage of this macro is that it abstracts
|
|
786 |
away the complexity behind iteration, and makes for shorter, more
|
|
787 |
concise code.</p>
|
|
788 |
<div class="versionadded">
|
|
789 |
<p><span class="versionmodified">New in version 2.3.</span></p>
|
|
790 |
</div>
|
|
791 |
</dd></dl>
|
|
792 |
|
|
793 |
<p>The following functions implement an iteration protocol for objects,
|
|
794 |
allowing to iterate through all key-value pairs in an object. The
|
|
795 |
items are not returned in any particular order, as this would require
|
|
796 |
sorting due to the internal hashtable implementation.</p>
|
|
797 |
<dl class="function">
|
|
798 |
<dt id="c.json_object_iter">
|
|
799 |
void *<tt class="descname">json_object_iter</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em><big>)</big><a class="headerlink" href="#c.json_object_iter" title="Permalink to this definition">¶</a></dt>
|
|
800 |
<dd><p>Returns an opaque iterator which can be used to iterate over all
|
|
801 |
key-value pairs in <em>object</em>, or <em>NULL</em> if <em>object</em> is empty.</p>
|
|
802 |
</dd></dl>
|
|
803 |
|
|
804 |
<dl class="function">
|
|
805 |
<dt id="c.json_object_iter_at">
|
|
806 |
void *<tt class="descname">json_object_iter_at</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, const char<em> *key</em><big>)</big><a class="headerlink" href="#c.json_object_iter_at" title="Permalink to this definition">¶</a></dt>
|
|
807 |
<dd><p>Like <a class="reference internal" href="#c.json_object_iter" title="json_object_iter"><tt class="xref c c-func docutils literal"><span class="pre">json_object_iter()</span></tt></a>, but returns an iterator to the
|
|
808 |
key-value pair in <em>object</em> whose key is equal to <em>key</em>, or NULL if
|
|
809 |
<em>key</em> is not found in <em>object</em>. Iterating forward to the end of
|
|
810 |
<em>object</em> only yields all key-value pairs of the object if <em>key</em>
|
|
811 |
happens to be the first key in the underlying hash table.</p>
|
|
812 |
</dd></dl>
|
|
813 |
|
|
814 |
<dl class="function">
|
|
815 |
<dt id="c.json_object_iter_next">
|
|
816 |
void *<tt class="descname">json_object_iter_next</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, void<em> *iter</em><big>)</big><a class="headerlink" href="#c.json_object_iter_next" title="Permalink to this definition">¶</a></dt>
|
|
817 |
<dd><p>Returns an iterator pointing to the next key-value pair in <em>object</em>
|
|
818 |
after <em>iter</em>, or <em>NULL</em> if the whole object has been iterated
|
|
819 |
through.</p>
|
|
820 |
</dd></dl>
|
|
821 |
|
|
822 |
<dl class="function">
|
|
823 |
<dt id="c.json_object_iter_key">
|
|
824 |
const char *<tt class="descname">json_object_iter_key</tt><big>(</big>void<em> *iter</em><big>)</big><a class="headerlink" href="#c.json_object_iter_key" title="Permalink to this definition">¶</a></dt>
|
|
825 |
<dd><p>Extract the associated key from <em>iter</em>.</p>
|
|
826 |
</dd></dl>
|
|
827 |
|
|
828 |
<dl class="function">
|
|
829 |
<dt id="c.json_object_iter_value">
|
|
830 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_object_iter_value</tt><big>(</big>void<em> *iter</em><big>)</big><a class="headerlink" href="#c.json_object_iter_value" title="Permalink to this definition">¶</a></dt>
|
|
831 |
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Extract the associated value from <em>iter</em>.</p>
|
|
832 |
</dd></dl>
|
|
833 |
|
|
834 |
<dl class="function">
|
|
835 |
<dt id="c.json_object_iter_set">
|
|
836 |
int <tt class="descname">json_object_iter_set</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, void<em> *iter</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_object_iter_set" title="Permalink to this definition">¶</a></dt>
|
|
837 |
<dd><p>Set the value of the key-value pair in <em>object</em>, that is pointed to
|
|
838 |
by <em>iter</em>, to <em>value</em>.</p>
|
|
839 |
</dd></dl>
|
|
840 |
|
|
841 |
<dl class="function">
|
|
842 |
<dt id="c.json_object_iter_set_new">
|
|
843 |
int <tt class="descname">json_object_iter_set_new</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *object</em>, void<em> *iter</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_object_iter_set_new" title="Permalink to this definition">¶</a></dt>
|
|
844 |
<dd><p>Like <a class="reference internal" href="#c.json_object_iter_set" title="json_object_iter_set"><tt class="xref c c-func docutils literal"><span class="pre">json_object_iter_set()</span></tt></a>, but steals the reference to
|
|
845 |
<em>value</em>. This is useful when <em>value</em> is newly created and not used
|
|
846 |
after the call.</p>
|
|
847 |
</dd></dl>
|
|
848 |
|
|
849 |
<dl class="function">
|
|
850 |
<dt id="c.json_object_key_to_iter">
|
|
851 |
void *<tt class="descname">json_object_key_to_iter</tt><big>(</big>const char<em> *key</em><big>)</big><a class="headerlink" href="#c.json_object_key_to_iter" title="Permalink to this definition">¶</a></dt>
|
|
852 |
<dd><p>Like <a class="reference internal" href="#c.json_object_iter_at" title="json_object_iter_at"><tt class="xref c c-func docutils literal"><span class="pre">json_object_iter_at()</span></tt></a>, but much faster. Only works for
|
|
853 |
values returned by <a class="reference internal" href="#c.json_object_iter_key" title="json_object_iter_key"><tt class="xref c c-func docutils literal"><span class="pre">json_object_iter_key()</span></tt></a>. Using other keys
|
|
854 |
will lead to segfaults. This function is used internally to
|
|
855 |
implement <a class="reference internal" href="#c.json_object_foreach" title="json_object_foreach"><tt class="xref c c-func docutils literal"><span class="pre">json_object_foreach()</span></tt></a>.</p>
|
|
856 |
<div class="versionadded">
|
|
857 |
<p><span class="versionmodified">New in version 2.3.</span></p>
|
|
858 |
</div>
|
|
859 |
</dd></dl>
|
|
860 |
|
|
861 |
<p>The iteration protocol can be used for example as follows:</p>
|
|
862 |
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* obj is a JSON object */</span>
|
|
863 |
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">key</span><span class="p">;</span>
|
|
864 |
<span class="kt">json_t</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
|
|
865 |
|
|
866 |
<span class="kt">void</span> <span class="o">*</span><span class="n">iter</span> <span class="o">=</span> <span class="n">json_object_iter</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
|
|
867 |
<span class="k">while</span><span class="p">(</span><span class="n">iter</span><span class="p">)</span>
|
|
868 |
<span class="p">{</span>
|
|
869 |
<span class="n">key</span> <span class="o">=</span> <span class="n">json_object_iter_key</span><span class="p">(</span><span class="n">iter</span><span class="p">);</span>
|
|
870 |
<span class="n">value</span> <span class="o">=</span> <span class="n">json_object_iter_value</span><span class="p">(</span><span class="n">iter</span><span class="p">);</span>
|
|
871 |
<span class="cm">/* use key and value ... */</span>
|
|
872 |
<span class="n">iter</span> <span class="o">=</span> <span class="n">json_object_iter_next</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">iter</span><span class="p">);</span>
|
|
873 |
<span class="p">}</span>
|
|
874 |
</pre></div>
|
|
875 |
</div>
|
|
876 |
<dl class="function">
|
|
877 |
<dt id="c.json_object_seed">
|
|
878 |
void <tt class="descname">json_object_seed</tt><big>(</big>size_t<em> seed</em><big>)</big><a class="headerlink" href="#c.json_object_seed" title="Permalink to this definition">¶</a></dt>
|
|
879 |
<dd><p>Seed the hash function used in Jansson’s hashtable implementation.
|
|
880 |
The seed is used to randomize the hash function so that an
|
|
881 |
attacker cannot control its output.</p>
|
|
882 |
<p>If <em>seed</em> is 0, Jansson generates the seed itselfy by reading
|
|
883 |
random data from the operating system’s entropy sources. If no
|
|
884 |
entropy sources are available, falls back to using a combination
|
|
885 |
of the current timestamp (with microsecond precision if possible)
|
|
886 |
and the process ID.</p>
|
|
887 |
<p>If called at all, this function must be called before any calls to
|
|
888 |
<a class="reference internal" href="#c.json_object" title="json_object"><tt class="xref c c-func docutils literal"><span class="pre">json_object()</span></tt></a>, either explicit or implicit. If this
|
|
889 |
function is not called by the user, the first call to
|
|
890 |
<a class="reference internal" href="#c.json_object" title="json_object"><tt class="xref c c-func docutils literal"><span class="pre">json_object()</span></tt></a> (either explicit or implicit) seeds the hash
|
|
891 |
function. See <a class="reference internal" href="portability.html#portability-thread-safety"><em>Thread safety</em></a> for notes on thread
|
|
892 |
safety.</p>
|
|
893 |
<p>If repeatable results are required, for e.g. unit tests, the hash
|
|
894 |
function can be “unrandomized” by calling <a class="reference internal" href="#c.json_object_seed" title="json_object_seed"><tt class="xref c c-func docutils literal"><span class="pre">json_object_seed()</span></tt></a>
|
|
895 |
with a constant value on program startup, e.g.
|
|
896 |
<tt class="docutils literal"><span class="pre">json_object_seed(1)</span></tt>.</p>
|
|
897 |
<div class="versionadded">
|
|
898 |
<p><span class="versionmodified">New in version 2.6.</span></p>
|
|
899 |
</div>
|
|
900 |
</dd></dl>
|
|
901 |
|
|
902 |
</div>
|
|
903 |
<div class="section" id="error-reporting">
|
|
904 |
<h2>Error reporting<a class="headerlink" href="#error-reporting" title="Permalink to this headline">¶</a></h2>
|
|
905 |
<p>Jansson uses a single struct type to pass error information to the
|
|
906 |
user. See sections <a class="reference internal" href="#apiref-decoding"><em>Decoding</em></a>, <a class="reference internal" href="#apiref-pack"><em>Building Values</em></a> and
|
|
907 |
<a class="reference internal" href="#apiref-unpack"><em>Parsing and Validating Values</em></a> for functions that pass error information using
|
|
908 |
this struct.</p>
|
|
909 |
<dl class="type">
|
|
910 |
<dt id="c.json_error_t">
|
|
911 |
<tt class="descname">json_error_t</tt><a class="headerlink" href="#c.json_error_t" title="Permalink to this definition">¶</a></dt>
|
|
912 |
<dd><dl class="member">
|
|
913 |
<dt>
|
|
914 |
<tt class="descname">char text[]</tt></dt>
|
|
915 |
<dd><p>The error message (in UTF-8), or an empty string if a message is
|
|
916 |
not available.</p>
|
|
917 |
</dd></dl>
|
|
918 |
|
|
919 |
<dl class="member">
|
|
920 |
<dt>
|
|
921 |
<tt class="descname">char source[]</tt></dt>
|
|
922 |
<dd><p>Source of the error. This can be (a part of) the file name or a
|
|
923 |
special identifier in angle brackers (e.g. <tt class="docutils literal"><span class="pre"><string></span></tt>).</p>
|
|
924 |
</dd></dl>
|
|
925 |
|
|
926 |
<dl class="member">
|
|
927 |
<dt id="c.json_error_t.line">
|
|
928 |
int <tt class="descname">line</tt><a class="headerlink" href="#c.json_error_t.line" title="Permalink to this definition">¶</a></dt>
|
|
929 |
<dd><p>The line number on which the error occurred.</p>
|
|
930 |
</dd></dl>
|
|
931 |
|
|
932 |
<dl class="member">
|
|
933 |
<dt id="c.json_error_t.column">
|
|
934 |
int <tt class="descname">column</tt><a class="headerlink" href="#c.json_error_t.column" title="Permalink to this definition">¶</a></dt>
|
|
935 |
<dd><p>The column on which the error occurred. Note that this is the
|
|
936 |
<em>character column</em>, not the byte column, i.e. a multibyte UTF-8
|
|
937 |
character counts as one column.</p>
|
|
938 |
</dd></dl>
|
|
939 |
|
|
940 |
<dl class="member">
|
|
941 |
<dt id="c.json_error_t.position">
|
|
942 |
size_t <tt class="descname">position</tt><a class="headerlink" href="#c.json_error_t.position" title="Permalink to this definition">¶</a></dt>
|
|
943 |
<dd><p>The position in bytes from the start of the input. This is
|
|
944 |
useful for debugging Unicode encoding problems.</p>
|
|
945 |
</dd></dl>
|
|
946 |
|
|
947 |
</dd></dl>
|
|
948 |
|
|
949 |
<p>The normal use of <a class="reference internal" href="#c.json_error_t" title="json_error_t"><tt class="xref c c-type docutils literal"><span class="pre">json_error_t</span></tt></a> is to allocate it on the stack,
|
|
950 |
and pass a pointer to a function. Example:</p>
|
|
951 |
<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
|
|
952 |
<span class="kt">json_t</span> <span class="o">*</span><span class="n">json</span><span class="p">;</span>
|
|
953 |
<span class="kt">json_error_t</span> <span class="n">error</span><span class="p">;</span>
|
|
954 |
|
|
955 |
<span class="n">json</span> <span class="o">=</span> <span class="n">json_load_file</span><span class="p">(</span><span class="s">"/path/to/file.json"</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="o">&</span><span class="n">error</span><span class="p">);</span>
|
|
956 |
<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">json</span><span class="p">)</span> <span class="p">{</span>
|
|
957 |
<span class="cm">/* the error variable contains error information */</span>
|
|
958 |
<span class="p">}</span>
|
|
959 |
<span class="p">...</span>
|
|
960 |
<span class="p">}</span>
|
|
961 |
</pre></div>
|
|
962 |
</div>
|
|
963 |
<p>Also note that if the call succeeded (<tt class="docutils literal"><span class="pre">json</span> <span class="pre">!=</span> <span class="pre">NULL</span></tt> in the above
|
|
964 |
example), the contents of <tt class="docutils literal"><span class="pre">error</span></tt> are generally left unspecified.
|
|
965 |
The decoding functions write to the <tt class="docutils literal"><span class="pre">position</span></tt> member also on
|
|
966 |
success. See <a class="reference internal" href="#apiref-decoding"><em>Decoding</em></a> for more info.</p>
|
|
967 |
<p>All functions also accept <em>NULL</em> as the <a class="reference internal" href="#c.json_error_t" title="json_error_t"><tt class="xref c c-type docutils literal"><span class="pre">json_error_t</span></tt></a> pointer,
|
|
968 |
in which case no error information is returned to the caller.</p>
|
|
969 |
</div>
|
|
970 |
<div class="section" id="encoding">
|
|
971 |
<h2>Encoding<a class="headerlink" href="#encoding" title="Permalink to this headline">¶</a></h2>
|
|
972 |
<p>This sections describes the functions that can be used to encode
|
|
973 |
values to JSON. By default, only objects and arrays can be encoded
|
|
974 |
directly, since they are the only valid <em>root</em> values of a JSON text.
|
|
975 |
To encode any JSON value, use the <tt class="docutils literal"><span class="pre">JSON_ENCODE_ANY</span></tt> flag (see
|
|
976 |
below).</p>
|
|
977 |
<p>By default, the output has no newlines, and spaces are used between
|
|
978 |
array and object elements for a readable output. This behavior can be
|
|
979 |
altered by using the <tt class="docutils literal"><span class="pre">JSON_INDENT</span></tt> and <tt class="docutils literal"><span class="pre">JSON_COMPACT</span></tt> flags
|
|
980 |
described below. A newline is never appended to the end of the encoded
|
|
981 |
JSON data.</p>
|
|
982 |
<p>Each function takes a <em>flags</em> parameter that controls some aspects of
|
|
983 |
how the data is encoded. Its default value is 0. The following macros
|
|
984 |
can be ORed together to obtain <em>flags</em>.</p>
|
|
985 |
<dl class="docutils">
|
|
986 |
<dt><tt class="docutils literal"><span class="pre">JSON_INDENT(n)</span></tt></dt>
|
|
987 |
<dd><p class="first">Pretty-print the result, using newlines between array and object
|
|
988 |
items, and indenting with <em>n</em> spaces. The valid range for <em>n</em> is
|
|
989 |
between 0 and 31 (inclusive), other values result in an undefined
|
|
990 |
output. If <tt class="docutils literal"><span class="pre">JSON_INDENT</span></tt> is not used or <em>n</em> is 0, no newlines are
|
|
991 |
inserted between array and object items.</p>
|
|
992 |
<p>The <tt class="docutils literal"><span class="pre">JSON_MAX_INDENT</span></tt> constant defines the maximum indentation
|
|
993 |
that can be used, and its value is 31.</p>
|
|
994 |
<div class="last versionchanged">
|
|
995 |
<p><span class="versionmodified">Changed in version 2.7: </span>Added <tt class="docutils literal"><span class="pre">JSON_MAX_INDENT</span></tt>.</p>
|
|
996 |
</div>
|
|
997 |
</dd>
|
|
998 |
<dt><tt class="docutils literal"><span class="pre">JSON_COMPACT</span></tt></dt>
|
|
999 |
<dd>This flag enables a compact representation, i.e. sets the separator
|
|
1000 |
between array and object items to <tt class="docutils literal"><span class="pre">","</span></tt> and between object keys
|
|
1001 |
and values to <tt class="docutils literal"><span class="pre">":"</span></tt>. Without this flag, the corresponding
|
|
1002 |
separators are <tt class="docutils literal"><span class="pre">",</span> <span class="pre">"</span></tt> and <tt class="docutils literal"><span class="pre">":</span> <span class="pre">"</span></tt> for more readable output.</dd>
|
|
1003 |
<dt><tt class="docutils literal"><span class="pre">JSON_ENSURE_ASCII</span></tt></dt>
|
|
1004 |
<dd>If this flag is used, the output is guaranteed to consist only of
|
|
1005 |
ASCII characters. This is achived by escaping all Unicode
|
|
1006 |
characters outside the ASCII range.</dd>
|
|
1007 |
<dt><tt class="docutils literal"><span class="pre">JSON_SORT_KEYS</span></tt></dt>
|
|
1008 |
<dd>If this flag is used, all the objects in output are sorted by key.
|
|
1009 |
This is useful e.g. if two JSON texts are diffed or visually
|
|
1010 |
compared.</dd>
|
|
1011 |
<dt><tt class="docutils literal"><span class="pre">JSON_PRESERVE_ORDER</span></tt></dt>
|
|
1012 |
<dd>If this flag is used, object keys in the output are sorted into the
|
|
1013 |
same order in which they were first inserted to the object. For
|
|
1014 |
example, decoding a JSON text and then encoding with this flag
|
|
1015 |
preserves the order of object keys.</dd>
|
|
1016 |
<dt><tt class="docutils literal"><span class="pre">JSON_ENCODE_ANY</span></tt></dt>
|
|
1017 |
<dd><p class="first">Specifying this flag makes it possible to encode any JSON value on
|
|
1018 |
its own. Without it, only objects and arrays can be passed as the
|
|
1019 |
<em>root</em> value to the encoding functions.</p>
|
|
1020 |
<p><strong>Note:</strong> Encoding any value may be useful in some scenarios, but
|
|
1021 |
it’s generally discouraged as it violates strict compatiblity with
|
|
1022 |
<span class="target" id="index-1"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc4627.html"><strong>RFC 4627</strong></a>. If you use this flag, don’t expect interoperatibility
|
|
1023 |
with other JSON systems.</p>
|
|
1024 |
<div class="last versionadded">
|
|
1025 |
<p><span class="versionmodified">New in version 2.1.</span></p>
|
|
1026 |
</div>
|
|
1027 |
</dd>
|
|
1028 |
<dt><tt class="docutils literal"><span class="pre">JSON_ESCAPE_SLASH</span></tt></dt>
|
|
1029 |
<dd><p class="first">Escape the <tt class="docutils literal"><span class="pre">/</span></tt> characters in strings with <tt class="docutils literal"><span class="pre">\/</span></tt>.</p>
|
|
1030 |
<div class="last versionadded">
|
|
1031 |
<p><span class="versionmodified">New in version 2.4.</span></p>
|
|
1032 |
</div>
|
|
1033 |
</dd>
|
|
1034 |
<dt><tt class="docutils literal"><span class="pre">JSON_REAL_PRECISION(n)</span></tt></dt>
|
|
1035 |
<dd><p class="first">Output all real numbers with at most <em>n</em> digits of precision. The
|
|
1036 |
valid range for <em>n</em> is between 0 and 31 (inclusive), and other
|
|
1037 |
values result in an undefined behavior.</p>
|
|
1038 |
<p>By default, the precision is 17, to correctly and losslessly encode
|
|
1039 |
all IEEE 754 double precision floating point numbers.</p>
|
|
1040 |
<div class="last versionadded">
|
|
1041 |
<p><span class="versionmodified">New in version 2.7.</span></p>
|
|
1042 |
</div>
|
|
1043 |
</dd>
|
|
1044 |
</dl>
|
|
1045 |
<p>The following functions perform the actual JSON encoding. The result
|
|
1046 |
is in UTF-8.</p>
|
|
1047 |
<dl class="function">
|
|
1048 |
<dt id="c.json_dumps">
|
|
1049 |
char *<tt class="descname">json_dumps</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *root</em>, size_t<em> flags</em><big>)</big><a class="headerlink" href="#c.json_dumps" title="Permalink to this definition">¶</a></dt>
|
|
1050 |
<dd><p>Returns the JSON representation of <em>root</em> as a string, or <em>NULL</em> on
|
|
1051 |
error. <em>flags</em> is described above. The return value must be freed
|
|
1052 |
by the caller using <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt>.</p>
|
|
1053 |
</dd></dl>
|
|
1054 |
|
|
1055 |
<dl class="function">
|
|
1056 |
<dt id="c.json_dumpf">
|
|
1057 |
int <tt class="descname">json_dumpf</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *root</em>, FILE<em> *output</em>, size_t<em> flags</em><big>)</big><a class="headerlink" href="#c.json_dumpf" title="Permalink to this definition">¶</a></dt>
|
|
1058 |
<dd><p>Write the JSON representation of <em>root</em> to the stream <em>output</em>.
|
|
1059 |
<em>flags</em> is described above. Returns 0 on success and -1 on error.
|
|
1060 |
If an error occurs, something may have already been written to
|
|
1061 |
<em>output</em>. In this case, the output is undefined and most likely not
|
|
1062 |
valid JSON.</p>
|
|
1063 |
</dd></dl>
|
|
1064 |
|
|
1065 |
<dl class="function">
|
|
1066 |
<dt id="c.json_dump_file">
|
|
1067 |
int <tt class="descname">json_dump_file</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em>, const char<em> *path</em>, size_t<em> flags</em><big>)</big><a class="headerlink" href="#c.json_dump_file" title="Permalink to this definition">¶</a></dt>
|
|
1068 |
<dd><p>Write the JSON representation of <em>root</em> to the file <em>path</em>. If
|
|
1069 |
<em>path</em> already exists, it is overwritten. <em>flags</em> is described
|
|
1070 |
above. Returns 0 on success and -1 on error.</p>
|
|
1071 |
</dd></dl>
|
|
1072 |
|
|
1073 |
<dl class="type">
|
|
1074 |
<dt id="c.json_dump_callback_t">
|
|
1075 |
<tt class="descname">json_dump_callback_t</tt><a class="headerlink" href="#c.json_dump_callback_t" title="Permalink to this definition">¶</a></dt>
|
|
1076 |
<dd><p>A typedef for a function that’s called by
|
|
1077 |
<a class="reference internal" href="#c.json_dump_callback" title="json_dump_callback"><tt class="xref c c-func docutils literal"><span class="pre">json_dump_callback()</span></tt></a>:</p>
|
|
1078 |
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="kt">json_dump_callback_t</span><span class="p">)(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">data</span><span class="p">);</span>
|
|
1079 |
</pre></div>
|
|
1080 |
</div>
|
|
1081 |
<p><em>buffer</em> points to a buffer containing a chunk of output, <em>size</em> is
|
|
1082 |
the length of the buffer, and <em>data</em> is the corresponding
|
|
1083 |
<a class="reference internal" href="#c.json_dump_callback" title="json_dump_callback"><tt class="xref c c-func docutils literal"><span class="pre">json_dump_callback()</span></tt></a> argument passed through.</p>
|
|
1084 |
<p>On error, the function should return -1 to stop the encoding
|
|
1085 |
process. On success, it should return 0.</p>
|
|
1086 |
<div class="versionadded">
|
|
1087 |
<p><span class="versionmodified">New in version 2.2.</span></p>
|
|
1088 |
</div>
|
|
1089 |
</dd></dl>
|
|
1090 |
|
|
1091 |
<dl class="function">
|
|
1092 |
<dt id="c.json_dump_callback">
|
|
1093 |
int <tt class="descname">json_dump_callback</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *json</em>, <a class="reference internal" href="#c.json_dump_callback_t" title="json_dump_callback_t">json_dump_callback_t</a><em> callback</em>, void<em> *data</em>, size_t<em> flags</em><big>)</big><a class="headerlink" href="#c.json_dump_callback" title="Permalink to this definition">¶</a></dt>
|
|
1094 |
<dd><p>Call <em>callback</em> repeatedly, passing a chunk of the JSON
|
|
1095 |
representation of <em>root</em> each time. <em>flags</em> is described above.
|
|
1096 |
Returns 0 on success and -1 on error.</p>
|
|
1097 |
<div class="versionadded">
|
|
1098 |
<p><span class="versionmodified">New in version 2.2.</span></p>
|
|
1099 |
</div>
|
|
1100 |
</dd></dl>
|
|
1101 |
|
|
1102 |
</div>
|
|
1103 |
<div class="section" id="decoding">
|
|
1104 |
<span id="apiref-decoding"></span><h2>Decoding<a class="headerlink" href="#decoding" title="Permalink to this headline">¶</a></h2>
|
|
1105 |
<p>This sections describes the functions that can be used to decode JSON
|
|
1106 |
text to the Jansson representation of JSON data. The JSON
|
|
1107 |
specification requires that a JSON text is either a serialized array
|
|
1108 |
or object, and this requirement is also enforced with the following
|
|
1109 |
functions. In other words, the top level value in the JSON text being
|
|
1110 |
decoded must be either array or object. To decode any JSON value, use
|
|
1111 |
the <tt class="docutils literal"><span class="pre">JSON_DECODE_ANY</span></tt> flag (see below).</p>
|
|
1112 |
<p>See <a class="reference internal" href="conformance.html#rfc-conformance"><em>RFC Conformance</em></a> for a discussion on Jansson’s conformance
|
|
1113 |
to the JSON specification. It explains many design decisions that
|
|
1114 |
affect especially the behavior of the decoder.</p>
|
|
1115 |
<p>Each function takes a <em>flags</em> parameter that can be used to control
|
|
1116 |
the behavior of the decoder. Its default value is 0. The following
|
|
1117 |
macros can be ORed together to obtain <em>flags</em>.</p>
|
|
1118 |
<dl class="docutils">
|
|
1119 |
<dt><tt class="docutils literal"><span class="pre">JSON_REJECT_DUPLICATES</span></tt></dt>
|
|
1120 |
<dd><p class="first">Issue a decoding error if any JSON object in the input text
|
|
1121 |
contains duplicate keys. Without this flag, the value of the last
|
|
1122 |
occurence of each key ends up in the result. Key equivalence is
|
|
1123 |
checked byte-by-byte, without special Unicode comparison
|
|
1124 |
algorithms.</p>
|
|
1125 |
<div class="last versionadded">
|
|
1126 |
<p><span class="versionmodified">New in version 2.1.</span></p>
|
|
1127 |
</div>
|
|
1128 |
</dd>
|
|
1129 |
<dt><tt class="docutils literal"><span class="pre">JSON_DECODE_ANY</span></tt></dt>
|
|
1130 |
<dd><p class="first">By default, the decoder expects an array or object as the input.
|
|
1131 |
With this flag enabled, the decoder accepts any valid JSON value.</p>
|
|
1132 |
<p><strong>Note:</strong> Decoding any value may be useful in some scenarios, but
|
|
1133 |
it’s generally discouraged as it violates strict compatiblity with
|
|
1134 |
<span class="target" id="index-2"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc4627.html"><strong>RFC 4627</strong></a>. If you use this flag, don’t expect interoperatibility
|
|
1135 |
with other JSON systems.</p>
|
|
1136 |
<div class="last versionadded">
|
|
1137 |
<p><span class="versionmodified">New in version 2.3.</span></p>
|
|
1138 |
</div>
|
|
1139 |
</dd>
|
|
1140 |
<dt><tt class="docutils literal"><span class="pre">JSON_DISABLE_EOF_CHECK</span></tt></dt>
|
|
1141 |
<dd><p class="first">By default, the decoder expects that its whole input constitutes a
|
|
1142 |
valid JSON text, and issues an error if there’s extra data after
|
|
1143 |
the otherwise valid JSON input. With this flag enabled, the decoder
|
|
1144 |
stops after decoding a valid JSON array or object, and thus allows
|
|
1145 |
extra data after the JSON text.</p>
|
|
1146 |
<p>Normally, reading will stop when the last <tt class="docutils literal"><span class="pre">]</span></tt> or <tt class="docutils literal"><span class="pre">}</span></tt> in the
|
|
1147 |
JSON input is encountered. If both <tt class="docutils literal"><span class="pre">JSON_DISABLE_EOF_CHECK</span></tt> and
|
|
1148 |
<tt class="docutils literal"><span class="pre">JSON_DECODE_ANY</span></tt> flags are used, the decoder may read one extra
|
|
1149 |
UTF-8 code unit (up to 4 bytes of input). For example, decoding
|
|
1150 |
<tt class="docutils literal"><span class="pre">4true</span></tt> correctly decodes the integer 4, but also reads the
|
|
1151 |
<tt class="docutils literal"><span class="pre">t</span></tt>. For this reason, if reading multiple consecutive values that
|
|
1152 |
are not arrays or objects, they should be separated by at least one
|
|
1153 |
whitespace character.</p>
|
|
1154 |
<div class="last versionadded">
|
|
1155 |
<p><span class="versionmodified">New in version 2.1.</span></p>
|
|
1156 |
</div>
|
|
1157 |
</dd>
|
|
1158 |
<dt><tt class="docutils literal"><span class="pre">JSON_DECODE_INT_AS_REAL</span></tt></dt>
|
|
1159 |
<dd><p class="first">JSON defines only one number type. Jansson distinguishes between
|
|
1160 |
ints and reals. For more information see <a class="reference internal" href="conformance.html#real-vs-integer"><em>Real vs. Integer</em></a>.
|
|
1161 |
With this flag enabled the decoder interprets all numbers as real
|
|
1162 |
values. Integers that do not have an exact double representation
|
|
1163 |
will silently result in a loss of precision. Integers that cause
|
|
1164 |
a double overflow will cause an error.</p>
|
|
1165 |
<div class="last versionadded">
|
|
1166 |
<p><span class="versionmodified">New in version 2.5.</span></p>
|
|
1167 |
</div>
|
|
1168 |
</dd>
|
|
1169 |
<dt><tt class="docutils literal"><span class="pre">JSON_ALLOW_NUL</span></tt></dt>
|
|
1170 |
<dd><p class="first">Allow <tt class="docutils literal"><span class="pre">\u0000</span></tt> escape inside string values. This is a safety
|
|
1171 |
measure; If you know your input can contain NUL bytes, use this
|
|
1172 |
flag. If you don’t use this flag, you don’t have to worry about NUL
|
|
1173 |
bytes inside strings unless you explicitly create themselves by
|
|
1174 |
using e.g. <a class="reference internal" href="#c.json_stringn" title="json_stringn"><tt class="xref c c-func docutils literal"><span class="pre">json_stringn()</span></tt></a> or <tt class="docutils literal"><span class="pre">s#</span></tt> format specifier for
|
|
1175 |
<a class="reference internal" href="#c.json_pack" title="json_pack"><tt class="xref c c-func docutils literal"><span class="pre">json_pack()</span></tt></a>.</p>
|
|
1176 |
<p>Object keys cannot have embedded NUL bytes even if this flag is
|
|
1177 |
used.</p>
|
|
1178 |
<div class="last versionadded">
|
|
1179 |
<p><span class="versionmodified">New in version 2.6.</span></p>
|
|
1180 |
</div>
|
|
1181 |
</dd>
|
|
1182 |
</dl>
|
|
1183 |
<p>Each function also takes an optional <a class="reference internal" href="#c.json_error_t" title="json_error_t"><tt class="xref c c-type docutils literal"><span class="pre">json_error_t</span></tt></a> parameter
|
|
1184 |
that is filled with error information if decoding fails. It’s also
|
|
1185 |
updated on success; the number of bytes of input read is written to
|
|
1186 |
its <tt class="docutils literal"><span class="pre">position</span></tt> field. This is especially useful when using
|
|
1187 |
<tt class="docutils literal"><span class="pre">JSON_DISABLE_EOF_CHECK</span></tt> to read multiple consecutive JSON texts.</p>
|
|
1188 |
<div class="versionadded">
|
|
1189 |
<p><span class="versionmodified">New in version 2.3: </span>Number of bytes of input read is written to the <tt class="docutils literal"><span class="pre">position</span></tt> field
|
|
1190 |
of the <a class="reference internal" href="#c.json_error_t" title="json_error_t"><tt class="xref c c-type docutils literal"><span class="pre">json_error_t</span></tt></a> structure.</p>
|
|
1191 |
</div>
|
|
1192 |
<p>If no error or position information is needed, you can pass <em>NULL</em>.</p>
|
|
1193 |
<p>The following functions perform the actual JSON decoding.</p>
|
|
1194 |
<dl class="function">
|
|
1195 |
<dt id="c.json_loads">
|
|
1196 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_loads</tt><big>(</big>const char<em> *input</em>, size_t<em> flags</em>, <a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em><big>)</big><a class="headerlink" href="#c.json_loads" title="Permalink to this definition">¶</a></dt>
|
|
1197 |
<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON string <em>input</em> and returns the array or object it
|
|
1198 |
contains, or <em>NULL</em> on error, in which case <em>error</em> is filled with
|
|
1199 |
information about the error. <em>flags</em> is described above.</p>
|
|
1200 |
</dd></dl>
|
|
1201 |
|
|
1202 |
<dl class="function">
|
|
1203 |
<dt id="c.json_loadb">
|
|
1204 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_loadb</tt><big>(</big>const char<em> *buffer</em>, size_t<em> buflen</em>, size_t<em> flags</em>, <a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em><big>)</big><a class="headerlink" href="#c.json_loadb" title="Permalink to this definition">¶</a></dt>
|
|
1205 |
<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON string <em>buffer</em>, whose length is <em>buflen</em>, and
|
|
1206 |
returns the array or object it contains, or <em>NULL</em> on error, in
|
|
1207 |
which case <em>error</em> is filled with information about the error. This
|
|
1208 |
is similar to <a class="reference internal" href="#c.json_loads" title="json_loads"><tt class="xref c c-func docutils literal"><span class="pre">json_loads()</span></tt></a> except that the string doesn’t
|
|
1209 |
need to be null-terminated. <em>flags</em> is described above.</p>
|
|
1210 |
<div class="versionadded">
|
|
1211 |
<p><span class="versionmodified">New in version 2.1.</span></p>
|
|
1212 |
</div>
|
|
1213 |
</dd></dl>
|
|
1214 |
|
|
1215 |
<dl class="function">
|
|
1216 |
<dt id="c.json_loadf">
|
|
1217 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_loadf</tt><big>(</big>FILE<em> *input</em>, size_t<em> flags</em>, <a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em><big>)</big><a class="headerlink" href="#c.json_loadf" title="Permalink to this definition">¶</a></dt>
|
|
1218 |
<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON text in stream <em>input</em> and returns the array or
|
|
1219 |
object it contains, or <em>NULL</em> on error, in which case <em>error</em> is
|
|
1220 |
filled with information about the error. <em>flags</em> is described
|
|
1221 |
above.</p>
|
|
1222 |
<p>This function will start reading the input from whatever position
|
|
1223 |
the input file was, without attempting to seek first. If an error
|
|
1224 |
occurs, the file position will be left indeterminate. On success,
|
|
1225 |
the file position will be at EOF, unless <tt class="docutils literal"><span class="pre">JSON_DISABLE_EOF_CHECK</span></tt>
|
|
1226 |
flag was used. In this case, the file position will be at the first
|
|
1227 |
character after the last <tt class="docutils literal"><span class="pre">]</span></tt> or <tt class="docutils literal"><span class="pre">}</span></tt> in the JSON input. This
|
|
1228 |
allows calling <a class="reference internal" href="#c.json_loadf" title="json_loadf"><tt class="xref c c-func docutils literal"><span class="pre">json_loadf()</span></tt></a> on the same <tt class="docutils literal"><span class="pre">FILE</span></tt> object
|
|
1229 |
multiple times, if the input consists of consecutive JSON texts,
|
|
1230 |
possibly separated by whitespace.</p>
|
|
1231 |
</dd></dl>
|
|
1232 |
|
|
1233 |
<dl class="function">
|
|
1234 |
<dt id="c.json_load_file">
|
|
1235 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_load_file</tt><big>(</big>const char<em> *path</em>, size_t<em> flags</em>, <a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em><big>)</big><a class="headerlink" href="#c.json_load_file" title="Permalink to this definition">¶</a></dt>
|
|
1236 |
<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON text in file <em>path</em> and returns the array or
|
|
1237 |
object it contains, or <em>NULL</em> on error, in which case <em>error</em> is
|
|
1238 |
filled with information about the error. <em>flags</em> is described
|
|
1239 |
above.</p>
|
|
1240 |
</dd></dl>
|
|
1241 |
|
|
1242 |
<dl class="type">
|
|
1243 |
<dt id="c.json_load_callback_t">
|
|
1244 |
<tt class="descname">json_load_callback_t</tt><a class="headerlink" href="#c.json_load_callback_t" title="Permalink to this definition">¶</a></dt>
|
|
1245 |
<dd><p>A typedef for a function that’s called by
|
|
1246 |
<a class="reference internal" href="#c.json_load_callback" title="json_load_callback"><tt class="xref c c-func docutils literal"><span class="pre">json_load_callback()</span></tt></a> to read a chunk of input data:</p>
|
|
1247 |
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">size_t</span> <span class="p">(</span><span class="o">*</span><span class="kt">json_load_callback_t</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">buflen</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">data</span><span class="p">);</span>
|
|
1248 |
</pre></div>
|
|
1249 |
</div>
|
|
1250 |
<p><em>buffer</em> points to a buffer of <em>buflen</em> bytes, and <em>data</em> is the
|
|
1251 |
corresponding <a class="reference internal" href="#c.json_load_callback" title="json_load_callback"><tt class="xref c c-func docutils literal"><span class="pre">json_load_callback()</span></tt></a> argument passed through.</p>
|
|
1252 |
<p>On success, the function should return the number of bytes read; a
|
|
1253 |
returned value of 0 indicates that no data was read and that the
|
|
1254 |
end of file has been reached. On error, the function should return
|
|
1255 |
<tt class="docutils literal"><span class="pre">(size_t)-1</span></tt> to abort the decoding process.</p>
|
|
1256 |
<div class="versionadded">
|
|
1257 |
<p><span class="versionmodified">New in version 2.4.</span></p>
|
|
1258 |
</div>
|
|
1259 |
</dd></dl>
|
|
1260 |
|
|
1261 |
<dl class="function">
|
|
1262 |
<dt id="c.json_load_callback">
|
|
1263 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_load_callback</tt><big>(</big><a class="reference internal" href="#c.json_load_callback_t" title="json_load_callback_t">json_load_callback_t</a><em> callback</em>, void<em> *data</em>, size_t<em> flags</em>, <a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em><big>)</big><a class="headerlink" href="#c.json_load_callback" title="Permalink to this definition">¶</a></dt>
|
|
1264 |
<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON text produced by repeated calls to <em>callback</em>, and
|
|
1265 |
returns the array or object it contains, or <em>NULL</em> on error, in
|
|
1266 |
which case <em>error</em> is filled with information about the error.
|
|
1267 |
<em>data</em> is passed through to <em>callback</em> on each call. <em>flags</em> is
|
|
1268 |
described above.</p>
|
|
1269 |
<div class="versionadded">
|
|
1270 |
<p><span class="versionmodified">New in version 2.4.</span></p>
|
|
1271 |
</div>
|
|
1272 |
</dd></dl>
|
|
1273 |
|
|
1274 |
</div>
|
|
1275 |
<div class="section" id="building-values">
|
|
1276 |
<span id="apiref-pack"></span><h2>Building Values<a class="headerlink" href="#building-values" title="Permalink to this headline">¶</a></h2>
|
|
1277 |
<p>This section describes functions that help to create, or <em>pack</em>,
|
|
1278 |
complex JSON values, especially nested objects and arrays. Value
|
|
1279 |
building is based on a <em>format string</em> that is used to tell the
|
|
1280 |
functions about the expected arguments.</p>
|
|
1281 |
<p>For example, the format string <tt class="docutils literal"><span class="pre">"i"</span></tt> specifies a single integer
|
|
1282 |
value, while the format string <tt class="docutils literal"><span class="pre">"[ssb]"</span></tt> or the equivalent <tt class="docutils literal"><span class="pre">"[s,</span> <span class="pre">s,</span>
|
|
1283 |
<span class="pre">b]"</span></tt> specifies an array value with two strings and a boolean as its
|
|
1284 |
items:</p>
|
|
1285 |
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Create the JSON integer 42 */</span>
|
|
1286 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"i"</span><span class="p">,</span> <span class="mi">42</span><span class="p">);</span>
|
|
1287 |
|
|
1288 |
<span class="cm">/* Create the JSON array ["foo", "bar", true] */</span>
|
|
1289 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"[ssb]"</span><span class="p">,</span> <span class="s">"foo"</span><span class="p">,</span> <span class="s">"bar"</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>
|
|
1290 |
</pre></div>
|
|
1291 |
</div>
|
|
1292 |
<p>Here’s the full list of format specifiers. The type in parentheses
|
|
1293 |
denotes the resulting JSON type, and the type in brackets (if any)
|
|
1294 |
denotes the C type that is expected as the corresponding argument or
|
|
1295 |
arguments.</p>
|
|
1296 |
<dl class="docutils">
|
|
1297 |
<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string) [const char *]</dt>
|
|
1298 |
<dd>Convert a NULL terminated UTF-8 string to a JSON string.</dd>
|
|
1299 |
<dt><tt class="docutils literal"><span class="pre">s#</span></tt> (string) [const char *, int]</dt>
|
|
1300 |
<dd><p class="first">Convert a UTF-8 buffer of a given length to a JSON string.</p>
|
|
1301 |
<div class="last versionadded">
|
|
1302 |
<p><span class="versionmodified">New in version 2.5.</span></p>
|
|
1303 |
</div>
|
|
1304 |
</dd>
|
|
1305 |
<dt><tt class="docutils literal"><span class="pre">s%</span></tt> (string) [const char *, size_t]</dt>
|
|
1306 |
<dd><p class="first">Like <tt class="docutils literal"><span class="pre">s#</span></tt> but the length argument is of type <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>.</p>
|
|
1307 |
<div class="last versionadded">
|
|
1308 |
<p><span class="versionmodified">New in version 2.6.</span></p>
|
|
1309 |
</div>
|
|
1310 |
</dd>
|
|
1311 |
<dt><tt class="docutils literal"><span class="pre">+</span></tt> [const char *]</dt>
|
|
1312 |
<dd><p class="first">Like <tt class="docutils literal"><span class="pre">s</span></tt>, but concatenate to the previous string. Only valid
|
|
1313 |
after <tt class="docutils literal"><span class="pre">s</span></tt>, <tt class="docutils literal"><span class="pre">s#</span></tt>, <tt class="docutils literal"><span class="pre">+</span></tt> or <tt class="docutils literal"><span class="pre">+#</span></tt>.</p>
|
|
1314 |
<div class="last versionadded">
|
|
1315 |
<p><span class="versionmodified">New in version 2.5.</span></p>
|
|
1316 |
</div>
|
|
1317 |
</dd>
|
|
1318 |
<dt><tt class="docutils literal"><span class="pre">+#</span></tt> [const char *, int]</dt>
|
|
1319 |
<dd><p class="first">Like <tt class="docutils literal"><span class="pre">s#</span></tt>, but concatenate to the previous string. Only valid
|
|
1320 |
after <tt class="docutils literal"><span class="pre">s</span></tt>, <tt class="docutils literal"><span class="pre">s#</span></tt>, <tt class="docutils literal"><span class="pre">+</span></tt> or <tt class="docutils literal"><span class="pre">+#</span></tt>.</p>
|
|
1321 |
<div class="last versionadded">
|
|
1322 |
<p><span class="versionmodified">New in version 2.5.</span></p>
|
|
1323 |
</div>
|
|
1324 |
</dd>
|
|
1325 |
<dt><tt class="docutils literal"><span class="pre">+%</span></tt> (string) [const char *, size_t]</dt>
|
|
1326 |
<dd><p class="first">Like <tt class="docutils literal"><span class="pre">+#</span></tt> but the length argument is of type <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>.</p>
|
|
1327 |
<div class="last versionadded">
|
|
1328 |
<p><span class="versionmodified">New in version 2.6.</span></p>
|
|
1329 |
</div>
|
|
1330 |
</dd>
|
|
1331 |
<dt><tt class="docutils literal"><span class="pre">n</span></tt> (null)</dt>
|
|
1332 |
<dd>Output a JSON null value. No argument is consumed.</dd>
|
|
1333 |
<dt><tt class="docutils literal"><span class="pre">b</span></tt> (boolean) [int]</dt>
|
|
1334 |
<dd>Convert a C <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> to JSON boolean value. Zero is converted
|
|
1335 |
to <tt class="docutils literal"><span class="pre">false</span></tt> and non-zero to <tt class="docutils literal"><span class="pre">true</span></tt>.</dd>
|
|
1336 |
<dt><tt class="docutils literal"><span class="pre">i</span></tt> (integer) [int]</dt>
|
|
1337 |
<dd>Convert a C <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> to JSON integer.</dd>
|
|
1338 |
<dt><tt class="docutils literal"><span class="pre">I</span></tt> (integer) [json_int_t]</dt>
|
|
1339 |
<dd>Convert a C <a class="reference internal" href="#c.json_int_t" title="json_int_t"><tt class="xref c c-type docutils literal"><span class="pre">json_int_t</span></tt></a> to JSON integer.</dd>
|
|
1340 |
<dt><tt class="docutils literal"><span class="pre">f</span></tt> (real) [double]</dt>
|
|
1341 |
<dd>Convert a C <tt class="xref c c-type docutils literal"><span class="pre">double</span></tt> to JSON real.</dd>
|
|
1342 |
<dt><tt class="docutils literal"><span class="pre">o</span></tt> (any value) [json_t *]</dt>
|
|
1343 |
<dd>Output any given JSON value as-is. If the value is added to an
|
|
1344 |
array or object, the reference to the value passed to <tt class="docutils literal"><span class="pre">o</span></tt> is
|
|
1345 |
stolen by the container.</dd>
|
|
1346 |
<dt><tt class="docutils literal"><span class="pre">O</span></tt> (any value) [json_t *]</dt>
|
|
1347 |
<dd>Like <tt class="docutils literal"><span class="pre">o</span></tt>, but the argument’s reference count is incremented.
|
|
1348 |
This is useful if you pack into an array or object and want to
|
|
1349 |
keep the reference for the JSON value consumed by <tt class="docutils literal"><span class="pre">O</span></tt> to
|
|
1350 |
yourself.</dd>
|
|
1351 |
<dt><tt class="docutils literal"><span class="pre">[fmt]</span></tt> (array)</dt>
|
|
1352 |
<dd>Build an array with contents from the inner format string. <tt class="docutils literal"><span class="pre">fmt</span></tt>
|
|
1353 |
may contain objects and arrays, i.e. recursive value building is
|
|
1354 |
supported.</dd>
|
|
1355 |
<dt><tt class="docutils literal"><span class="pre">{fmt}</span></tt> (object)</dt>
|
|
1356 |
<dd>Build an object with contents from the inner format string
|
|
1357 |
<tt class="docutils literal"><span class="pre">fmt</span></tt>. The first, third, etc. format specifier represent a key,
|
|
1358 |
and must be a string (see <tt class="docutils literal"><span class="pre">s</span></tt>, <tt class="docutils literal"><span class="pre">s#</span></tt>, <tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">+#</span></tt> above),
|
|
1359 |
as object keys are always strings. The second, fourth, etc. format
|
|
1360 |
specifier represent a value. Any value may be an object or array,
|
|
1361 |
i.e. recursive value building is supported.</dd>
|
|
1362 |
</dl>
|
|
1363 |
<p>Whitespace, <tt class="docutils literal"><span class="pre">:</span></tt> and <tt class="docutils literal"><span class="pre">,</span></tt> are ignored.</p>
|
|
1364 |
<p>The following functions compose the value building API:</p>
|
|
1365 |
<dl class="function">
|
|
1366 |
<dt id="c.json_pack">
|
|
1367 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_pack</tt><big>(</big>const char<em> *fmt</em>, ...<big>)</big><a class="headerlink" href="#c.json_pack" title="Permalink to this definition">¶</a></dt>
|
|
1368 |
<dd><em class="refcount">Return value: New reference.</em><p>Build a new JSON value according to the format string <em>fmt</em>. For
|
|
1369 |
each format specifier (except for <tt class="docutils literal"><span class="pre">{}[]n</span></tt>), one or more arguments
|
|
1370 |
are consumed and used to build the corresponding value. Returns
|
|
1371 |
<em>NULL</em> on error.</p>
|
|
1372 |
</dd></dl>
|
|
1373 |
|
|
1374 |
<dl class="function">
|
|
1375 |
<dt id="c.json_pack_ex">
|
|
1376 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_pack_ex</tt><big>(</big><a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em>, size_t<em> flags</em>, const char<em> *fmt</em>, ...<big>)</big><a class="headerlink" href="#c.json_pack_ex" title="Permalink to this definition">¶</a></dt>
|
|
1377 |
<dt id="c.json_vpack_ex">
|
|
1378 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_vpack_ex</tt><big>(</big><a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em>, size_t<em> flags</em>, const char<em> *fmt</em>, va_list<em> ap</em><big>)</big><a class="headerlink" href="#c.json_vpack_ex" title="Permalink to this definition">¶</a></dt>
|
|
1379 |
<dd><em class="refcount">Return value: New reference.</em><p>Like <a class="reference internal" href="#c.json_pack" title="json_pack"><tt class="xref c c-func docutils literal"><span class="pre">json_pack()</span></tt></a>, but an in the case of an error, an error
|
|
1380 |
message is written to <em>error</em>, if it’s not <em>NULL</em>. The <em>flags</em>
|
|
1381 |
parameter is currently unused and should be set to 0.</p>
|
|
1382 |
<p>As only the errors in format string (and out-of-memory errors) can
|
|
1383 |
be caught by the packer, these two functions are most likely only
|
|
1384 |
useful for debugging format strings.</p>
|
|
1385 |
</dd></dl>
|
|
1386 |
|
|
1387 |
<p>More examples:</p>
|
|
1388 |
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Build an empty JSON object */</span>
|
|
1389 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"{}"</span><span class="p">);</span>
|
|
1390 |
|
|
1391 |
<span class="cm">/* Build the JSON object {"foo": 42, "bar": 7} */</span>
|
|
1392 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"{sisi}"</span><span class="p">,</span> <span class="s">"foo"</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="s">"bar"</span><span class="p">,</span> <span class="mi">7</span><span class="p">);</span>
|
|
1393 |
|
|
1394 |
<span class="cm">/* Like above, ':', ',' and whitespace are ignored */</span>
|
|
1395 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"{s:i, s:i}"</span><span class="p">,</span> <span class="s">"foo"</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="s">"bar"</span><span class="p">,</span> <span class="mi">7</span><span class="p">);</span>
|
|
1396 |
|
|
1397 |
<span class="cm">/* Build the JSON array [[1, 2], {"cool": true}] */</span>
|
|
1398 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"[[i,i],{s:b}]"</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s">"cool"</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>
|
|
1399 |
|
|
1400 |
<span class="cm">/* Build a string from a non-NUL terminated buffer */</span>
|
|
1401 |
<span class="kt">char</span> <span class="n">buffer</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="sc">'t'</span><span class="p">,</span> <span class="sc">'e'</span><span class="p">,</span> <span class="sc">'s'</span><span class="p">,</span> <span class="sc">'t'</span><span class="p">};</span>
|
|
1402 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"s#"</span><span class="p">,</span> <span class="n">buffer</span><span class="p">,</span> <span class="mi">4</span><span class="p">);</span>
|
|
1403 |
|
|
1404 |
<span class="cm">/* Concatentate strings together to build the JSON string "foobarbaz" */</span>
|
|
1405 |
<span class="n">json_pack</span><span class="p">(</span><span class="s">"s++"</span><span class="p">,</span> <span class="s">"foo"</span><span class="p">,</span> <span class="s">"bar"</span><span class="p">,</span> <span class="s">"baz"</span><span class="p">);</span>
|
|
1406 |
</pre></div>
|
|
1407 |
</div>
|
|
1408 |
</div>
|
|
1409 |
<div class="section" id="parsing-and-validating-values">
|
|
1410 |
<span id="apiref-unpack"></span><h2>Parsing and Validating Values<a class="headerlink" href="#parsing-and-validating-values" title="Permalink to this headline">¶</a></h2>
|
|
1411 |
<p>This section describes functions that help to validate complex values
|
|
1412 |
and extract, or <em>unpack</em>, data from them. Like <a class="reference internal" href="#apiref-pack"><em>building values</em></a>, this is also based on format strings.</p>
|
|
1413 |
<p>While a JSON value is unpacked, the type specified in the format
|
|
1414 |
string is checked to match that of the JSON value. This is the
|
|
1415 |
validation part of the process. In addition to this, the unpacking
|
|
1416 |
functions can also check that all items of arrays and objects are
|
|
1417 |
unpacked. This check be enabled with the format specifier <tt class="docutils literal"><span class="pre">!</span></tt> or by
|
|
1418 |
using the flag <tt class="docutils literal"><span class="pre">JSON_STRICT</span></tt>. See below for details.</p>
|
|
1419 |
<p>Here’s the full list of format specifiers. The type in parentheses
|
|
1420 |
denotes the JSON type, and the type in brackets (if any) denotes the C
|
|
1421 |
type whose address should be passed.</p>
|
|
1422 |
<dl class="docutils">
|
|
1423 |
<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string) [const char *]</dt>
|
|
1424 |
<dd>Convert a JSON string to a pointer to a NULL terminated UTF-8
|
|
1425 |
string. The resulting string is extracted by using
|
|
1426 |
<a class="reference internal" href="#c.json_string_value" title="json_string_value"><tt class="xref c c-func docutils literal"><span class="pre">json_string_value()</span></tt></a> internally, so it exists as long as
|
|
1427 |
there are still references to the corresponding JSON string.</dd>
|
|
1428 |
<dt><tt class="docutils literal"><span class="pre">s%</span></tt> (string) [const char *, size_t *]</dt>
|
|
1429 |
<dd><p class="first">Convert a JSON string to a pointer to a NULL terminated UTF-8
|
|
1430 |
string and its length.</p>
|
|
1431 |
<div class="last versionadded">
|
|
1432 |
<p><span class="versionmodified">New in version 2.6.</span></p>
|
|
1433 |
</div>
|
|
1434 |
</dd>
|
|
1435 |
<dt><tt class="docutils literal"><span class="pre">n</span></tt> (null)</dt>
|
|
1436 |
<dd>Expect a JSON null value. Nothing is extracted.</dd>
|
|
1437 |
<dt><tt class="docutils literal"><span class="pre">b</span></tt> (boolean) [int]</dt>
|
|
1438 |
<dd>Convert a JSON boolean value to a C <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt>, so that <tt class="docutils literal"><span class="pre">true</span></tt>
|
|
1439 |
is converted to 1 and <tt class="docutils literal"><span class="pre">false</span></tt> to 0.</dd>
|
|
1440 |
<dt><tt class="docutils literal"><span class="pre">i</span></tt> (integer) [int]</dt>
|
|
1441 |
<dd>Convert a JSON integer to C <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt>.</dd>
|
|
1442 |
<dt><tt class="docutils literal"><span class="pre">I</span></tt> (integer) [json_int_t]</dt>
|
|
1443 |
<dd>Convert a JSON integer to C <a class="reference internal" href="#c.json_int_t" title="json_int_t"><tt class="xref c c-type docutils literal"><span class="pre">json_int_t</span></tt></a>.</dd>
|
|
1444 |
<dt><tt class="docutils literal"><span class="pre">f</span></tt> (real) [double]</dt>
|
|
1445 |
<dd>Convert a JSON real to C <tt class="xref c c-type docutils literal"><span class="pre">double</span></tt>.</dd>
|
|
1446 |
<dt><tt class="docutils literal"><span class="pre">F</span></tt> (integer or real) [double]</dt>
|
|
1447 |
<dd>Convert a JSON number (integer or real) to C <tt class="xref c c-type docutils literal"><span class="pre">double</span></tt>.</dd>
|
|
1448 |
<dt><tt class="docutils literal"><span class="pre">o</span></tt> (any value) [json_t *]</dt>
|
|
1449 |
<dd>Store a JSON value with no conversion to a <a class="reference internal" href="#c.json_t" title="json_t"><tt class="xref c c-type docutils literal"><span class="pre">json_t</span></tt></a> pointer.</dd>
|
|
1450 |
<dt><tt class="docutils literal"><span class="pre">O</span></tt> (any value) [json_t *]</dt>
|
|
1451 |
<dd>Like <tt class="docutils literal"><span class="pre">O</span></tt>, but the JSON value’s reference count is incremented.</dd>
|
|
1452 |
<dt><tt class="docutils literal"><span class="pre">[fmt]</span></tt> (array)</dt>
|
|
1453 |
<dd>Convert each item in the JSON array according to the inner format
|
|
1454 |
string. <tt class="docutils literal"><span class="pre">fmt</span></tt> may contain objects and arrays, i.e. recursive
|
|
1455 |
value extraction is supporetd.</dd>
|
|
1456 |
<dt><tt class="docutils literal"><span class="pre">{fmt}</span></tt> (object)</dt>
|
|
1457 |
<dd><p class="first">Convert each item in the JSON object according to the inner format
|
|
1458 |
string <tt class="docutils literal"><span class="pre">fmt</span></tt>. The first, third, etc. format specifier represent
|
|
1459 |
a key, and must be <tt class="docutils literal"><span class="pre">s</span></tt>. The corresponding argument to unpack
|
|
1460 |
functions is read as the object key. The second fourth, etc.
|
|
1461 |
format specifier represent a value and is written to the address
|
|
1462 |
given as the corresponding argument. <strong>Note</strong> that every other
|
|
1463 |
argument is read from and every other is written to.</p>
|
|
1464 |
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> may contain objects and arrays as values, i.e. recursive
|
|
1465 |
value extraction is supporetd.</p>
|
|
1466 |
<div class="last versionadded">
|
|
1467 |
<p><span class="versionmodified">New in version 2.3: </span>Any <tt class="docutils literal"><span class="pre">s</span></tt> representing a key may be suffixed with a <tt class="docutils literal"><span class="pre">?</span></tt> to
|
|
1468 |
make the key optional. If the key is not found, nothing is
|
|
1469 |
extracted. See below for an example.</p>
|
|
1470 |
</div>
|
|
1471 |
</dd>
|
|
1472 |
<dt><tt class="docutils literal"><span class="pre">!</span></tt></dt>
|
|
1473 |
<dd>This special format specifier is used to enable the check that
|
|
1474 |
all object and array items are accessed, on a per-value basis. It
|
|
1475 |
must appear inside an array or object as the last format specifier
|
|
1476 |
before the closing bracket or brace. To enable the check globally,
|
|
1477 |
use the <tt class="docutils literal"><span class="pre">JSON_STRICT</span></tt> unpacking flag.</dd>
|
|
1478 |
<dt><tt class="docutils literal"><span class="pre">*</span></tt></dt>
|
|
1479 |
<dd>This special format specifier is the opposite of <tt class="docutils literal"><span class="pre">!</span></tt>. If the
|
|
1480 |
<tt class="docutils literal"><span class="pre">JSON_STRICT</span></tt> flag is used, <tt class="docutils literal"><span class="pre">*</span></tt> can be used to disable the
|
|
1481 |
strict check on a per-value basis. It must appear inside an array
|
|
1482 |
or object as the last format specifier before the closing bracket
|
|
1483 |
or brace.</dd>
|
|
1484 |
</dl>
|
|
1485 |
<p>Whitespace, <tt class="docutils literal"><span class="pre">:</span></tt> and <tt class="docutils literal"><span class="pre">,</span></tt> are ignored.</p>
|
|
1486 |
<p>The following functions compose the parsing and validation API:</p>
|
|
1487 |
<dl class="function">
|
|
1488 |
<dt id="c.json_unpack">
|
|
1489 |
int <tt class="descname">json_unpack</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *root</em>, const char<em> *fmt</em>, ...<big>)</big><a class="headerlink" href="#c.json_unpack" title="Permalink to this definition">¶</a></dt>
|
|
1490 |
<dd><p>Validate and unpack the JSON value <em>root</em> according to the format
|
|
1491 |
string <em>fmt</em>. Returns 0 on success and -1 on failure.</p>
|
|
1492 |
</dd></dl>
|
|
1493 |
|
|
1494 |
<dl class="function">
|
|
1495 |
<dt id="c.json_unpack_ex">
|
|
1496 |
int <tt class="descname">json_unpack_ex</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *root</em>, <a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em>, size_t<em> flags</em>, const char<em> *fmt</em>, ...<big>)</big><a class="headerlink" href="#c.json_unpack_ex" title="Permalink to this definition">¶</a></dt>
|
|
1497 |
<dt id="c.json_vunpack_ex">
|
|
1498 |
int <tt class="descname">json_vunpack_ex</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *root</em>, <a class="reference internal" href="#c.json_error_t" title="json_error_t">json_error_t</a><em> *error</em>, size_t<em> flags</em>, const char<em> *fmt</em>, va_list<em> ap</em><big>)</big><a class="headerlink" href="#c.json_vunpack_ex" title="Permalink to this definition">¶</a></dt>
|
|
1499 |
<dd><p>Validate and unpack the JSON value <em>root</em> according to the format
|
|
1500 |
string <em>fmt</em>. If an error occurs and <em>error</em> is not <em>NULL</em>, write
|
|
1501 |
error information to <em>error</em>. <em>flags</em> can be used to control the
|
|
1502 |
behaviour of the unpacker, see below for the flags. Returns 0 on
|
|
1503 |
success and -1 on failure.</p>
|
|
1504 |
</dd></dl>
|
|
1505 |
|
|
1506 |
<div class="admonition note">
|
|
1507 |
<p class="first admonition-title">Note</p>
|
|
1508 |
<p>The first argument of all unpack functions is <tt class="docutils literal"><span class="pre">json_t</span> <span class="pre">*root</span></tt>
|
|
1509 |
instead of <tt class="docutils literal"><span class="pre">const</span> <span class="pre">json_t</span> <span class="pre">*root</span></tt>, because the use of <tt class="docutils literal"><span class="pre">O</span></tt> format
|
|
1510 |
specifier causes the reference count of <tt class="docutils literal"><span class="pre">root</span></tt>, or some value
|
|
1511 |
reachable from <tt class="docutils literal"><span class="pre">root</span></tt>, to be increased. Furthermore, the <tt class="docutils literal"><span class="pre">o</span></tt>
|
|
1512 |
format specifier may be used to extract a value as-is, which allows
|
|
1513 |
modifying the structure or contents of a value reachable from
|
|
1514 |
<tt class="docutils literal"><span class="pre">root</span></tt>.</p>
|
|
1515 |
<p class="last">If the <tt class="docutils literal"><span class="pre">O</span></tt> and <tt class="docutils literal"><span class="pre">o</span></tt> format specifiers are not used, it’s
|
|
1516 |
perfectly safe to cast a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">json_t</span> <span class="pre">*</span></tt> variable to plain
|
|
1517 |
<tt class="docutils literal"><span class="pre">json_t</span> <span class="pre">*</span></tt> when used with these functions.</p>
|
|
1518 |
</div>
|
|
1519 |
<p>The following unpacking flags are available:</p>
|
|
1520 |
<dl class="docutils">
|
|
1521 |
<dt><tt class="docutils literal"><span class="pre">JSON_STRICT</span></tt></dt>
|
|
1522 |
<dd>Enable the extra validation step checking that all object and
|
|
1523 |
array items are unpacked. This is equivalent to appending the
|
|
1524 |
format specifier <tt class="docutils literal"><span class="pre">!</span></tt> to the end of every array and object in the
|
|
1525 |
format string.</dd>
|
|
1526 |
<dt><tt class="docutils literal"><span class="pre">JSON_VALIDATE_ONLY</span></tt></dt>
|
|
1527 |
<dd>Don’t extract any data, just validate the JSON value against the
|
|
1528 |
given format string. Note that object keys must still be specified
|
|
1529 |
after the format string.</dd>
|
|
1530 |
</dl>
|
|
1531 |
<p>Examples:</p>
|
|
1532 |
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* root is the JSON integer 42 */</span>
|
|
1533 |
<span class="kt">int</span> <span class="n">myint</span><span class="p">;</span>
|
|
1534 |
<span class="n">json_unpack</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"i"</span><span class="p">,</span> <span class="o">&</span><span class="n">myint</span><span class="p">);</span>
|
|
1535 |
<span class="n">assert</span><span class="p">(</span><span class="n">myint</span> <span class="o">==</span> <span class="mi">42</span><span class="p">);</span>
|
|
1536 |
|
|
1537 |
<span class="cm">/* root is the JSON object {"foo": "bar", "quux": true} */</span>
|
|
1538 |
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">str</span><span class="p">;</span>
|
|
1539 |
<span class="kt">int</span> <span class="n">boolean</span><span class="p">;</span>
|
|
1540 |
<span class="n">json_unpack</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{s:s, s:b}"</span><span class="p">,</span> <span class="s">"foo"</span><span class="p">,</span> <span class="o">&</span><span class="n">str</span><span class="p">,</span> <span class="s">"quux"</span><span class="p">,</span> <span class="o">&</span><span class="n">boolean</span><span class="p">);</span>
|
|
1541 |
<span class="n">assert</span><span class="p">(</span><span class="n">strcmp</span><span class="p">(</span><span class="n">str</span><span class="p">,</span> <span class="s">"bar"</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">&&</span> <span class="n">boolean</span> <span class="o">==</span> <span class="mi">1</span><span class="p">);</span>
|
|
1542 |
|
|
1543 |
<span class="cm">/* root is the JSON array [[1, 2], {"baz": null} */</span>
|
|
1544 |
<span class="kt">json_error_t</span> <span class="n">error</span><span class="p">;</span>
|
|
1545 |
<span class="n">json_unpack_ex</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="o">&</span><span class="n">error</span><span class="p">,</span> <span class="n">JSON_VALIDATE_ONLY</span><span class="p">,</span> <span class="s">"[[i,i], {s:n}]"</span><span class="p">,</span> <span class="s">"baz"</span><span class="p">);</span>
|
|
1546 |
<span class="cm">/* returns 0 for validation success, nothing is extracted */</span>
|
|
1547 |
|
|
1548 |
<span class="cm">/* root is the JSON array [1, 2, 3, 4, 5] */</span>
|
|
1549 |
<span class="kt">int</span> <span class="n">myint1</span><span class="p">,</span> <span class="n">myint2</span><span class="p">;</span>
|
|
1550 |
<span class="n">json_unpack</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"[ii!]"</span><span class="p">,</span> <span class="o">&</span><span class="n">myint1</span><span class="p">,</span> <span class="o">&</span><span class="n">myint2</span><span class="p">);</span>
|
|
1551 |
<span class="cm">/* returns -1 for failed validation */</span>
|
|
1552 |
|
|
1553 |
<span class="cm">/* root is an empty JSON object */</span>
|
|
1554 |
<span class="kt">int</span> <span class="n">myint</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">myint2</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
|
|
1555 |
<span class="n">json_unpack</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{s?i, s?[ii]}"</span><span class="p">,</span>
|
|
1556 |
<span class="s">"foo"</span><span class="p">,</span> <span class="o">&</span><span class="n">myint1</span><span class="p">,</span>
|
|
1557 |
<span class="s">"bar"</span><span class="p">,</span> <span class="o">&</span><span class="n">myint2</span><span class="p">,</span> <span class="o">&</span><span class="n">myint3</span><span class="p">);</span>
|
|
1558 |
<span class="cm">/* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */</span>
|
|
1559 |
</pre></div>
|
|
1560 |
</div>
|
|
1561 |
</div>
|
|
1562 |
<div class="section" id="equality">
|
|
1563 |
<h2>Equality<a class="headerlink" href="#equality" title="Permalink to this headline">¶</a></h2>
|
|
1564 |
<p>Testing for equality of two JSON values cannot, in general, be
|
|
1565 |
achieved using the <tt class="docutils literal"><span class="pre">==</span></tt> operator. Equality in the terms of the
|
|
1566 |
<tt class="docutils literal"><span class="pre">==</span></tt> operator states that the two <a class="reference internal" href="#c.json_t" title="json_t"><tt class="xref c c-type docutils literal"><span class="pre">json_t</span></tt></a> pointers point to
|
|
1567 |
exactly the same JSON value. However, two JSON values can be equal not
|
|
1568 |
only if they are exactly the same value, but also if they have equal
|
|
1569 |
“contents”:</p>
|
|
1570 |
<ul class="simple">
|
|
1571 |
<li>Two integer or real values are equal if their contained numeric
|
|
1572 |
values are equal. An integer value is never equal to a real value,
|
|
1573 |
though.</li>
|
|
1574 |
<li>Two strings are equal if their contained UTF-8 strings are equal,
|
|
1575 |
byte by byte. Unicode comparison algorithms are not implemented.</li>
|
|
1576 |
<li>Two arrays are equal if they have the same number of elements and
|
|
1577 |
each element in the first array is equal to the corresponding
|
|
1578 |
element in the second array.</li>
|
|
1579 |
<li>Two objects are equal if they have exactly the same keys and the
|
|
1580 |
value for each key in the first object is equal to the value of the
|
|
1581 |
corresponding key in the second object.</li>
|
|
1582 |
<li>Two true, false or null values have no “contents”, so they are equal
|
|
1583 |
if their types are equal. (Because these values are singletons,
|
|
1584 |
their equality can actually be tested with <tt class="docutils literal"><span class="pre">==</span></tt>.)</li>
|
|
1585 |
</ul>
|
|
1586 |
<p>The following function can be used to test whether two JSON values are
|
|
1587 |
equal.</p>
|
|
1588 |
<dl class="function">
|
|
1589 |
<dt id="c.json_equal">
|
|
1590 |
int <tt class="descname">json_equal</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value1</em>, <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value2</em><big>)</big><a class="headerlink" href="#c.json_equal" title="Permalink to this definition">¶</a></dt>
|
|
1591 |
<dd><p>Returns 1 if <em>value1</em> and <em>value2</em> are equal, as defined above.
|
|
1592 |
Returns 0 if they are inequal or one or both of the pointers are
|
|
1593 |
<em>NULL</em>.</p>
|
|
1594 |
</dd></dl>
|
|
1595 |
|
|
1596 |
</div>
|
|
1597 |
<div class="section" id="copying">
|
|
1598 |
<h2>Copying<a class="headerlink" href="#copying" title="Permalink to this headline">¶</a></h2>
|
|
1599 |
<p>Because of reference counting, passing JSON values around doesn’t
|
|
1600 |
require copying them. But sometimes a fresh copy of a JSON value is
|
|
1601 |
needed. For example, if you need to modify an array, but still want to
|
|
1602 |
use the original afterwards, you should take a copy of it first.</p>
|
|
1603 |
<p>Jansson supports two kinds of copying: shallow and deep. There is a
|
|
1604 |
difference between these methods only for arrays and objects. Shallow
|
|
1605 |
copying only copies the first level value (array or object) and uses
|
|
1606 |
the same child values in the copied value. Deep copying makes a fresh
|
|
1607 |
copy of the child values, too. Moreover, all the child values are deep
|
|
1608 |
copied in a recursive fashion.</p>
|
|
1609 |
<dl class="function">
|
|
1610 |
<dt id="c.json_copy">
|
|
1611 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_copy</tt><big>(</big><a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_copy" title="Permalink to this definition">¶</a></dt>
|
|
1612 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns a shallow copy of <em>value</em>, or <em>NULL</em> on error.</p>
|
|
1613 |
</dd></dl>
|
|
1614 |
|
|
1615 |
<dl class="function">
|
|
1616 |
<dt id="c.json_deep_copy">
|
|
1617 |
<a class="reference internal" href="#c.json_t" title="json_t">json_t</a> *<tt class="descname">json_deep_copy</tt><big>(</big>const <a class="reference internal" href="#c.json_t" title="json_t">json_t</a><em> *value</em><big>)</big><a class="headerlink" href="#c.json_deep_copy" title="Permalink to this definition">¶</a></dt>
|
|
1618 |
<dd><em class="refcount">Return value: New reference.</em><p>Returns a deep copy of <em>value</em>, or <em>NULL</em> on error.</p>
|
|
1619 |
</dd></dl>
|
|
1620 |
|
|
1621 |
</div>
|
|
1622 |
<div class="section" id="custom-memory-allocation">
|
|
1623 |
<span id="apiref-custom-memory-allocation"></span><h2>Custom Memory Allocation<a class="headerlink" href="#custom-memory-allocation" title="Permalink to this headline">¶</a></h2>
|
|
1624 |
<p>By default, Jansson uses <tt class="xref c c-func docutils literal"><span class="pre">malloc()</span></tt> and <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt> for
|
|
1625 |
memory allocation. These functions can be overridden if custom
|
|
1626 |
behavior is needed.</p>
|
|
1627 |
<dl class="type">
|
|
1628 |
<dt id="c.json_malloc_t">
|
|
1629 |
<tt class="descname">json_malloc_t</tt><a class="headerlink" href="#c.json_malloc_t" title="Permalink to this definition">¶</a></dt>
|
|
1630 |
<dd><p>A typedef for a function pointer with <tt class="xref c c-func docutils literal"><span class="pre">malloc()</span></tt>‘s
|
|
1631 |
signature:</p>
|
|
1632 |
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="kt">json_malloc_t</span><span class="p">)(</span><span class="kt">size_t</span><span class="p">);</span>
|
|
1633 |
</pre></div>
|
|
1634 |
</div>
|
|
1635 |
</dd></dl>
|
|
1636 |
|
|
1637 |
<dl class="type">
|
|
1638 |
<dt id="c.json_free_t">
|
|
1639 |
<tt class="descname">json_free_t</tt><a class="headerlink" href="#c.json_free_t" title="Permalink to this definition">¶</a></dt>
|
|
1640 |
<dd><p>A typedef for a function pointer with <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt>‘s
|
|
1641 |
signature:</p>
|
|
1642 |
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">void</span> <span class="p">(</span><span class="o">*</span><span class="kt">json_free_t</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
|
|
1643 |
</pre></div>
|
|
1644 |
</div>
|
|
1645 |
</dd></dl>
|
|
1646 |
|
|
1647 |
<dl class="function">
|
|
1648 |
<dt id="c.json_set_alloc_funcs">
|
|
1649 |
void <tt class="descname">json_set_alloc_funcs</tt><big>(</big><a class="reference internal" href="#c.json_malloc_t" title="json_malloc_t">json_malloc_t</a><em> malloc_fn</em>, <a class="reference internal" href="#c.json_free_t" title="json_free_t">json_free_t</a><em> free_fn</em><big>)</big><a class="headerlink" href="#c.json_set_alloc_funcs" title="Permalink to this definition">¶</a></dt>
|
|
1650 |
<dd><p>Use <em>malloc_fn</em> instead of <tt class="xref c c-func docutils literal"><span class="pre">malloc()</span></tt> and <em>free_fn</em> instead
|
|
1651 |
of <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt>. This function has to be called before any other
|
|
1652 |
Jansson’s API functions to ensure that all memory operations use
|
|
1653 |
the same functions.</p>
|
|
1654 |
</dd></dl>
|
|
1655 |
|
|
1656 |
<p><strong>Examples:</strong></p>
|
|
1657 |
<p>Circumvent problems with different CRT heaps on Windows by using
|
|
1658 |
application’s <tt class="xref c c-func docutils literal"><span class="pre">malloc()</span></tt> and <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt>:</p>
|
|
1659 |
<div class="highlight-c"><div class="highlight"><pre><span class="n">json_set_alloc_funcs</span><span class="p">(</span><span class="n">malloc</span><span class="p">,</span> <span class="n">free</span><span class="p">);</span>
|
|
1660 |
</pre></div>
|
|
1661 |
</div>
|
|
1662 |
<p>Use the <a class="reference external" href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm’s conservative garbage collector</a> for memory
|
|
1663 |
operations:</p>
|
|
1664 |
<div class="highlight-c"><div class="highlight"><pre><span class="n">json_set_alloc_funcs</span><span class="p">(</span><span class="n">GC_malloc</span><span class="p">,</span> <span class="n">GC_free</span><span class="p">);</span>
|
|
1665 |
</pre></div>
|
|
1666 |
</div>
|
|
1667 |
<p>Allow storing sensitive data (e.g. passwords or encryption keys) in
|
|
1668 |
JSON structures by zeroing all memory when freed:</p>
|
|
1669 |
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="o">*</span><span class="nf">secure_malloc</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span>
|
|
1670 |
<span class="p">{</span>
|
|
1671 |
<span class="cm">/* Store the memory area size in the beginning of the block */</span>
|
|
1672 |
<span class="kt">void</span> <span class="o">*</span><span class="n">ptr</span> <span class="o">=</span> <span class="n">malloc</span><span class="p">(</span><span class="n">size</span> <span class="o">+</span> <span class="mi">8</span><span class="p">);</span>
|
|
1673 |
<span class="o">*</span><span class="p">((</span><span class="kt">size_t</span> <span class="o">*</span><span class="p">)</span><span class="n">ptr</span><span class="p">)</span> <span class="o">=</span> <span class="n">size</span><span class="p">;</span>
|
|
1674 |
<span class="k">return</span> <span class="n">ptr</span> <span class="o">+</span> <span class="mi">8</span><span class="p">;</span>
|
|
1675 |
<span class="p">}</span>
|
|
1676 |
|
|
1677 |
<span class="k">static</span> <span class="kt">void</span> <span class="nf">secure_free</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">ptr</span><span class="p">)</span>
|
|
1678 |
<span class="p">{</span>
|
|
1679 |
<span class="kt">size_t</span> <span class="n">size</span><span class="p">;</span>
|
|
1680 |
|
|
1681 |
<span class="n">ptr</span> <span class="o">-=</span> <span class="mi">8</span><span class="p">;</span>
|
|
1682 |
<span class="n">size</span> <span class="o">=</span> <span class="o">*</span><span class="p">((</span><span class="kt">size_t</span> <span class="o">*</span><span class="p">)</span><span class="n">ptr</span><span class="p">);</span>
|
|
1683 |
|
|
1684 |
<span class="n">guaranteed_memset</span><span class="p">(</span><span class="n">ptr</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">size</span> <span class="o">+</span> <span class="mi">8</span><span class="p">);</span>
|
|
1685 |
<span class="n">free</span><span class="p">(</span><span class="n">ptr</span><span class="p">);</span>
|
|
1686 |
<span class="p">}</span>
|
|
1687 |
|
|
1688 |
<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span>
|
|
1689 |
<span class="p">{</span>
|
|
1690 |
<span class="n">json_set_alloc_funcs</span><span class="p">(</span><span class="n">secure_malloc</span><span class="p">,</span> <span class="n">secure_free</span><span class="p">);</span>
|
|
1691 |
<span class="cm">/* ... */</span>
|
|
1692 |
<span class="p">}</span>
|
|
1693 |
</pre></div>
|
|
1694 |
</div>
|
|
1695 |
<p>For more information about the issues of storing sensitive data in
|
|
1696 |
memory, see
|
|
1697 |
<a class="reference external" href="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html">http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html</a>.
|
|
1698 |
The page also explains the <tt class="xref c c-func docutils literal"><span class="pre">guaranteed_memset()</span></tt> function used
|
|
1699 |
in the example and gives a sample implementation for it.</p>
|
|
1700 |
</div>
|
|
1701 |
</div>
|
|
1702 |
|
|
1703 |
|
|
1704 |
</div>
|
|
1705 |
</div>
|
|
1706 |
</div>
|
|
1707 |
<div class="sphinxsidebar">
|
|
1708 |
<div class="sphinxsidebarwrapper">
|
|
1709 |
<h3><a href="index.html">Table Of Contents</a></h3>
|
|
1710 |
<ul>
|
|
1711 |
<li><a class="reference internal" href="#">API Reference</a><ul>
|
|
1712 |
<li><a class="reference internal" href="#preliminaries">Preliminaries</a></li>
|
|
1713 |
<li><a class="reference internal" href="#library-version">Library Version</a></li>
|
|
1714 |
<li><a class="reference internal" href="#value-representation">Value Representation</a><ul>
|
|
1715 |
<li><a class="reference internal" href="#type">Type</a></li>
|
|
1716 |
<li><a class="reference internal" href="#reference-count">Reference Count</a></li>
|
|
1717 |
<li><a class="reference internal" href="#circular-references">Circular References</a></li>
|
|
1718 |
</ul>
|
|
1719 |
</li>
|
|
1720 |
<li><a class="reference internal" href="#true-false-and-null">True, False and Null</a></li>
|
|
1721 |
<li><a class="reference internal" href="#string">String</a></li>
|
|
1722 |
<li><a class="reference internal" href="#number">Number</a></li>
|
|
1723 |
<li><a class="reference internal" href="#array">Array</a></li>
|
|
1724 |
<li><a class="reference internal" href="#object">Object</a></li>
|
|
1725 |
<li><a class="reference internal" href="#error-reporting">Error reporting</a></li>
|
|
1726 |
<li><a class="reference internal" href="#encoding">Encoding</a></li>
|
|
1727 |
<li><a class="reference internal" href="#decoding">Decoding</a></li>
|
|
1728 |
<li><a class="reference internal" href="#building-values">Building Values</a></li>
|
|
1729 |
<li><a class="reference internal" href="#parsing-and-validating-values">Parsing and Validating Values</a></li>
|
|
1730 |
<li><a class="reference internal" href="#equality">Equality</a></li>
|
|
1731 |
<li><a class="reference internal" href="#copying">Copying</a></li>
|
|
1732 |
<li><a class="reference internal" href="#custom-memory-allocation">Custom Memory Allocation</a></li>
|
|
1733 |
</ul>
|
|
1734 |
</li>
|
|
1735 |
</ul>
|
|
1736 |
|
|
1737 |
<h4>Previous topic</h4>
|
|
1738 |
<p class="topless"><a href="portability.html"
|
|
1739 |
title="previous chapter">Portability</a></p>
|
|
1740 |
<h4>Next topic</h4>
|
|
1741 |
<p class="topless"><a href="changes.html"
|
|
1742 |
title="next chapter">Changes in Jansson</a></p>
|
|
1743 |
<h3>This Page</h3>
|
|
1744 |
<ul class="this-page-menu">
|
|
1745 |
<li><a href="_sources/apiref.txt"
|
|
1746 |
rel="nofollow">Show Source</a></li>
|
|
1747 |
</ul>
|
|
1748 |
<div id="searchbox" style="display: none">
|
|
1749 |
<h3>Quick search</h3>
|
|
1750 |
<form class="search" action="search.html" method="get">
|
|
1751 |
<input type="text" name="q" />
|
|
1752 |
<input type="submit" value="Go" />
|
|
1753 |
<input type="hidden" name="check_keywords" value="yes" />
|
|
1754 |
<input type="hidden" name="area" value="default" />
|
|
1755 |
</form>
|
|
1756 |
<p class="searchtip" style="font-size: 90%">
|
|
1757 |
Enter search terms or a module, class or function name.
|
|
1758 |
</p>
|
|
1759 |
</div>
|
|
1760 |
<script type="text/javascript">$('#searchbox').show(0);</script>
|
|
1761 |
</div>
|
|
1762 |
</div>
|
|
1763 |
<div class="clearer"></div>
|
|
1764 |
</div>
|
|
1765 |
<div class="related">
|
|
1766 |
<h3>Navigation</h3>
|
|
1767 |
<ul>
|
|
1768 |
<li class="right" style="margin-right: 10px">
|
|
1769 |
<a href="genindex.html" title="General Index"
|
|
1770 |
>index</a></li>
|
|
1771 |
<li class="right" >
|
|
1772 |
<a href="changes.html" title="Changes in Jansson"
|
|
1773 |
>next</a> |</li>
|
|
1774 |
<li class="right" >
|
|
1775 |
<a href="portability.html" title="Portability"
|
|
1776 |
>previous</a> |</li>
|
|
1777 |
<li><a href="index.html">Jansson 2.7 documentation</a> »</li>
|
|
1778 |
</ul>
|
|
1779 |
</div>
|
|
1780 |
<div class="footer">
|
|
1781 |
© Copyright 2009-2014, Petri Lehtinen.
|
|
1782 |
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
|
|
1783 |
</div>
|
|
1784 |
</body>
|
|
1785 |
</html> |