Release date: 2021-08-17
SHA-256: 230f3a03cefd586661ebab577a347c973d97a770afb89e22c52abc3c2a19d0a7 (json.hpp), b5e3bfad07feba218a26a4f809fbb0d1e33450524bf5d7244cabc92cf8178c69 (include.zip)
Summary
JSON for Modern C++ 3.10.0 is the first release for over a year. It contains some new features and a lot of minor changes and bug fixes.
Most notably, it introduces [**extended diagnostics.**](https://json.nlohmann.me/home/exceptions/#extended-diagnostic-messages) By defining [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/features/macros/#json_diagnostics) before including the `json.hpp`, a [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) is added to [exceptions](https://json.nlohmann.me/home/exceptions/) which helps to debug issues with object access, array indices, or mismatching types.
Another important change behind the curtains is a **fully overworked CI** which performs a lot of checks for every commit which should allow more frequent releases in the future.
All changes are backward-compatible.
:moneybag: Note you can **support this project** via [GitHub sponsors](https://github.com/sponsors/nlohmann) or [PayPal](http://paypal.me/nlohmann).
:sparkles: New Features
- Add **extended diagnostics information** by adding a [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the [exception](https://json.nlohmann.me/home/exceptions/) messages indicating the exact location of a invalid type errors or out-of-bound errors.
[json.exception.type_error.302] (/address/housenumber) type must be number, but is string
Exceptions in the library are thrown in the local context of the JSON value they are detected. This makes detailed diagnostics messages, and hence debugging, difficult. To create better diagnostics messages, each JSON value needs a pointer to its parent value such that a global context (i.e., a path from the root value to the value that lead to the exception) can be created. That global context is then provided as a JSON Pointer.
As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/features/macros/#json_diagnostics) to 1 before including `json.hpp`. See the [`documentation`](https://json.nlohmann.me/home/exceptions/#extended-diagnostic-messages) for more information. 932 1508 2562 2838 2866
- Add a [**GDB pretty printer**](https://github.com/nlohmann/json/tree/develop/third_party/gdb_pretty_printer) to facilitate reading `basic_json` values in GDB. #1952 2607
- Add a new value `store` to the [cbor_tag_handler_t](https://json.nlohmann.me/api/basic_json/cbor_tag_handler_t/) which allows to store the tags of CBOR values as binary subtypes. #2863 2908
- Add support for containers with non-default-constructible types. 2574 2576
:bug: Bug Fixes
- Fix a regression bug that failed `ordered_json` to be used when exceptions were switched off. 2347 2725 2934
- Added iterator range insertion for `ordered_json`. 2490 2512
- Change the type of binary subtypes to `std::uint64_t` to support subtypes >255. Furthermore, the return value of the `subtype()` function has been fixed to the documented value `-1` in case no subtype is given. 2863 2908
- Fix move constructor of internal `json_ref` type which created `null` values when compiled with `-fno-elide-constructors`. 2387 2405
- Fix the compilation of `input_adapter` for containers in edge cases. 2553
- Allow parsing from `std::byte` containers. 2413 2546 2550 2602 2869
- Fix memory leak in `to_json` in case a JSON value is reused. 2865 2872
- Fix compilation error in case symbol `EOF` was not found. 2755 2756
- Fix Compilation error when using `NLOHMANN_JSON_SERIALIZE_ENUM` with `ordered_json` on libc++. 2491 2825
Warnings
A lot of warnings have been fixed in this release. To make sure the library remains warning-free, the CI now breaks in case a warning is found in GCC (261 warning flags), Clang (flag `-Weverything` with 8 exceptions), or MSVC (flag `/W4`).
- Fix `-Wimplicit-fallthrough` warnings. 2348 2349
- Fix `-Wfloat-equal` warnings. 2909 2911
- Add assertions to suppress C28020 warnings. 2447
- Fix shadow warnings. 1759 2536 2444
- Fix compiler warnings in the test suite. 2537
- Fix issues found by Visual Studio Visual Assist 2615
- Fix unused parameter warning. 2646 2658 2668 2706 2707
- Remove HEDLEY annotation from `exception::what()` to fix C28204 warning. 2673 2680
- Suppress C4127 warning. 2592 2875
- Fix truncation warning. 2572 2874
- Fix useless cast warning. 1777 2114 2893 2902
- Fix unknown pragma warning. 2924 2925
- Fix `-Wswitch-enum` warnings. 2927
- Fix C4309 and C4100 warnings and treat all MSVC `/W4` warnings as error. 2930
- Suppress fewer warning flags. 2936
:zap: Improvements
Tests and CI
The CI chain has been completely overworked and now runs mostly on a dedicated [Docker Image](https://github.com/nlohmann/json-ci) that contains all relevant tools.
- Collected all CI calls in a [CMake file](https://github.com/nlohmann/json/blob/develop/cmake/ci.cmake) which can be enabled by setting `JSON_CI`.
- Linux now builds with Clang 3.5 to 12 and GCC 4.8 to 11 checking multiple C++ standards. 2540
- Windows builds with MSVC 2015 to 2019, MinGW (GCC 8), Clang 11 and 12, and Clang-CL 11 checking multiple C++ standards.
- Mac builds with Xcode 10.2.1 to Xcode 12.4 checking multiple C++ standards. 1798 2561 2737 2790 2817
- Use static analysis tools Clang-Tidy, Cppcheck, Valgrind, Google Sanitizers, Clang Static Analyzer, Cpplint, and Facebook Infer.
- Add internal checks for CMake flags, switched off exceptions, header amalgamation, self-contained headers, and exclusion of certain tests via CTest.
- Providers: Move most Travis/AppVeyor builds to GitHub Actions. Use [Drone CI](https://cloud.drone.io/nlohmann/json) for aarch64 build. Remove FOSSA. Properly select "Release" build for Travis CI builds. #2375 2689
- Remove `define private public` hack from test files. Instead, macro `JSON_PRIVATE_UNLESS_TESTED` is used in the source code which defaults to `private`, but can be set to `public` to test internals. 43 913 1985 2352
CMake
- Fixed issue in CMake file that overwrote `CMAKE_CXX_COMPILER` when the test suite was compiled. 2344 2384
- Only enable CMake options `JSON_BuildTests` and `JSON_Install` by default when the library is the main project. 2513 2514
- Add CTest label `not_reproducible` to skip non-reproducible tests. 2324 2560
- Formatted CMake files 2770
- Add a CMake option `JSON_SystemInclude` to use `SYSTEM` in `target_include_directories`. 2762
- Add CMake option `JSON_FastTests` (`OFF` by default) to which slow test suite.
Documentation
- Fixed typos in the documentation. 2354 2754
- Extended documentation for discarded values and `is_discarded()` function. 2360 2363
- Fix Markdown of README. 2582
- Fix example in README file. 2625 2659
- Fix example in parse exceptions documentation. 2679
- Overworked [documentation of number handling](https://json.nlohmann.me/features/types/number_handling/). #2747
- Add link to Conan Center package to README. 2771
- Added example for CPM.cmake. 2406
- Update README to use HTTPS everywhere. 2789
- Fixed consistency of `using` declarations in README. 2826
- Fix documentation of tests that required a Git checkout. 2845
- Fix code samples in GIF slideshow. 2457
- Update documentation to reference [RFC 8259](https://tools.ietf.org/html/rfc8259.html) as JSON standard.
- Add section on how to get support to README file.
- Replaced links to Doxygen documentation with new [API documentation](https://json.nlohmann.me/api/basic_json/).
- Documented the effect of a [bug](https://github.com/microsoft/STL/issues/2114) in Microsoft's STL that makes `what()` member function of exception objects unusable in case `_HAS_EXCEPTIONS=0` is set. #2824
Thirdparty
- Updated Hedley to version 15. 2367
- Updated Doctest to version 2.4.6. 2525 2538 2686 2687
:hammer: Further Changes
- Use C++14 constructs where available. 2533
- Fix `pkg-config.pc` generation. 2690
- Add possibility to set the C++ standard via macros `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, and `JSON_HAS_CPP_20`. By defining any of these symbols, the internal check is overridden and the provided C++ version is unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be detected incorrectly. 2730 2731 2749
- Add preprocessor symbol `JSON_NO_IO`. When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for security reasons (e.g., Intel Software Guard Extensions (SGX)). 2728 2729 2842 2861
- Benchmarks are handled via `FetchContent` and require CMake version 3.11. Removed Google Benchmark copy. Fix default branch name for Google Benchmarks. 2795 2796
- Simplify object parser for CBOR. 2879 2598
- Cleaned up maintainer Makefiles
Licensing
- Clarified license of `is_complete_type` implementation. 2534
- License fix for `integer_sequence` and `index_sequence` implementation. 2683
:fire: Deprecated functions
Passing iterator pairs or pointer/length pairs to parsing functions (`basic_json::parse`, `basic_json::accept`, `basic_json::sax_parse`, `basic_json::from_cbor`, `basic_json::from_msgpack`, `basic_json::from_ubjson`, `basic_json::from_bson`) via initializer lists is deprecated. Instead, pass two iterators; for instance, call `basic_json::from_cbor(ptr, ptr+len)` instead of `basic_json::from_cbor({ptr, len})`.
The following functions have been deprecated in earlier versions and will be removed in the next major version (i.e., 4.0.0):
- Function [`iterator_wrapper`](https://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a0a8051760196ac813fd5eb3c8d5a2976.html#a0a8051760196ac813fd5eb3c8d5a2976) are deprecated. Please use the member function [`items()`](https://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a5961446010dfc494e0c247b4e9026977.html#a5961446010dfc494e0c247b4e9026977) instead.
- Functions [`friend std::istream& operator<<(basic_json&, std::istream&)`](https://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a60ca396028b8d9714c6e10efbf475af6.html#a60ca396028b8d9714c6e10efbf475af6) and [`friend std::ostream& operator>>(const basic_json&, std::ostream&)`](https://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a34d6a60dd99e9f33b8273a1c8db5669b.html#a34d6a60dd99e9f33b8273a1c8db5669b) are deprecated. Please use [`friend std::istream& operator>>(std::istream&, basic_json&)`](https://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_aaf363408931d76472ded14017e59c9e8.html#aaf363408931d76472ded14017e59c9e8) and [`friend operator<<(std::ostream&, const basic_json&)`](https://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a5e34c5435e557d0bf666bd7311211405.html#a5e34c5435e557d0bf666bd7311211405) instead.
All deprecations are annotated with [`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which function to use instead.