upgrading.html revision 3421
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai <title>Upgrading from 1.x — Jansson 2.7 documentation</title>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <link rel="stylesheet" href="_static/default.css" type="text/css" />
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai var DOCUMENTATION_OPTIONS = {
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai URL_ROOT: './',
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai VERSION: '2.7',
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai COLLAPSE_INDEX: false,
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai FILE_SUFFIX: '.html',
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai HAS_SOURCE: true
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <script type="text/javascript" src="_static/jquery.js"></script>
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai <script type="text/javascript" src="_static/underscore.js"></script>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <script type="text/javascript" src="_static/doctools.js"></script>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <link rel="top" title="Jansson 2.7 documentation" href="index.html" />
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <link rel="next" title="Tutorial" href="tutorial.html" />
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <link rel="prev" title="Getting Started" href="gettingstarted.html" />
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <a href="gettingstarted.html" title="Getting Started"
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<h1>Upgrading from 1.x<a class="headerlink" href="#upgrading-from-1-x" title="Permalink to this headline">ΒΆ</a></h1>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<p>This chapter lists the backwards incompatible changes introduced in
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen DesaiJansson 2.0, and the steps that are needed for upgrading your code.</p>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<p><strong>The incompatibilities are not dramatic.</strong> The biggest change is that
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiall decoding functions now require and extra parameter. Most programs
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaican be modified to work with 2.0 by adding a <tt class="docutils literal"><span class="pre">0</span></tt> as the second
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiparameter 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>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiand <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>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<h2>Compatibility<a class="headerlink" href="#compatibility" title="Permalink to this headline">ΒΆ</a></h2>
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai<p>Jansson 2.0 is backwards incompatible with the Jansson 1.x releases.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen DesaiIt is ABI incompatible, i.e. all programs dynamically linking to the
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen DesaiJansson library need to be recompiled. It’s also API incompatible,
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaii.e. the source code of programs using Jansson 1.x may need
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaimodifications to make them compile against Jansson 2.0.</p>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<p>All the 2.x releases are guaranteed to be backwards compatible for
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiboth ABI and API, so no recompilation or source changes are needed
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<div class="section" id="list-of-incompatible-changes">
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<h2>List of Incompatible Changes<a class="headerlink" href="#list-of-incompatible-changes" title="Permalink to this headline">ΒΆ</a></h2>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<dd><p class="first">For future needs, a <tt class="docutils literal"><span class="pre">flags</span></tt> parameter was added as the second
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiparameter 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>,
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaithese functions need to be changed by adding a <tt class="docutils literal"><span class="pre">0</span></tt> as the second
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiargument. For example:</p>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<div class="last highlight-c"><div class="highlight"><pre><span class="cm">/* old code */</span>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<dt><strong>Underlying type of JSON integers</strong></dt>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<dd><p class="first">The underlying C type of JSON integers has been changed from
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> to the widest available signed integer type, i.e.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaithe whole 64-bit integer range available on most modern systems.</p>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiinteger type. <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> should still be used in most cases when
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaidealing with smallish JSON integers, as the compiler handles
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiimplicit type coercion. Only when the full 64-bit range is needed,
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<dt><strong>Maximum encoder indentation depth</strong></dt>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<dd>The maximum argument of the <tt class="docutils literal"><span class="pre">JSON_INDENT()</span></tt> macro has been
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaichanged from 255 to 31, to free up bits from the <tt class="docutils literal"><span class="pre">flags</span></tt>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiparameter 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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaithan 31, it needs to be changed.</dd>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<dt><strong>Unsigned integers in API functions</strong></dt>
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai<dd>Version 2.0 unifies unsigned integer usage in the API. All uses of
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaiwith <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>. This includes flags, container sizes, etc.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen DesaiThis should not require source code changes, as both
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<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
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desaicompatible with <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>.</dd>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <h3><a href="index.html">Table Of Contents</a></h3>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<li><a class="reference internal" href="#">Upgrading from 1.x</a><ul>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<li><a class="reference internal" href="#compatibility">Compatibility</a></li>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<li><a class="reference internal" href="#list-of-incompatible-changes">List of Incompatible Changes</a></li>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <p class="topless"><a href="gettingstarted.html"
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai title="previous chapter">Getting Started</a></p>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <form class="search" action="search.html" method="get">
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai <input type="hidden" name="check_keywords" value="yes" />
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <input type="hidden" name="area" value="default" />
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai Enter search terms or a module, class or function name.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai<script type="text/javascript">$('#searchbox').show(0);</script>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <a href="gettingstarted.html" title="Getting Started"
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai © Copyright 2009-2014, Petri Lehtinen.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.