|
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> |