From 53bc9d8a39a440d6cbd70c139bff4ae67787b8eb Mon Sep 17 00:00:00 2001 From: Petri Lehtinen Date: Thu, 24 Feb 2011 22:15:13 +0200 Subject: [PATCH] Add "Upgrading from older releases" to docs, tweak CHANGES a bit --- CHANGES | 18 ++++++------- doc/index.rst | 1 + doc/upgrading.rst | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 86 insertions(+), 9 deletions(-) create mode 100644 doc/upgrading.rst diff --git a/CHANGES b/CHANGES index c2e393b..cf4f5a3 100644 --- a/CHANGES +++ b/CHANGES @@ -2,8 +2,8 @@ Version 2.0 (in development) ============================ This release is backwards incompatible with the 1.x release series. -See the documentation for instructions on how to port existing code to -Jansson 2.0. +See the chapter "Upgrading from older versions" in documentation for +details. * Backwards incompatible changes: @@ -14,7 +14,7 @@ Jansson 2.0. type available, i.e. long long if it's supported, otherwise long. Add a typedef json_int_t that defines the type. - - Change the maximum indentation depth to 32 spaces in encoder. This + - Change the maximum indentation depth to 31 spaces in encoder. This frees up bits from the flags parameter of encoding functions `json_dumpf()`, `json_dumps()` and `json_dump_file()`. @@ -23,8 +23,8 @@ Jansson 2.0. * New features - - `json_pack()`, `json_pack_ex()`, `json_vpack_ex()`: Create complex - JSON values based on a format string. + - `json_pack()`, `json_pack_ex()`, `json_vpack_ex()`: Create JSON + values based on a format string. - `json_unpack()`, `json_unpack_ex()`, `json_vunpack_ex()`: Simple value extraction and validation functionality based on a format @@ -33,12 +33,12 @@ Jansson 2.0. - Add column, position and source fields to the ``json_error_t`` struct. - - Report the error context for UTF-8 decoding errors in the decoder. + - Enhance error reporting in the decoder. - - Add preprocessor constants that define the library version. + - ``JANSSON_VERSION`` et al.: Preprocessor constants that define the + library version. - - Add API for setting custom memory allocation functions: - `json_set_alloc_funcs()`. + - `json_set_alloc_funcs()`: Set custom memory allocation functions. * Fix many portability issues, especially on Windows. diff --git a/doc/index.rst b/doc/index.rst index c7321df..b5a3be8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -33,6 +33,7 @@ Contents :maxdepth: 2 gettingstarted + upgrading tutorial conformance apiref diff --git a/doc/upgrading.rst b/doc/upgrading.rst new file mode 100644 index 0000000..0f73a75 --- /dev/null +++ b/doc/upgrading.rst @@ -0,0 +1,76 @@ +.. highlight:: c + +***************************** +Upgrading from older versions +***************************** + +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 + :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`. -- 2.1.4