a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley.. highlight:: c

f41f183f628a148860a6d1f0070208cddd45b0c6Bob Halley

f41f183f628a148860a6d1f0070208cddd45b0c6Bob Halley******************

f41f183f628a148860a6d1f0070208cddd45b0c6Bob HalleyUpgrading from 1.x

f41f183f628a148860a6d1f0070208cddd45b0c6Bob Halley******************

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyThis chapter lists the backwards incompatible changes introduced in

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyJansson 2.0, and the steps that are needed for upgrading your code.

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley**The incompatibilities are not dramatic.** The biggest change is that

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleyall decoding functions now require and extra parameter. Most programs

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleycan be modified to work with 2.0 by adding a ``0`` as the second

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleyparameter to all calls of :func:`json_loads()`, :func:`json_loadf()`

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleyand :func:`json_load_file()`.

5a2f873360de2653816d985144871ffcc3753cd0David Lawrence

ffe74cc719aa0f10c38fbc1f2f3ea7db0960cb8fMark Andrews

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyCompatibility

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley=============

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyJansson 2.0 is backwards incompatible with the Jansson 1.x releases.

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyIt is ABI incompatible, i.e. all programs dynamically linking to the

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyJansson library need to be recompiled. It's also API incompatible,

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleyi.e. the source code of programs using Jansson 1.x may need

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleymodifications to make them compile against Jansson 2.0.

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyAll the 2.x releases are guaranteed to be backwards compatible for

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleyboth ABI and API, so no recompilation or source changes are needed

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halleywhen upgrading from 2.x to 2.y.

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob HalleyList of Incompatible Changes

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley============================

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley**Decoding flags**

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley For future needs, a ``flags`` parameter was added as the second

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley parameter to all decoding functions, i.e. :func:`json_loads()`,

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley :func:`json_loadf()` and :func:`json_load_file()`. All calls to

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley these functions need to be changed by adding a ``0`` as the second

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley argument. For example::

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley

4880900113e4d0f17884f3fbdbf4c302e3f9ea91Bob Halley /* old code */

a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley json_loads(input, &error);

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews /* new code */

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews json_loads(input, 0, &error);

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews**Underlying type of JSON integers**

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews The underlying C type of JSON integers has been changed from

5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews :type:`int` to the widest available signed integer type, i.e.

:type:`long long` or :type:`long`, depending on whether

:type:`long long` is supported on your system or not. This makes

the whole 64-bit integer range available on most modern systems.

``jansson.h`` has a typedef :type:`json_int_t` to the underlying

integer type. :type:`int` should still be used in most cases when

dealing with smallish JSON integers, as the compiler handles

implicit type coercion. Only when the full 64-bit range is needed,

:type:`json_int_t` should be explicitly used.

**Maximum encoder indentation depth**

The maximum argument of the ``JSON_INDENT()`` macro has been

changed from 255 to 31, to free up bits from the ``flags``

parameter of :func:`json_dumps()`, :func:`json_dumpf()` and

:func:`json_dump_file()`. If your code uses a bigger indentation

than 31, it needs to be changed.

**Unsigned integers in API functions**

Version 2.0 unifies unsigned integer usage in the API. All uses of

:type:`unsigned int` and :type:`unsigned long` have been replaced

with :type:`size_t`. This includes flags, container sizes, etc.

This should not require source code changes, as both

:type:`unsigned int` and :type:`unsigned long` are usually

compatible with :type:`size_t`.