upgrading.html revision 4139
2N/A<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2N/A "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2N/A
2N/A
2N/A<html xmlns="http://www.w3.org/1999/xhtml">
2N/A <head>
2N/A <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
2N/A
2N/A <title>Upgrading from 1.x &mdash; Jansson 2.7 documentation</title>
2N/A
2N/A <link rel="stylesheet" href="_static/default.css" type="text/css" />
2N/A <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
2N/A
2N/A <script type="text/javascript">
2N/A var DOCUMENTATION_OPTIONS = {
2N/A URL_ROOT: './',
2N/A VERSION: '2.7',
2N/A COLLAPSE_INDEX: false,
2N/A FILE_SUFFIX: '.html',
2N/A HAS_SOURCE: true
58N/A };
2N/A </script>
2N/A <script type="text/javascript" src="_static/jquery.js"></script>
2N/A <script type="text/javascript" src="_static/underscore.js"></script>
2N/A <script type="text/javascript" src="_static/doctools.js"></script>
23N/A <link rel="top" title="Jansson 2.7 documentation" href="index.html" />
23N/A <link rel="next" title="Tutorial" href="tutorial.html" />
23N/A <link rel="prev" title="Getting Started" href="gettingstarted.html" />
23N/A </head>
23N/A <body>
32N/A <div class="related">
32N/A <h3>Navigation</h3>
32N/A <ul>
34N/A <li class="right" style="margin-right: 10px">
32N/A <a href="genindex.html" title="General Index"
34N/A accesskey="I">index</a></li>
32N/A <li class="right" >
32N/A <a href="tutorial.html" title="Tutorial"
58N/A accesskey="N">next</a> |</li>
32N/A <li class="right" >
225N/A <a href="gettingstarted.html" title="Getting Started"
225N/A accesskey="P">previous</a> |</li>
225N/A <li><a href="index.html">Jansson 2.7 documentation</a> &raquo;</li>
225N/A </ul>
225N/A </div>
225N/A
225N/A <div class="document">
225N/A <div class="documentwrapper">
225N/A <div class="bodywrapper">
225N/A <div class="body">
2N/A
38N/A <div class="section" id="upgrading-from-1-x">
38N/A<h1>Upgrading from 1.x<a class="headerlink" href="#upgrading-from-1-x" title="Permalink to this headline">¶</a></h1>
38N/A<p>This chapter lists the backwards incompatible changes introduced in
38N/AJansson 2.0, and the steps that are needed for upgrading your code.</p>
38N/A<p><strong>The incompatibilities are not dramatic.</strong> The biggest change is that
38N/Aall decoding functions now require and extra parameter. Most programs
38N/Acan be modified to work with 2.0 by adding a <tt class="docutils literal"><span class="pre">0</span></tt> as the second
83N/Aparameter 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>
83N/Aand <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>
99N/A<div class="section" id="compatibility">
2N/A<h2>Compatibility<a class="headerlink" href="#compatibility" title="Permalink to this headline">¶</a></h2>
92N/A<p>Jansson 2.0 is backwards incompatible with the Jansson 1.x releases.
92N/AIt is ABI incompatible, i.e. all programs dynamically linking to the
92N/AJansson library need to be recompiled. It&#8217;s also API incompatible,
2N/Ai.e. the source code of programs using Jansson 1.x may need
2N/Amodifications to make them compile against Jansson 2.0.</p>
313N/A<p>All the 2.x releases are guaranteed to be backwards compatible for
2N/Aboth ABI and API, so no recompilation or source changes are needed
34N/Awhen upgrading from 2.x to 2.y.</p>
2N/A</div>
313N/A<div class="section" id="list-of-incompatible-changes">
313N/A<h2>List of Incompatible Changes<a class="headerlink" href="#list-of-incompatible-changes" title="Permalink to this headline">¶</a></h2>
313N/A<dl class="docutils">
34N/A<dt><strong>Decoding flags</strong></dt>
2N/A<dd><p class="first">For future needs, a <tt class="docutils literal"><span class="pre">flags</span></tt> parameter was added as the second
313N/Aparameter 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>,
53N/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> 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
34N/Athese functions need to be changed by adding a <tt class="docutils literal"><span class="pre">0</span></tt> as the second
70N/Aargument. For example:</p>
2N/A<div class="last highlight-c"><div class="highlight"><pre><span class="cm">/* old code */</span>
2N/A<span class="n">json_loads</span><span class="p">(</span><span class="n">input</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">error</span><span class="p">);</span>
2N/A
2N/A<span class="cm">/* new code */</span>
70N/A<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">&amp;</span><span class="n">error</span><span class="p">);</span>
105N/A</pre></div>
105N/A</div>
2N/A</dd>
70N/A<dt><strong>Underlying type of JSON integers</strong></dt>
70N/A<dd><p class="first">The underlying C type of JSON integers has been changed from
70N/A<tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> to the widest available signed integer type, i.e.
528N/A<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
70N/A<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
70N/Athe whole 64-bit integer range available on most modern systems.</p>
70N/A<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
70N/Ainteger type. <tt class="xref c c-type docutils literal"><span class="pre">int</span></tt> should still be used in most cases when
70N/Adealing with smallish JSON integers, as the compiler handles
70N/Aimplicit type coercion. Only when the full 64-bit range is needed,
6N/A<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>
6N/A</dd>
6N/A<dt><strong>Maximum encoder indentation depth</strong></dt>
34N/A<dd>The maximum argument of the <tt class="docutils literal"><span class="pre">JSON_INDENT()</span></tt> macro has been
34N/Achanged from 255 to 31, to free up bits from the <tt class="docutils literal"><span class="pre">flags</span></tt>
34N/Aparameter 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
34N/A<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
34N/Athan 31, it needs to be changed.</dd>
34N/A<dt><strong>Unsigned integers in API functions</strong></dt>
34N/A<dd>Version 2.0 unifies unsigned integer usage in the API. All uses of
313N/A<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
38N/Awith <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>. This includes flags, container sizes, etc.
34N/AThis should not require source code changes, as both
38N/A<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
34N/Acompatible with <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>.</dd>
92N/A</dl>
145N/A</div>
500N/A</div>
500N/A
500N/A
500N/A </div>
500N/A </div>
500N/A </div>
500N/A <div class="sphinxsidebar">
92N/A <div class="sphinxsidebarwrapper">
92N/A <h3><a href="index.html">Table Of Contents</a></h3>
92N/A <ul>
92N/A<li><a class="reference internal" href="#">Upgrading from 1.x</a><ul>
92N/A<li><a class="reference internal" href="#compatibility">Compatibility</a></li>
92N/A<li><a class="reference internal" href="#list-of-incompatible-changes">List of Incompatible Changes</a></li>
92N/A</ul>
92N/A</li>
313N/A</ul>
38N/A
34N/A <h4>Previous topic</h4>
38N/A <p class="topless"><a href="gettingstarted.html"
32N/A title="previous chapter">Getting Started</a></p>
2N/A <h4>Next topic</h4>
<p class="topless"><a href="tutorial.html"
title="next chapter">Tutorial</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/upgrading.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="tutorial.html" title="Tutorial"
>next</a> |</li>
<li class="right" >
<a href="gettingstarted.html" title="Getting Started"
>previous</a> |</li>
<li><a href="index.html">Jansson 2.7 documentation</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2009-2014, Petri Lehtinen.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>