|
1 .. highlight:: c |
|
2 |
|
3 ****************** |
|
4 Upgrading from 1.x |
|
5 ****************** |
|
6 |
|
7 This chapter lists the backwards incompatible changes introduced in |
|
8 Jansson 2.0, and the steps that are needed for upgrading your code. |
|
9 |
|
10 **The incompatibilities are not dramatic.** The biggest change is that |
|
11 all decoding functions now require and extra parameter. Most programs |
|
12 can be modified to work with 2.0 by adding a ``0`` as the second |
|
13 parameter to all calls of :func:`json_loads()`, :func:`json_loadf()` |
|
14 and :func:`json_load_file()`. |
|
15 |
|
16 |
|
17 Compatibility |
|
18 ============= |
|
19 |
|
20 Jansson 2.0 is backwards incompatible with the Jansson 1.x releases. |
|
21 It is ABI incompatible, i.e. all programs dynamically linking to the |
|
22 Jansson library need to be recompiled. It's also API incompatible, |
|
23 i.e. the source code of programs using Jansson 1.x may need |
|
24 modifications to make them compile against Jansson 2.0. |
|
25 |
|
26 All the 2.x releases are guaranteed to be backwards compatible for |
|
27 both ABI and API, so no recompilation or source changes are needed |
|
28 when upgrading from 2.x to 2.y. |
|
29 |
|
30 |
|
31 List 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`. |