94318890c0
Use double-backtick quoting instead. It has the same effect (because these links had nowhere to link to) but it does not result in loud warnings about broken references by default with Sphinx-3.x.
77 lines
2.9 KiB
ReStructuredText
77 lines
2.9 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
******************
|
|
Upgrading from 1.x
|
|
******************
|
|
|
|
This chapter lists the backwards incompatible changes introduced in
|
|
Jansson 2.0, and the steps that are needed for upgrading your code.
|
|
|
|
**The incompatibilities are not dramatic.** The biggest change is that
|
|
all decoding functions now require and extra parameter. Most programs
|
|
can be modified to work with 2.0 by adding a ``0`` as the second
|
|
parameter to all calls of :func:`json_loads()`, :func:`json_loadf()`
|
|
and :func:`json_load_file()`.
|
|
|
|
|
|
Compatibility
|
|
=============
|
|
|
|
Jansson 2.0 is backwards incompatible with the Jansson 1.x releases.
|
|
It is ABI incompatible, i.e. all programs dynamically linking to the
|
|
Jansson library need to be recompiled. It's also API incompatible,
|
|
i.e. the source code of programs using Jansson 1.x may need
|
|
modifications to make them compile against Jansson 2.0.
|
|
|
|
All the 2.x releases are guaranteed to be backwards compatible for
|
|
both ABI and API, so no recompilation or source changes are needed
|
|
when upgrading from 2.x to 2.y.
|
|
|
|
|
|
List of Incompatible Changes
|
|
============================
|
|
|
|
**Decoding flags**
|
|
For future needs, a ``flags`` parameter was added as the second
|
|
parameter to all decoding functions, i.e. :func:`json_loads()`,
|
|
:func:`json_loadf()` and :func:`json_load_file()`. All calls to
|
|
these functions need to be changed by adding a ``0`` as the second
|
|
argument. For example::
|
|
|
|
/* old code */
|
|
json_loads(input, &error);
|
|
|
|
/* new code */
|
|
json_loads(input, 0, &error);
|
|
|
|
|
|
**Underlying type of JSON integers**
|
|
The underlying C type of JSON integers has been changed from
|
|
``int`` to the widest available signed integer type, i.e.
|
|
``long long`` or ``long``, depending on whether
|
|
``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. ``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
|
|
``unsigned int`` and ``unsigned long`` have been replaced
|
|
with ``size_t``. This includes flags, container sizes, etc.
|
|
This should not require source code changes, as both
|
|
``unsigned int`` and ``unsigned long`` are usually
|
|
compatible with ``size_t``.
|