upgrading.html revision 3421
56881241fa725984d8184455e3f0c1b6de305c6bmental<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
56881241fa725984d8184455e3f0c1b6de305c6bmental "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
56881241fa725984d8184455e3f0c1b6de305c6bmental <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
56881241fa725984d8184455e3f0c1b6de305c6bmental <title>Upgrading from 1.x — Jansson 2.7 documentation</title>
56881241fa725984d8184455e3f0c1b6de305c6bmental <link rel="stylesheet" href="_static/default.css" type="text/css" />
56881241fa725984d8184455e3f0c1b6de305c6bmental <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
56881241fa725984d8184455e3f0c1b6de305c6bmental var DOCUMENTATION_OPTIONS = {
56881241fa725984d8184455e3f0c1b6de305c6bmental URL_ROOT: './',
6a13f00062e752dfe3aecd06dbc6d57c5f62ba8cjoncruz VERSION: '2.7',
56881241fa725984d8184455e3f0c1b6de305c6bmental COLLAPSE_INDEX: false,
6a13f00062e752dfe3aecd06dbc6d57c5f62ba8cjoncruz FILE_SUFFIX: '.html',
56881241fa725984d8184455e3f0c1b6de305c6bmental HAS_SOURCE: true
0801db25a73ad5948af5f492113b6c2b72df4d57joncruz <script type="text/javascript" src="_static/jquery.js"></script>
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruz <script type="text/javascript" src="_static/underscore.js"></script>
56881241fa725984d8184455e3f0c1b6de305c6bmental <script type="text/javascript" src="_static/doctools.js"></script>
56881241fa725984d8184455e3f0c1b6de305c6bmental <link rel="top" title="Jansson 2.7 documentation" href="index.html" />
56881241fa725984d8184455e3f0c1b6de305c6bmental <link rel="next" title="Tutorial" href="tutorial.html" />
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruz <link rel="prev" title="Getting Started" href="gettingstarted.html" />
caf60ce95aac2d44c7cdd41125e9f4ab32ded886joncruz <a href="gettingstarted.html" title="Getting Started"
caf60ce95aac2d44c7cdd41125e9f4ab32ded886joncruz <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruz<h1>Upgrading from 1.x<a class="headerlink" href="#upgrading-from-1-x" title="Permalink to this headline">¶</a></h1>
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruz<p>This chapter lists the backwards incompatible changes introduced in
c0ad9a2e35be02bb66552e03f392fe02b57bda7bmentalJansson 2.0, and the steps that are needed for upgrading your code.</p>
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruz<p><strong>The incompatibilities are not dramatic.</strong> The biggest change is that
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruzall decoding functions now require and extra parameter. Most programs
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruzcan be modified to work with 2.0 by adding a <tt class="docutils literal"><span class="pre">0</span></tt> as the second
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruzparameter to all calls of <a class="reference internal" href="apiref.html#c.json_loads" title="json_loads"><tt class="xref c c-func docutils literal"><span class="pre">json_loads()</span></tt></a>, <a class="reference internal" href="apiref.html#c.json_loadf" title="json_loadf"><tt class="xref c c-func docutils literal"><span class="pre">json_loadf()</span></tt></a>
87c6636aa10a025441b313717f37fdbbc5b9af6ejoncruzand <a class="reference internal" href="apiref.html#c.json_load_file" title="json_load_file"><tt class="xref c c-func docutils literal"><span class="pre">json_load_file()</span></tt></a>.</p>
56881241fa725984d8184455e3f0c1b6de305c6bmental<h2>Compatibility<a class="headerlink" href="#compatibility" title="Permalink to this headline">¶</a></h2>
56881241fa725984d8184455e3f0c1b6de305c6bmental<p>Jansson 2.0 is backwards incompatible with the Jansson 1.x releases.
410db19c3e005769ef7dbf538a5b5fa5f0b5b88ejoncruzIt is ABI incompatible, i.e. all programs dynamically linking to the
0832343fd7f087d3b718bc86f2cf74014e56b582joncruzJansson library need to be recompiled. It’s also API incompatible,
0832343fd7f087d3b718bc86f2cf74014e56b582joncruzi.e. the source code of programs using Jansson 1.x may need
0832343fd7f087d3b718bc86f2cf74014e56b582joncruzmodifications to make them compile against Jansson 2.0.</p>
0832343fd7f087d3b718bc86f2cf74014e56b582joncruz<p>All the 2.x releases are guaranteed to be backwards compatible for
0832343fd7f087d3b718bc86f2cf74014e56b582joncruzboth ABI and API, so no recompilation or source changes are needed
0832343fd7f087d3b718bc86f2cf74014e56b582joncruz<div class="section" id="list-of-incompatible-changes">
0832343fd7f087d3b718bc86f2cf74014e56b582joncruz<h2>List of Incompatible Changes<a class="headerlink" href="#list-of-incompatible-changes" title="Permalink to this headline">¶</a></h2>
56881241fa725984d8184455e3f0c1b6de305c6bmental<dd><p class="first">For future needs, a <tt class="docutils literal"><span class="pre">flags</span></tt> parameter was added as the second
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzparameter to all decoding functions, i.e. <a class="reference internal" href="apiref.html#c.json_loads" title="json_loads"><tt class="xref c c-func docutils literal"><span class="pre">json_loads()</span></tt></a>,
6a13f00062e752dfe3aecd06dbc6d57c5f62ba8cjoncruz<a class="reference internal" href="apiref.html#c.json_loadf" title="json_loadf"><tt class="xref c c-func docutils literal"><span class="pre">json_loadf()</span></tt></a> and <a class="reference internal" href="apiref.html#c.json_load_file" title="json_load_file"><tt class="xref c c-func docutils literal"><span class="pre">json_load_file()</span></tt></a>. All calls to
6a13f00062e752dfe3aecd06dbc6d57c5f62ba8cjoncruzthese functions need to be changed by adding a <tt class="docutils literal"><span class="pre">0</span></tt> as the second
362d6fa90bf1d5218f2bb4f72ce194e074778a25joncruzargument. For example:</p>
362d6fa90bf1d5218f2bb4f72ce194e074778a25joncruz<div class="last highlight-c"><div class="highlight"><pre><span class="cm">/* old code */</span>
362d6fa90bf1d5218f2bb4f72ce194e074778a25joncruz<span class="n">json_loads</span><span class="p">(</span><span class="n">input</span><span class="p">,</span> <span class="o">&</span><span class="n">error</span><span class="p">);</span>
362d6fa90bf1d5218f2bb4f72ce194e074778a25joncruz<span class="n">json_loads</span><span class="p">(</span><span class="n">input</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="o">&</span><span class="n">error</span><span class="p">);</span>
6a13f00062e752dfe3aecd06dbc6d57c5f62ba8cjoncruz<dt><strong>Underlying type of JSON integers</strong></dt>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<dd><p class="first">The underlying C type of JSON integers has been changed from
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> to the widest available signed integer type, i.e.
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<tt class="xref c c-type docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> or <tt class="xref c c-type docutils literal"><span class="pre">long</span></tt>, depending on whether
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<tt class="xref c c-type docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> is supported on your system or not. This makes
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzthe whole 64-bit integer range available on most modern systems.</p>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<p class="last"><tt class="docutils literal"><span class="pre">jansson.h</span></tt> has a typedef <a class="reference internal" href="apiref.html#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 the underlying
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzinteger type. <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> should still be used in most cases when
5eb26fcf16904b1881b3df87b17fd2e20a1ae110mentaldealing with smallish JSON integers, as the compiler handles
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzimplicit type coercion. Only when the full 64-bit range is needed,
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<a class="reference internal" href="apiref.html#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> should be explicitly used.</p>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<dt><strong>Maximum encoder indentation depth</strong></dt>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<dd>The maximum argument of the <tt class="docutils literal"><span class="pre">JSON_INDENT()</span></tt> macro has been
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzchanged from 255 to 31, to free up bits from the <tt class="docutils literal"><span class="pre">flags</span></tt>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzparameter of <a class="reference internal" href="apiref.html#c.json_dumps" title="json_dumps"><tt class="xref c c-func docutils literal"><span class="pre">json_dumps()</span></tt></a>, <a class="reference internal" href="apiref.html#c.json_dumpf" title="json_dumpf"><tt class="xref c c-func docutils literal"><span class="pre">json_dumpf()</span></tt></a> and
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<a class="reference internal" href="apiref.html#c.json_dump_file" title="json_dump_file"><tt class="xref c c-func docutils literal"><span class="pre">json_dump_file()</span></tt></a>. If your code uses a bigger indentation
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzthan 31, it needs to be changed.</dd>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<dt><strong>Unsigned integers in API functions</strong></dt>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<dd>Version 2.0 unifies unsigned integer usage in the API. All uses of
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<tt class="xref c c-type docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt> and <tt class="xref c c-type docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt> have been replaced
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzwith <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>. This includes flags, container sizes, etc.
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzThis should not require source code changes, as both
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<tt class="xref c c-type docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt> and <tt class="xref c c-type docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt> are usually
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruzcompatible with <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>.</dd>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<li><a class="reference internal" href="#">Upgrading from 1.x</a><ul>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<li><a class="reference internal" href="#compatibility">Compatibility</a></li>
a556f5c62c0487ed9fb81094b1c6bba62b8f2803joncruz<li><a class="reference internal" href="#list-of-incompatible-changes">List of Incompatible Changes</a></li>
56881241fa725984d8184455e3f0c1b6de305c6bmental <form class="search" action="search.html" method="get">
56881241fa725984d8184455e3f0c1b6de305c6bmental <input type="hidden" name="check_keywords" value="yes" />
410db19c3e005769ef7dbf538a5b5fa5f0b5b88ejoncruz Enter search terms or a module, class or function name.
56881241fa725984d8184455e3f0c1b6de305c6bmental<script type="text/javascript">$('#searchbox').show(0);</script>
0832343fd7f087d3b718bc86f2cf74014e56b582joncruz <a href="gettingstarted.html" title="Getting Started"
0832343fd7f087d3b718bc86f2cf74014e56b582joncruz <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
0801db25a73ad5948af5f492113b6c2b72df4d57joncruz © Copyright 2009-2014, Petri Lehtinen.
0801db25a73ad5948af5f492113b6c2b72df4d57joncruz Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.