"Fossies" - the Fresh Open Source Software Archive

Member "jansson-2.14/doc/upgrading.rst" (19 Nov 2020, 2935 Bytes) of package /linux/www/jansson-2.14.tar.bz2:

    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     ``int`` to the widest available signed integer type, i.e.
   51     ``long long`` or ``long``, depending on whether
   52     ``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. ``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     ``unsigned int`` and ``unsigned long`` have been replaced
   73     with ``size_t``. This includes flags, container sizes, etc.
   74     This should not require source code changes, as both
   75     ``unsigned int`` and ``unsigned long`` are usually
   76     compatible with ``size_t``.