3421N/A<span id="apiref"></span><h1>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h1>
3421N/A<h2>Preliminaries<a class="headerlink" href="#preliminaries" title="Permalink to this headline">¶</a></h2>
3421N/A<p>All declarations are in <tt class="file docutils literal"><span class="pre">jansson.h</span></tt>, so it’s enough to</p>
3421N/A<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <jansson.h></span>
3421N/A<p>All constants are prefixed with <tt class="docutils literal"><span class="pre">JSON_</span></tt> (except for those describing
3421N/Athe library version, prefixed with <tt class="docutils literal"><span class="pre">JANSSON_</span></tt>). Other identifiers
3421N/Aare 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
3421N/A<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>
3421N/A<h2>Library Version<a class="headerlink" href="#library-version" title="Permalink to this headline">¶</a></h2>
3421N/A<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>
3421N/A<dd>A string representation of the current version, e.g. <tt class="docutils literal"><span class="pre">"1.2.1"</span></tt> or
3421N/A<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.
3421N/A<div class="last highlight-c"><div class="highlight"><pre><span class="cp">#if JANSSON_VERSION_HEX >= 0x010300</span>
3421N/A<h2>Value Representation<a class="headerlink" href="#value-representation" title="Permalink to this headline">¶</a></h2>
3421N/A<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:
3421N/A<em>object</em>, <em>array</em>, <em>string</em>, <em>number</em>, <em>boolean</em>, and <em>null</em>. JSON
3421N/A<tt class="descname">json_t</tt><a class="headerlink" href="#c.json_t" title="Permalink to this definition">¶</a></dt>
3421N/A<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
3421N/Aenum <tt class="descname">json_type</tt><a class="headerlink" href="#c.json_type" title="Permalink to this definition">¶</a></dt>
3421N/A<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_OBJECT</span></tt></td>
3421N/A<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_ARRAY</span></tt></td>
3421N/A<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_STRING</span></tt></td>
3421N/A<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_INTEGER</span></tt></td>
3421N/A<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_REAL</span></tt></td>
3421N/A<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_TRUE</span></tt></td>
3421N/A<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">JSON_FALSE</span></tt></td>
3421N/A<tr class="row-even"><td><tt class="docutils literal"><span class="pre">JSON_NULL</span></tt></td>
3421N/A<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
3421N/Ais represented by a value of the type <tt class="docutils literal"><span class="pre">JSON_TRUE</span></tt> and false by a
3421N/Aint <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>
3421N/A<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
3421N/A<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
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<dd><p>Returns true for values of types <tt class="docutils literal"><span class="pre">JSON_INTEGER</span></tt> and
3421N/A<tt class="docutils literal"><span class="pre">JSON_REAL</span></tt>, and false for other types and for <em>NULL</em>.</p>
3421N/A<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>
3421N/A<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
3421N/A<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>
3421N/A<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>
3421N/A<span id="apiref-reference-count"></span><h3>Reference Count<a class="headerlink" href="#reference-count" title="Permalink to this headline">¶</a></h3>
3421N/A<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>
3421N/Avoid <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>
3421N/A<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
3421N/Aas 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
3421N/Athe 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
3421N/Ahave 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
3421N/Asuffixed 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>
3421N/A<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>
3421N/A<span class="n">array</span> <span class="o">=</span> <span class="n">json_array</span><span class="p">();</span>
3421N/A<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>
3421N/A<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>
3421N/A<span class="n">json_decref</span><span class="p">(</span><span class="n">integer</span><span class="p">);</span>
3421N/Aby 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
3421N/Afunction <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
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/Areference 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>
3421N/A<h3>Circular References<a class="headerlink" href="#circular-references" title="Permalink to this headline">¶</a></h3>
3421N/A<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>
3421N/A<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>
3421N/A<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
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<p>In this example, the array <tt class="docutils literal"><span class="pre">arr2</span></tt> is contained in the array
3421N/A<tt class="docutils literal"><span class="pre">arr1</span></tt>, and vice versa. Jansson cannot check for this kind of
3421N/Acannot 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
3421N/A<h2>True, False and Null<a class="headerlink" href="#true-false-and-null" title="Permalink to this headline">¶</a></h2>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Returns the JSON true value.</p>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Returns the JSON false value.</p>
3421N/A<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>
3421N/A<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.
3421N/AThis 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>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Returns the JSON null value.</p>
3421N/A<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>
3421N/A<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
3421N/A<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>
3421N/A<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
3421N/A<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>
3421N/A<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
3421N/A<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>
3421N/A<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
3421N/Aconst 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>
3421N/Asize_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>
3421N/Aint <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>
3421N/A<dd><p>Sets the associated value of <em>string</em> to <em>value</em>. <em>value</em> must be a
3421N/Aint <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>
3421N/A<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>
3421N/Aint <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>
3421N/A<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
3421N/Aint <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>
3421N/A<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,
3421N/Athe two. They are called “integer” and “real”, respectively. For more
3421N/Ainformation, see <a class="reference internal" href="conformance.html#rfc-conformance"><em>RFC Conformance</em></a>.</p>
3421N/A<tt class="descname">json_int_t</tt><a class="headerlink" href="#c.json_int_t" title="Permalink to this definition">¶</a></dt>
3421N/Apractice it’s just a typedef of <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> if your compiler
3421N/A<p>Usually, you can safely use plain <tt class="docutils literal"><span class="pre">int</span></tt> in place of
3421N/A<tt class="docutils literal"><span class="pre">json_int_t</span></tt>, and the implicit C integer conversion handles the
3421N/Ashould use <tt class="docutils literal"><span class="pre">json_int_t</span></tt> explicitly.</p>
3421N/A<dt><tt class="docutils literal"><span class="pre">JSON_INTEGER_IS_LONG_LONG</span></tt></dt>
3421N/A<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
3421N/A<div class="last highlight-c"><div class="highlight"><pre><span class="cp">#if JSON_INTEGER_IS_LONG_LONG</span>
3421N/A<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
3421N/Aspecifier 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
3421N/Aleading <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
3421N/Ais 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
3421N/Aeither <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
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON integer, or <em>NULL</em> on error.</p>
3421N/A<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>
3421N/Aint <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>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON real, or <em>NULL</em> on error.</p>
3421N/Adouble <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>
3421N/Aint <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>
3421N/Adouble <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>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON array, or <em>NULL</em> on error. Initially, the array
3421N/Asize_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>
3421N/A<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>
3421N/A<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
3421N/A<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,
3421N/Aint <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>
3421N/A<dd><p>Replaces the element in <em>array</em> at position <em>index</em> with <em>value</em>.
3421N/A<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
3421N/Aint <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>
3421N/A<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>.
3421N/Aint <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>
3421N/A<dd><p>Appends <em>value</em> to the end of <em>array</em>, growing the size of <em>array</em>
3421N/Aint <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>
3421N/A<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
3421N/Aint <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>
3421N/Aint <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>
3421N/A<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
3421N/Aint <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>
3421N/Aint <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>
3421N/Aint <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>
3421N/A<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>
3421N/A<dd><p>Iterate over every element of <tt class="docutils literal"><span class="pre">array</span></tt>, running the block
3421N/Avariables <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
3421N/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> <span class="pre">*</span></tt></a> respectively. Example:</p>
3421N/A<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* array is a JSON array */</span>
3421N/A<span class="kt">json_t</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
3421N/A<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>
3421N/A<p>This macro expands to an ordinary <tt class="docutils literal"><span class="pre">for</span></tt> statement upon
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Returns a new JSON object, or <em>NULL</em> on error. Initially, the
3421N/Asize_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>
3421N/A<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>
3421N/A<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
3421N/Aint <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>
3421N/A<dd><p>Set the value of <em>key</em> to <em>value</em> in <em>object</em>. <em>key</em> must be a
3421N/Aint <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>
3421N/A<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
3421N/Aint <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>
3421N/A<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
3421N/Aint <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>
3421N/A<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
3421N/Aint <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>
3421N/Aint <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>
3421N/Aint <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>
3421N/Aint <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>
3421N/A<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
3421N/Aint <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>
3421N/A<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.
3421N/A<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>
3421N/A<dd><p>Iterate over every key-value pair of <tt class="docutils literal"><span class="pre">object</span></tt>, running the block
3421N/Avariables <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
3421N/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> <span class="pre">*</span></tt></a> respectively. Example:</p>
3421N/A<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* obj is a JSON object */</span>
3421N/A<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">key</span><span class="p">;</span>
3421N/A<span class="kt">json_t</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
3421N/A<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>
3421N/A<p>This macro expands to an ordinary <tt class="docutils literal"><span class="pre">for</span></tt> statement upon
3421N/Avoid *<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>
3421N/Avoid *<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>
3421N/A<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
3421N/Avoid *<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>
3421N/Aconst 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>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: Borrowed reference.</em><p>Extract the associated value from <em>iter</em>.</p>
3421N/Aint <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>
3421N/Aint <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>
3421N/A<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
3421N/Avoid *<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>
3421N/A<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
3421N/Avalues 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
3421N/Aimplement <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>
3421N/A<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* obj is a JSON object */</span>
3421N/A<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">key</span><span class="p">;</span>
3421N/A<span class="kt">json_t</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
3421N/A<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>
3421N/A<span class="k">while</span><span class="p">(</span><span class="n">iter</span><span class="p">)</span>
3421N/A <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>
3421N/A <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>
3421N/A <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>
3421N/Avoid <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>
3421N/A<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
3421N/A<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
3421N/Afunction. See <a class="reference internal" href="portability.html#portability-thread-safety"><em>Thread safety</em></a> for notes on thread
3421N/Afunction 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>
3421N/A<h2>Error reporting<a class="headerlink" href="#error-reporting" title="Permalink to this headline">¶</a></h2>
3421N/Auser. 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
3421N/A<a class="reference internal" href="#apiref-unpack"><em>Parsing and Validating Values</em></a> for functions that pass error information using
3421N/A<tt class="descname">json_error_t</tt><a class="headerlink" href="#c.json_error_t" title="Permalink to this definition">¶</a></dt>
3421N/Aspecial identifier in angle brackers (e.g. <tt class="docutils literal"><span class="pre"><string></span></tt>).</p>
3421N/Aint <tt class="descname">line</tt><a class="headerlink" href="#c.json_error_t.line" title="Permalink to this definition">¶</a></dt>
3421N/Aint <tt class="descname">column</tt><a class="headerlink" href="#c.json_error_t.column" title="Permalink to this definition">¶</a></dt>
3421N/Asize_t <tt class="descname">position</tt><a class="headerlink" href="#c.json_error_t.position" title="Permalink to this definition">¶</a></dt>
3421N/A<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,
3421N/A<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>
3421N/A <span class="kt">json_t</span> <span class="o">*</span><span class="n">json</span><span class="p">;</span>
3421N/A <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>
3421N/A <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>
3421N/A<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
3421N/Aexample), the contents of <tt class="docutils literal"><span class="pre">error</span></tt> are generally left unspecified.
3421N/AThe decoding functions write to the <tt class="docutils literal"><span class="pre">position</span></tt> member also on
3421N/Asuccess. See <a class="reference internal" href="#apiref-decoding"><em>Decoding</em></a> for more info.</p>
3421N/A<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,
3421N/A<h2>Encoding<a class="headerlink" href="#encoding" title="Permalink to this headline">¶</a></h2>
3421N/ATo encode any JSON value, use the <tt class="docutils literal"><span class="pre">JSON_ENCODE_ANY</span></tt> flag (see
3421N/Aaltered 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
3421N/Aoutput. If <tt class="docutils literal"><span class="pre">JSON_INDENT</span></tt> is not used or <em>n</em> is 0, no newlines are
3421N/A<p>The <tt class="docutils literal"><span class="pre">JSON_MAX_INDENT</span></tt> constant defines the maximum indentation
3421N/A<p><span class="versionmodified">Changed in version 2.7: </span>Added <tt class="docutils literal"><span class="pre">JSON_MAX_INDENT</span></tt>.</p>
3421N/Abetween array and object items to <tt class="docutils literal"><span class="pre">","</span></tt> and between object keys
3421N/Aand values to <tt class="docutils literal"><span class="pre">":"</span></tt>. Without this flag, the corresponding
3421N/Aseparators 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>
3421N/A<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
3421N/A<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>
3421N/A<dd><p class="first">Output all real numbers with at most <em>n</em> digits of precision. The
3421N/Achar *<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>
3421N/Aby the caller using <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt>.</p>
3421N/Aint <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>
3421N/Aint <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>
3421N/A<tt class="descname">json_dump_callback_t</tt><a class="headerlink" href="#c.json_dump_callback_t" title="Permalink to this definition">¶</a></dt>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/Aint <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>
3421N/A<span id="apiref-decoding"></span><h2>Decoding<a class="headerlink" href="#decoding" title="Permalink to this headline">¶</a></h2>
3421N/Athe <tt class="docutils literal"><span class="pre">JSON_DECODE_ANY</span></tt> flag (see below).</p>
3421N/A<p>See <a class="reference internal" href="conformance.html#rfc-conformance"><em>RFC Conformance</em></a> for a discussion on Jansson’s conformance
3421N/A<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
3421N/A<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
3421N/AJSON input is encountered. If both <tt class="docutils literal"><span class="pre">JSON_DISABLE_EOF_CHECK</span></tt> and
3421N/A<tt class="docutils literal"><span class="pre">JSON_DECODE_ANY</span></tt> flags are used, the decoder may read one extra
3421N/A<tt class="docutils literal"><span class="pre">4true</span></tt> correctly decodes the integer 4, but also reads the
3421N/A<tt class="docutils literal"><span class="pre">t</span></tt>. For this reason, if reading multiple consecutive values that
3421N/Aints and reals. For more information see <a class="reference internal" href="conformance.html#real-vs-integer"><em>Real vs. Integer</em></a>.
3421N/A<dd><p class="first">Allow <tt class="docutils literal"><span class="pre">\u0000</span></tt> escape inside string values. This is a safety
3421N/Ausing 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
3421N/A<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>
3421N/A<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
3421N/Aits <tt class="docutils literal"><span class="pre">position</span></tt> field. This is especially useful when using
3421N/A<tt class="docutils literal"><span class="pre">JSON_DISABLE_EOF_CHECK</span></tt> to read multiple consecutive JSON texts.</p>
3421N/A<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
3421N/Aof 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>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON string <em>input</em> and returns the array or object it
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON string <em>buffer</em>, whose length is <em>buflen</em>, and
3421N/Ais 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
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON text in stream <em>input</em> and returns the array or
3421N/Athe file position will be at EOF, unless <tt class="docutils literal"><span class="pre">JSON_DISABLE_EOF_CHECK</span></tt>
3421N/Acharacter 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
3421N/Aallows 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
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON text in file <em>path</em> and returns the array or
3421N/A<tt class="descname">json_load_callback_t</tt><a class="headerlink" href="#c.json_load_callback_t" title="Permalink to this definition">¶</a></dt>
3421N/A<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>
3421N/A<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>
3421N/Acorresponding <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>
3421N/A<tt class="docutils literal"><span class="pre">(size_t)-1</span></tt> to abort the decoding process.</p>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Decodes the JSON text produced by repeated calls to <em>callback</em>, and
3421N/A<span id="apiref-pack"></span><h2>Building Values<a class="headerlink" href="#building-values" title="Permalink to this headline">¶</a></h2>
3421N/A<p>For example, the format string <tt class="docutils literal"><span class="pre">"i"</span></tt> specifies a single integer
3421N/Avalue, 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>
3421N/A<span class="pre">b]"</span></tt> specifies an array value with two strings and a boolean as its
3421N/A<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Create the JSON integer 42 */</span>
3421N/A<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>
3421N/A<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>
3421N/A<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string) [const char *]</dt>
3421N/A<dt><tt class="docutils literal"><span class="pre">s#</span></tt> (string) [const char *, int]</dt>
3421N/A<dt><tt class="docutils literal"><span class="pre">s%</span></tt> (string) [const char *, size_t]</dt>
3421N/A<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>
3421N/A<dd><p class="first">Like <tt class="docutils literal"><span class="pre">s</span></tt>, but concatenate to the previous string. Only valid
3421N/Aafter <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>
3421N/A<dd><p class="first">Like <tt class="docutils literal"><span class="pre">s#</span></tt>, but concatenate to the previous string. Only valid
3421N/Aafter <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>
3421N/A<dt><tt class="docutils literal"><span class="pre">+%</span></tt> (string) [const char *, size_t]</dt>
3421N/A<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>
3421N/A<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
3421N/Ato <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>
3421N/A<dd>Convert a C <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> to JSON integer.</dd>
3421N/A<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>
3421N/A<dd>Convert a C <tt class="xref c c-type docutils literal"><span class="pre">double</span></tt> to JSON real.</dd>
3421N/Aarray or object, the reference to the value passed to <tt class="docutils literal"><span class="pre">o</span></tt> is
3421N/A<dd>Like <tt class="docutils literal"><span class="pre">o</span></tt>, but the argument’s reference count is incremented.
3421N/Akeep the reference for the JSON value consumed by <tt class="docutils literal"><span class="pre">O</span></tt> to
3421N/A<dd>Build an array with contents from the inner format string. <tt class="docutils literal"><span class="pre">fmt</span></tt>
3421N/A<tt class="docutils literal"><span class="pre">fmt</span></tt>. The first, third, etc. format specifier represent a key,
3421N/Aand 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),
3421N/A<p>Whitespace, <tt class="docutils literal"><span class="pre">:</span></tt> and <tt class="docutils literal"><span class="pre">,</span></tt> are ignored.</p>
3421N/A<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>
3421N/A<dd><em class="refcount">Return value: New reference.</em><p>Build a new JSON value according to the format string <em>fmt</em>. For
3421N/Aeach format specifier (except for <tt class="docutils literal"><span class="pre">{}[]n</span></tt>), one or more arguments
3421N/A<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>
3421N/A<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>
3421N/A<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
3421N/A<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Build an empty JSON object */</span>
3421N/A<span class="n">json_pack</span><span class="p">(</span><span class="s">"{}"</span><span class="p">);</span>
3421N/A<span class="cm">/* Build the JSON object {"foo": 42, "bar": 7} */</span>
3421N/A<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>
3421N/A<span class="cm">/* Like above, ':', ',' and whitespace are ignored */</span>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<span class="cm">/* Concatentate strings together to build the JSON string "foobarbaz" */</span>
3421N/A<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>
3421N/A<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>
3421N/Aand 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>
3421N/Aunpacked. This check be enabled with the format specifier <tt class="docutils literal"><span class="pre">!</span></tt> or by
3421N/Ausing the flag <tt class="docutils literal"><span class="pre">JSON_STRICT</span></tt>. See below for details.</p>
3421N/A<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string) [const char *]</dt>
3421N/A<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
3421N/A<dt><tt class="docutils literal"><span class="pre">s%</span></tt> (string) [const char *, size_t *]</dt>
3421N/A<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>
3421N/Ais converted to 1 and <tt class="docutils literal"><span class="pre">false</span></tt> to 0.</dd>
3421N/A<dd>Convert a JSON integer to C <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt>.</dd>
3421N/A<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>
3421N/A<dd>Convert a JSON real to C <tt class="xref c c-type docutils literal"><span class="pre">double</span></tt>.</dd>
3421N/A<dt><tt class="docutils literal"><span class="pre">F</span></tt> (integer or real) [double]</dt>
3421N/A<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>
3421N/A<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>
3421N/A<dd>Like <tt class="docutils literal"><span class="pre">O</span></tt>, but the JSON value’s reference count is incremented.</dd>
3421N/Astring. <tt class="docutils literal"><span class="pre">fmt</span></tt> may contain objects and arrays, i.e. recursive
3421N/Astring <tt class="docutils literal"><span class="pre">fmt</span></tt>. The first, third, etc. format specifier represent
3421N/Aa key, and must be <tt class="docutils literal"><span class="pre">s</span></tt>. The corresponding argument to unpack
3421N/A<p><tt class="docutils literal"><span class="pre">fmt</span></tt> may contain objects and arrays as values, i.e. recursive
3421N/A<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
3421N/Ause the <tt class="docutils literal"><span class="pre">JSON_STRICT</span></tt> unpacking flag.</dd>
3421N/A<dd>This special format specifier is the opposite of <tt class="docutils literal"><span class="pre">!</span></tt>. If the
3421N/A<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
3421N/A<p>Whitespace, <tt class="docutils literal"><span class="pre">:</span></tt> and <tt class="docutils literal"><span class="pre">,</span></tt> are ignored.</p>
3421N/Aint <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>
3421N/Aint <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>
3421N/Aint <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>
3421N/A<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>
3421N/Ainstead 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
3421N/Aspecifier causes the reference count of <tt class="docutils literal"><span class="pre">root</span></tt>, or some value
3421N/Areachable 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>
3421N/A<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
3421N/Aperfectly 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
3421N/A<tt class="docutils literal"><span class="pre">json_t</span> <span class="pre">*</span></tt> when used with these functions.</p>
3421N/Aformat specifier <tt class="docutils literal"><span class="pre">!</span></tt> to the end of every array and object in the
3421N/A<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* root is the JSON integer 42 */</span>
3421N/A<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>
3421N/A<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>
3421N/A<span class="cm">/* root is the JSON object {"foo": "bar", "quux": true} */</span>
3421N/A<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">str</span><span class="p">;</span>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<span class="kt">int</span> <span class="n">myint1</span><span class="p">,</span> <span class="n">myint2</span><span class="p">;</span>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A <span class="s">"foo"</span><span class="p">,</span> <span class="o">&</span><span class="n">myint1</span><span class="p">,</span>
3421N/A <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>
3421N/A<span class="cm">/* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */</span>
3421N/A<h2>Equality<a class="headerlink" href="#equality" title="Permalink to this headline">¶</a></h2>
3421N/Aachieved using the <tt class="docutils literal"><span class="pre">==</span></tt> operator. Equality in the terms of the
3421N/A<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
3421N/Atheir equality can actually be tested with <tt class="docutils literal"><span class="pre">==</span></tt>.)</li>
3421N/Aint <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>
3421N/A<h2>Copying<a class="headerlink" href="#copying" title="Permalink to this headline">¶</a></h2>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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>
3421N/A<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
3421N/A<tt class="descname">json_malloc_t</tt><a class="headerlink" href="#c.json_malloc_t" title="Permalink to this definition">¶</a></dt>
3421N/A<dd><p>A typedef for a function pointer with <tt class="xref c c-func docutils literal"><span class="pre">malloc()</span></tt>‘s
3421N/A<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>
3421N/A<tt class="descname">json_free_t</tt><a class="headerlink" href="#c.json_free_t" title="Permalink to this definition">¶</a></dt>
3421N/A<dd><p>A typedef for a function pointer with <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt>‘s
3421N/A<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>
3421N/Avoid <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>
3421N/A<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
3421N/Aof <tt class="xref c c-func docutils literal"><span class="pre">free()</span></tt>. This function has to be called before any other
3421N/Aapplication’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>
3421N/A<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>
3421N/A<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
3421N/A<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>
3421N/A<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>
3421N/A <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>
3421N/A <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>
3421N/A <span class="k">return</span> <span class="n">ptr</span> <span class="o">+</span> <span class="mi">8</span><span class="p">;</span>
3421N/A<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>
3421N/A <span class="n">ptr</span> <span class="o">-=</span> <span class="mi">8</span><span class="p">;</span>
3421N/A <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>
3421N/A <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>
3421N/A <span class="n">free</span><span class="p">(</span><span class="n">ptr</span><span class="p">);</span>
3421N/A <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>
3421N/A<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>.
3421N/AThe page also explains the <tt class="xref c c-func docutils literal"><span class="pre">guaranteed_memset()</span></tt> function used
3421N/A<li><a class="reference internal" href="#parsing-and-validating-values">Parsing and Validating Values</a></li>