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