Changes in Jansson — Jansson 2.11 documentation

# Changes in Jansson

## Version 2.11

Released 2018-02-09

- New features:
  - Add `json_pack()` format specifiers s*, o* and O* for values that can be omitted if null (#339).
  - Add `json_error_code()` to retrieve numeric error codes (#365, #380, #381).
  - Enable thread safety for `json_dump()` on all systems. Enable thread safe `json_decref()` and `json_incref()` for modern compilers (#389).
  - Add `json_sprintf()` and `json_vsprintf()` (#393).
- Bug Fixes:
  - Fix incorrect report of success from `json_dump_file()` when an error is returned by `fclose()` (#359).
  - Make json_equal() const-correct (#344).
  - Fix incomplete stealing of references by `json_pack()` (#374).
- Build:
  - Work around gcc’s -Wimplicit-fallthrough.
  - Fix CMake detection of `sys/types.h()` header (#375).
  - Fix `jansson.pc()` generated by CMake to be more consistent with the one generated using GNU Autotools (#368).
- Other:
  - Miscellaneous documentation fixes (#356, #378, #395).
  - Remove unnecessary reference actions from parsers (#377).

## Version 2.10

Released 2017-03-02

- New features:
  - Add JSON_EMBED encoding flag allowing arrays and objects to be encoded into existing streams (#329).
  - Add `json_dumpb()` function for dumping to a pre-allocated buffer (#328).
  - Add `json_dumpfd()` and `json_loadfd()` functions for dumping to streaming file descriptors (#328).
  - Add support for parsing buffers larger than 2GB (#309).
- Build:
  - Fix CMake build when LONG_LONG_INT is defined as “” (#321)
- Other:
  - Internal code cleanup (#311, #314)

## Version 2.9

Released 2016-09-18

- New features:
  - Add `json_auto_t` to automatically decref a value that goes out of scope. Available only on GCC and Clang. (#301)
- Build:
  - Fix CMake build (at least on Linux) by removing conflicting jansson_config.h from the distribution (#306)
  - Change CMake install target generation to be optional (#305)
- Documentation:
  - Small documentation fixes.

## Version 2.8

Released 2016-08-30

- New features:
  - Always preserve insertion order of object items. `json_object_iter()` and friends, `json_object_foreach()` and `json_dumps()` and friends now always work in the insertion order of object items (#293).
  - Add `json_object_foreach_safe()` macro that allows `json_object_del()` calls during iteration (#230).
  - Add `json_get_alloc_funcs()` to allow reading the allocation functions set by `json_set_alloc_funcs()` (#262, #264).
  - Add `json_pack()` format specifiers s?, o? and O? for values that can be null (#261, #270).
- Bug fixes:
  - Fix a crash when parsing inputs consisting of very deeply nested arrays or objects (#282, #284).
  - Never convert numbers to integers in the parser when JSON_DECODE_INT_AS_REAL is set. This fixes error messages for overflowing numbers when JSON_DECODE_INT_AS_REAL is set (#212).
  - Fix a use-after-free in `json_pack()` error handling.
  - Fix subnormal number parsing on mingw32.
  - Handle out-of-memory situations gracefully in the hashtable implementation (#298).
- Build:
  - Fix build with CMake on all versions of Visual Studio up to 2015 (#262, #289).
  - Fix pkgconfig libdir when using CMake (#268).
  - Fix CMake config for static CRT builds on Windows (#206).
  - Fix warnings on LLVM 6.0 targeting iOS arm64 (#208).
  - Add coverlls.io support via Travis for a nice test coverage badge (#211).
  - Don’t expect `jansson_config.h` to be in the compiler’s include path (#209).
  - Add a build-time option to set initial hashtable size (#213).
  - Use snprintf and strncpy in place of sprintf and strcpy to silence linker warnings on OpenBSD (#233).
- Documentation:
  - Fix various typos in documentation, and a broken link (#258).
  - Add an example program in `examples/` (#214, #217).
  - Fix building of documentation man pages (#207).
  - Document the fact that copying objects doesn’t preserve the insertion order of keys (#237).
- Tests:
  - Don’t use the nonstandard __FUNCTION__ macro in tests.
  - Use expr instead of $((…)) in shell scripts for Solaris 10 compatibility.
  - Disable Visual Studio warning C4756 when triggered deliberately in tests (#216).
  - Other minor fixes (#221, #248).
- Other changes:
  - List all unrecognized object keys when strict unpacking fails (#263).
  - Alter the order of the members of the hashtable_pair struct for easier debugging.
  - Minor performance improvement to `json_dump()` and friends (#234).
  - Minor style fixes (#255, #257).

## Version 2.7

Released 2014-10-02

- New features:
  - `json_pack()` and friends: Add format specifiers `s%` and `+%` for a size_t string length (#141).
  - `json_unpack()` and friends: Add format specifier `s%` for unpacking the string length along with the string itself (#141).
  - Add length-aware string constructors `json_stringn()` and `json_stringn_nocheck()`, length-aware string mutators `json_string_setn()` and `json_string_setn_nocheck()`, and a function for getting string’s length `json_string_length()` (#141, #143).
  - Support `\u0000` escapes in the decoder. The support can be enabled by using the `JSON_ALLOW_NUL` decoding flag (#141).
  - Add `json_boolean_value()` as an alias for `json_is_true()` (#146).
  - Add JSON_REAL_PRECISION encoding flag/macro for controlling real number precision (#178).
  - Define the maximum indentation as JSON_MAX_INDENT (#191).
- Bug fixes:
  - Some malformed `\uNNNN` escapes could crash the decoder with an assertion failure.
  - Avoid integer overflows with very long strings in UTF-8 decoder and hashtable.
  - Check for NULL key in `json_object_get()` and `json_object_del()` (#151).
  - Enhance hashtable seeding on Windows (#162).
  - `json_unpack()`: Allow mixing JSON_STRICT with optional keys (#162, #163).
  - Fix int/int32 mismatch (#142).
  - Parse subnormal numbers correctly (#202).
- Build:
  - Remove VS2010 build files. CMake should be used on Windows instead (#165).
  - Fix CMake build flags for MinGW (#193).
  - Add CMake config files for find_package. Rename config.h to jansson_private_config.h (#157, #159).
  - Make Valgrind checks work with CMake (#160).
  - Fix feature checks to use correct __ATOMIC flags.
  - Fix CMake checks for uint16_t and uint8_t support (#177).
  - Make Jansson build on SmartOS/Solaris (#171).
  - Work around a GCC bug on Solaris (#175).
  - Fix autoreconf on Debian (#182).
  - Don’t use GNU make specific export for global AM_CFLAGS (#203, #204).
  - Fix building on Android using the supplied Android.mk (#166, #174).
  - Android.mk: Add -DHAVE_STDINT_H to LOCAL_CFLAGS (#200).
- Documentation:
  - Document JANSSON_BUILD_SHARED_LIBS CMake option (#187).
- Tests:
  - Close file handles correctly (#198).
- Other changes:
  - `\uNNNN` escapes are now encoded in upper case for better readability.
  - Enable usage of AddressSanitizer (#180).

## Version 2.6

Released 2014-02-11

- Security:
  - CVE-2013-6401: The hash function used by the hashtable implementation has been changed, and is automatically seeded with random data when the first JSON object is created. This prevents an attacker from causing large JSON objects with specially crafted keys perform poorly.
- New features:
  - `json_object_seed()`: Set the seed value of the hash function.
- Bug fixes:
  - Include CMake specific files in the release tarball.
- Documentation:
  - Fix tutorial source to send a User-Agent header, which is now required by the GitHub API.
  - Set all memory to zero in secure_free() example.

## Version 2.5

Released 2013-09-19

- New features:
  - `json_pack()` and friends: Add format specifiers `s#`, `+` and `+#`.
  - Add `JSON_DECODE_INT_AS_REAL` decoding flag to treat all numbers as real in the decoder (#123).
  - Add `json_array_foreach()`, paralleling `json_object_foreach()` (#118).
- Bug fixes:
  - `json_dumps()` and friends: Don’t crash if json is NULL and `JSON_ENCODE_ANY` is set.
  - Fix a theoretical integer overflow in `jsonp_strdup()`.
  - Fix `l_isxdigit()` macro (#97).
  - Fix an off-by-one error in `json_array_remove()`.
- Build:
  - Support CMake in addition to GNU Autotools (#106, #107, #112, #115, #120, #127).
  - Support building for Android (#109).
  - Don’t use `-Werror` by default.
  - Support building and testing with VPATH (#93).
  - Fix compilation when `NDEBUG` is defined (#128)
- Tests:
  - Fix a refleak in `test/bin/json_process.c`.
- Documentation:
  - Clarify the return value of `json_load_callback_t()`.
  - Document how to circumvent problems with separate heaps on Windows.
  - Fix memory leaks and warnings in `github_commits.c`.
  - Use `json_decref()` properly in tutorial.
- Other:
  - Make it possible to forward declare `struct json_t`.

## Version 2.4

Released 2012-09-23

- New features:
  - Add `json_boolean()` macro that returns the JSON true or false value based on its argument (#86).
  - Add `json_load_callback()` that calls a callback function repeatedly to read the JSON input (#57).
  - Add JSON_ESCAPE_SLASH encoding flag to escape all occurences of `/` with `\/`.
- Bug fixes:
  - Check for and reject NaN and Inf values for reals. Encoding these values resulted in invalid JSON.
  - Fix `json_real_set()` to return -1 on error.
- Build:
  - Jansson now builds on Windows with Visual Studio 2010, and includes solution and project files in `win32/vs2010/` directory.
  - Fix build warnings (#77, #78).
  - Add `-no-undefined` to LDFLAGS (#90).
- Tests:
  - Fix the symbol exports test on Linux/PPC64 (#88).
- Documentation:
  - Fix typos (#73, #84).

## Version 2.3.1

Released 2012-04-20

- Build issues:
  - Only use `long long` if `strtoll()` is also available.
- Documentation:
  - Fix the names of library version constants in documentation. (#52)
  - Change the tutorial to use GitHub API v3. (#65)
- Tests:
  - Make some tests locale independent. (#51)
  - Distribute the library exports test in the tarball.
  - Make test run on shells that don’t support the `export FOO=bar` syntax.

## Version 2.3

Released 2012-01-27

- New features:
  - `json_unpack()` and friends: Add support for optional object keys with the `{s?o}` syntax.
  - Add `json_object_update_existing()` and `json_object_update_missing()`, for updating only existing keys or only adding missing keys to an object. (#37)
  - Add `json_object_foreach()` for more convenient iteration over objects. (#45, #46)
  - When decoding JSON, write the number of bytes that were read from input to `error.position` also on success. This is handy with `JSON_DISABLE_EOF_CHECK`.
  - Add support for decoding any JSON value, not just arrays or objects. The support is enabled with the new `JSON_DECODE_ANY` flag. Patch by Andrea Marchesini. (#4)
- Bug fixes
  - Avoid problems with object’s serial number growing too big. (#40, #41)
  - Decoding functions now return NULL if the first argument is NULL. Patch by Andrea Marchesini.
  - Include `jansson_config.h.win32` in the distribution tarball.
  - Remove `+` and leading zeros from exponents in the encoder. (#39)
  - Make Jansson build and work on MinGW. (#39, #38)
- Documentation
  - Note that the same JSON values must not be encoded in parallel by separate threads. (#42)
  - Document MinGW support.

## Version 2.2.1

Released 2011-10-06

- Bug fixes:
  - Fix real number encoding and decoding under non-C locales. (#32)
  - Fix identifier decoding under non-UTF-8 locales. (#35)
  - `json_load_file()`: Open the input file in binary mode for maximum compatiblity.
- Documentation:
  - Clarify the lifecycle of the result of the `s` fromat of `json_unpack()`. (#31)
  - Add some portability info. (#36)
  - Little clarifications here and there.
- Other:
  - Some style fixes, issues detected by static analyzers.

## Version 2.2

Released 2011-09-03

- New features:
  - `json_dump_callback()`: Pass the encoder output to a callback function in chunks.
- Bug fixes:
  - `json_string_set()`: Check that target is a string and value is not NULL.
- Other:
  - Documentation typo fixes and clarifications.

## Version 2.1

Released 2011-06-10

- New features:
  - `json_loadb()`: Decode a string with a given size, useful if the string is not null terminated.
  - Add `JSON_ENCODE_ANY` encoding flag to allow encoding any JSON value. By default, only arrays and objects can be encoded. (#19)
  - Add `JSON_REJECT_DUPLICATES` decoding flag to issue a decoding error if any JSON object in the input contins duplicate keys. (#3)
  - Add `JSON_DISABLE_EOF_CHECK` decoding flag to stop decoding after a valid JSON input. This allows other data after the JSON data.
- Bug fixes:
  - Fix an additional memory leak when memory allocation fails in `json_object_set()` and friends.
  - Clear errno before calling `strtod()` for better portability. (#27)
- Building:
  - Avoid set-but-not-used warning/error in a test. (#20)
- Other:
  - Minor clarifications to documentation.

## Version 2.0.1

Released 2011-03-31

- Bug fixes:
  - Replace a few `malloc()` and `free()` calls with their counterparts that support custom memory management.
  - Fix object key hashing in json_unpack() strict checking mode.
  - Fix the parentheses in `JANSSON_VERSION_HEX` macro.
  - Fix `json_object_size()` return value.
  - Fix a few compilation issues.
- Portability:
  - Enhance portability of `va_copy()`.
  - Test framework portability enhancements.
- Documentation:
  - Distribute `doc/upgrading.rst` with the source tarball.
  - Build documentation in strict mode in `make distcheck`.

## Version 2.0

Released 2011-02-28

This release is backwards incompatible with the 1.x release series. See the chapter “Upgrading from older versions” in documentation for details.

- Backwards incompatible changes:
  - Unify unsigned integer usage in the API: All occurences of unsigned int and unsigned long have been replaced with size_t.
  - Change JSON integer’s underlying type to the widest signed integer 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 31 spaces in encoder. This frees up bits from the flags parameter of encoding functions `json_dumpf()`, `json_dumps()` and `json_dump_file()`.
  - For future needs, add a flags parameter to all decoding functions `json_loadf()`, `json_loads()` and `json_load_file()`.
- New features
  - `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 string.
  - Add column, position and source fields to the `json_error_t` struct.
  - Enhance error reporting in the decoder.
  - `JANSSON_VERSION` et al.: Preprocessor constants that define the library version.
  - `json_set_alloc_funcs()`: Set custom memory allocation functions.
- Fix many portability issues, especially on Windows.
- Configuration
  - Add file `jansson_config.h` that contains site specific configuration. It’s created automatically by the configure script, or can be created by hand if the configure script cannot be used. The file `jansson_config.h.win32` can be used without modifications on Windows systems.
  - Add a section to documentation describing how to build Jansson on Windows.
  - Documentation now requires Sphinx 1.0 or newer.

## Version 1.3

Released 2010-06-13

- New functions:
  - `json_object_iter_set()`, `json_object_iter_set_new()`: Change object contents while iterating over it.
  - `json_object_iter_at()`: Return an iterator that points to a specific object item.
- New encoding flags:
  - `JSON_PRESERVE_ORDER`: Preserve the insertion order of object keys.
- Bug fixes:
  - Fix an error that occured when an array or object was first encoded as empty, then populated with some data, and then re-encoded
  - Fix the situation like above, but when the first encoding resulted in an error
- Documentation:
  - Clarify the documentation on reference stealing, providing an example usage pattern

## Version 1.2.1

Released 2010-04-03

- Bug fixes:
  - Fix reference counting on `true`, `false` and `null`
  - Estimate real number underflows in decoder with 0.0 instead of issuing an error
- Portability:
  - Make `int32_t` available on all systems
  - Support compilers that don’t have the `inline` keyword
  - Require Autoconf 2.60 (for `int32_t`)
- Tests:
  - Print test names correctly when `VERBOSE=1`
  - `test/suites/api`: Fail when a test fails
  - Enhance tests for iterators
  - Enhance tests for decoding texts that contain null bytes
- Documentation:
  - Don’t remove `changes.rst` in `make clean`
  - Add a chapter on RFC conformance

## Version 1.2

Released 2010-01-21

- New functions:
  - `json_equal()`: Test whether two JSON values are equal
  - `json_copy()` and `json_deep_copy()`: Make shallow and deep copies of JSON values
  - Add a version of all functions taking a string argument that doesn’t check for valid UTF-8: `json_string_nocheck()`, `json_string_set_nocheck()`, `json_object_set_nocheck()`, `json_object_set_new_nocheck()`
- New encoding flags:
  - `JSON_SORT_KEYS`: Sort objects by key
  - `JSON_ENSURE_ASCII`: Escape all non-ASCII Unicode characters
  - `JSON_COMPACT`: Use a compact representation with all unneeded whitespace stripped
- Bug fixes:
  - Revise and unify whitespace usage in encoder: Add spaces between array and object items, never append newline to output.
  - Remove const qualifier from the `json_t` parameter in `json_string_set()`, `json_integer_set()` and `json_real_set()`.
  - Use `int32_t` internally for representing Unicode code points (int is not enough on all platforms)
- Other changes:
  - Convert `CHANGES` (this file) to reStructured text and add it to HTML documentation
  - The test system has been refactored. Python is no longer required to run the tests.
  - Documentation can now be built by invoking `make html`
  - Support for pkg-config

## Version 1.1.3

Released 2009-12-18

- Encode reals correctly, so that first encoding and then decoding a real always produces the same value
- Don’t export private symbols in `libjansson.so`

## Version 1.1.2

Released 2009-11-08

- Fix a bug where an error message was not produced if the input file could not be opened in `json_load_file()`
- Fix an assertion failure in decoder caused by a minus sign without a digit after it
- Remove an unneeded include of `stdint.h` in `jansson.h`

## Version 1.1.1

Released 2009-10-26

- All documentation files were not distributed with v1.1; build documentation in make distcheck to prevent this in the future
- Fix v1.1 release date in `CHANGES`

## Version 1.1

Released 2009-10-20

- API additions and improvements:
  - Extend array and object APIs
  - Add functions to modify integer, real and string values
  - Improve argument validation
  - Use unsigned int instead of `uint32_t` for encoding flags
- Enhance documentation
  - Add getting started guide and tutorial
  - Fix some typos
  - General clarifications and cleanup
- Check for integer and real overflows and underflows in decoder
- Make singleton values thread-safe (`true`, `false` and `null`)
- Enhance circular reference handling
- Don’t define `-std=c99` in `AM_CFLAGS`
- Add C++ guards to `jansson.h`
- Minor performance and portability improvements
- Expand test coverage

## Version 1.0.4

Released 2009-10-11

- Relax Autoconf version requirement to 2.59
- Make Jansson compile on platforms where plain `char` is unsigned
- Fix API tests for object

## Version 1.0.3

Released 2009-09-14

- Check for integer and real overflows and underflows in decoder
- Use the Python json module for tests, or simplejson if the json module is not found
- Distribute changelog (this file)

## Version 1.0.2

Released 2009-09-08

- Handle EOF correctly in decoder

## Version 1.0.1

Released 2009-09-04

- Fixed broken `json_is_boolean()`

## Version 1.0

Released 2009-08-25

- Initial release