1.. highlight:: c 2 3****************** 4Upgrading from 1.x 5****************** 6 7This chapter lists the backwards incompatible changes introduced in 8Jansson 2.0, and the steps that are needed for upgrading your code. 9 10**The incompatibilities are not dramatic.** The biggest change is that 11all decoding functions now require and extra parameter. Most programs 12can be modified to work with 2.0 by adding a ``0`` as the second 13parameter to all calls of :func:`json_loads()`, :func:`json_loadf()` 14and :func:`json_load_file()`. 15 16 17Compatibility 18============= 19 20Jansson 2.0 is backwards incompatible with the Jansson 1.x releases. 21It is ABI incompatible, i.e. all programs dynamically linking to the 22Jansson library need to be recompiled. It's also API incompatible, 23i.e. the source code of programs using Jansson 1.x may need 24modifications to make them compile against Jansson 2.0. 25 26All the 2.x releases are guaranteed to be backwards compatible for 27both ABI and API, so no recompilation or source changes are needed 28when upgrading from 2.x to 2.y. 29 30 31List of Incompatible Changes 32============================ 33 34**Decoding flags** 35 For future needs, a ``flags`` parameter was added as the second 36 parameter to all decoding functions, i.e. :func:`json_loads()`, 37 :func:`json_loadf()` and :func:`json_load_file()`. All calls to 38 these functions need to be changed by adding a ``0`` as the second 39 argument. For example:: 40 41 /* old code */ 42 json_loads(input, &error); 43 44 /* new code */ 45 json_loads(input, 0, &error); 46 47 48**Underlying type of JSON integers** 49 The underlying C type of JSON integers has been changed from 50 :type:`int` to the widest available signed integer type, i.e. 51 :type:`long long` or :type:`long`, depending on whether 52 :type:`long long` is supported on your system or not. This makes 53 the whole 64-bit integer range available on most modern systems. 54 55 ``jansson.h`` has a typedef :type:`json_int_t` to the underlying 56 integer type. :type:`int` should still be used in most cases when 57 dealing with smallish JSON integers, as the compiler handles 58 implicit type coercion. Only when the full 64-bit range is needed, 59 :type:`json_int_t` should be explicitly used. 60 61 62**Maximum encoder indentation depth** 63 The maximum argument of the ``JSON_INDENT()`` macro has been 64 changed from 255 to 31, to free up bits from the ``flags`` 65 parameter of :func:`json_dumps()`, :func:`json_dumpf()` and 66 :func:`json_dump_file()`. If your code uses a bigger indentation 67 than 31, it needs to be changed. 68 69 70**Unsigned integers in API functions** 71 Version 2.0 unifies unsigned integer usage in the API. All uses of 72 :type:`unsigned int` and :type:`unsigned long` have been replaced 73 with :type:`size_t`. This includes flags, container sizes, etc. 74 This should not require source code changes, as both 75 :type:`unsigned int` and :type:`unsigned long` are usually 76 compatible with :type:`size_t`. 77