JSON for Modern C++ version 3.10.0

[nlohmann]

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. By defining JSON_DIAGNOSTICS before including the json.hpp, a JSON Pointer is added to 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.

💰 Note you can support this project via GitHub sponsors or PayPal.

✨ New Features

• Add extended diagnostics information by adding a JSON Pointer to the exception 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 to 1 before including json.hpp. See the documentation for more information. Add Key name to Exception #932 How to get position info or parser context with custom from_json() that may throw exceptions? #1508 Better diagnostics #2562 Assertion failure when inserting into arrays with JSON_DIAGNOSTICS set #2838 Fix assertion failure in diagnostics #2866

• Add a GDB pretty printer to facilitate reading basic_json values in GDB. GDB pretty printing support #1952 Add GDB pretty printer #2607

• Add a new value store to the cbor_tag_handler_t which allows to store the tags of CBOR values as binary subtypes. Binary subtype field cannot represent all CBOR tags #2863 Fix binary subtypes #2908

• Add support for containers with non-default-constructible types. Deserialization to std::array with non-default constructable types fails #2574 Add support for deserialization of STL containers of non-default constructable types (fixes #2574). #2576

🐛 Bug Fixes

• Fix a regression bug that failed ordered_json to be used when exceptions were switched off. Fix code to work without exceptions #2347 -fno-expection not respected anymore in 3.9.1 #2725 Latest version 3.9.1 uses throw instead of JSON_THROW in the amalgamated json.hpp file #2934
• Added iterator range insertion for ordered_json. Missing "void insert( InputIt first, InputIt last );" overload in nlohmann::ordered_map #2490 Ranged insert test section is added in unit-ordered_json.cpp #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. Binary subtype field cannot represent all CBOR tags #2863 Fix binary subtypes #2908
• Fix move constructor of internal json_ref type which created null values when compiled with -fno-elide-constructors. Usage with -fno-elide-constructors causes dump() output to be array of nulls #2387 Fix move constructor of json_ref #2405
• Fix the compilation of input_adapter for containers in edge cases. Fix compilation of input_adapter(container) in edge cases #2553
• Allow parsing from std::byte containers. Compilation failure of tests with C++20 standard (caused by change of u8 literals)  #2413 Should it support parsing containers of `std::byte`? #2546 Allow parsing from std::byte containers #2550 Parse from byte-vector results in compile error #2602 can't parse std::vector<std::byte> #2869
• Fix memory leak in to_json in case a JSON value is reused. ASAN detects memory leaks #2865 Fix memory leak in to_json #2872
• Fix compilation error in case symbol EOF was not found. Undefined symbol EOF  #2755 replace EOF with std::char_traits<char>::eof() #2756
• Fix Compilation error when using NLOHMANN_JSON_SERIALIZE_ENUM with ordered_json on libc++. Compilation error when using NLOHMANN_JSON_SERIALIZE_ENUM ordered_json on libc++ #2491 Properly constrain the basic_json conversion operator #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. Compiler warns of implicit fallthrough when defining preprocessor macro NDEBUG #2348 Remove -Wimplicit-fallthrough warning #2349
• Fix -Wfloat-equal warnings. Comparison floating points causes warning #2909 Supress -Wfloat-equal on intended float comparisions #2911
• Add assertions to suppress C28020 warnings. Add asserts to suppress C28020 #2447
• Fix shadow warnings. Fixes Cppcheck warnings #1759 Fix a shadowing warning #2536 Change argument name "subtype" in byte_container_with_subtype #2444
• Fix compiler warnings in the test suite. Fix warnings #2537
• Fix issues found by Visual Studio Visual Assist Visual Studio Visual Assist code issues reported by VA code inspection of file json.hpp #2615
• Fix unused parameter warning. Unused variable in exception class when not using improved diagnostics #2646 unused-parameter on OSX when Diagnostics is off #2658 Compiler warning: unused parameter #2668 unused parameter error/warning #2706 Update json.hpp #2707
• Remove HEDLEY annotation from exception::what() to fix C28204 warning. Remove HEDLEY annotation from exception::what() #2673 compile errors .... chromium-style #2680
• Suppress C4127 warning. Warnings C4715 and C4127 when building json-3.9.1 with Visual Studio 2019 16.7.7 #2592 Suppress C4127 warning in unit-json_pointer.cpp #2875
• Fix truncation warning. compiler error: directive output may be truncated writing between 2 and 8 bytes #2572 Fix truncation warning #2874
• Fix useless cast warning. GCC -Wuseless-cast warnings #1777 usless_cast warnings with gcc 9.3 and 10.1 (C++17) #2114 g++ (11) -Wuseless-cast gives lots of warnings #2893 Fix useless-cast warnings #2902
• Fix unknown pragma warning. warning C4068: unknown pragma 'GCC' on MSVC/cl #2924 Guard GCC pragmas #2925
• Fix -Wswitch-enum warnings. All: fix warnings when compiling with -Wswitch-enum #2927
• Fix C4309 and C4100 warnings and treat all MSVC /W4 warnings as error. Treat MSVC warnings as errors #2930
• Suppress fewer warning flags. Overwork warning flags #2936

⚡ Improvements

Tests and CI

The CI chain has been completely overworked and now runs mostly on a dedicated Docker Image that contains all relevant tools.

• Collected all CI calls in a CMake file 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. Travis doesn't run any tests in C++17 mode #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. Always compile tests with all warnings enabled and error out on warnings #1798 CI targets #2561 Use Clang 12 in CI #2737 Add C++ standards to macOS matrix #2790 Fix CI #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 for aarch64 build. Remove FOSSA. Properly select "Release" build for Travis CI builds. Properly select "Release" build for Travis #2375 add more CI steps #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. Compilation error due to assuming that private=public #43 Don't use define private public in test files #913 Build error: keyword is hidden by macro definition! #1985 Remove "#define private public" from tests #2352

CMake

• Fixed issue in CMake file that overwrote CMAKE_CXX_COMPILER when the test suite was compiled. fix cmake script overwriting compiler path #2344 Build fails with clang-cl due to override of CMAKE_CXX_COMPILER(?) #2384
• Only enable CMake options JSON_BuildTests and JSON_Install by default when the library is the main project. Including CTest in the top-level CMakeLists.txt sets BUILD_TESTING=ON for parent projects #2513 Add MAIN_PROJECT check for test and install options #2514
• Add CTest label not_reproducible to skip non-reproducible tests. 3.9.0: tests make build non-reproducible #2324 Add switch to skip non-reproducible tests. #2560
• Formatted CMake files #Keep consistent formatting #2770
• Add a CMake option JSON_SystemInclude to use SYSTEM in target_include_directories. Add a cmake option 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. Fix typos in documentation #2354 Fix typo in README #2754
• Extended documentation for discarded values and is_discarded() function. json::parse(allow_exceptions = false) documentation is misleading. #2360 Fix and extend documentation of discarded values #2363
• Fix Markdown of README. readme: fix tilde character display #2582
• Fix example in README file. Fix missing 1.78 in example in README.md #2625 Fix amount of entries in the json object #2659
• Fix example in parse exceptions documentation. Update parse_exceptions.md - correct json::exception::parse_error #2679
• Overworked documentation of number handling. Add documentation for numbers #2747
• Add link to Conan Center package to README. Link to Conan Center package added #2771
• Added example for CPM.cmake. 📝 add CPM.Cmake example #2406
• Update README to use HTTPS everywhere. Update URLs to HTTPS #2789
• Fixed consistency of using declarations in README. Consistency with using in README.md #2826
• Fix documentation of tests that required a Git checkout. 3.9.1: test suite is failing #2845
• Fix code samples in GIF slideshow. Sample code in GIF slide outdated (cannot use emplace() with array) #2457
• Update documentation to reference RFC 8259 as JSON standard.
• Add section on how to get support to README file.
• Replaced links to Doxygen documentation with new API documentation.
• Documented the effect of a bug in Microsoft's STL that makes what() member function of exception objects unusable in case _HAS_EXCEPTIONS=0 is set. encoding of json::exception::what() #2824

Thirdparty

• Updated Hedley to version 15. Update Hedley #2367
• Updated Doctest to version 2.4.6. Doctest is updated to v2.4.1 #2525 Doctest is updated to v2.4.3 #2538 Tests do not compile with pre-release glibc #2686 Update doctest from 2.4.4 to 2.4.6 (fixes #2686) #2687

🔨 Further Changes

• Use C++14 constructs where available. Do not unconditionally redefine C++14 constructs #2533
• Fix pkg-config.pc generation. pkg-config.pc.in: Don't concatenate paths #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. Possibility to use with custom c++ version to use in intel sgx enclaves #2730 Fixes #2730 #2731 Update documentation #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)). Possibility to use without the dependency to file io and streams to use in intel sgx enclaves #2728 Possibility to use without the dependency to file io and streams to use in intel sgx enclaves #2729 Documentation for macro JSON_NO_IO is missing #2842 Update documentation #2861
• Benchmarks are handled via FetchContent and require CMake version 3.11. Removed Google Benchmark copy. Fix default branch name for Google Benchmarks. Specified git branch for google benchmark fetch in benchmark test #2795 Failed benchmark due to renamed branch #2796
• Simplify object parser for CBOR. Avoid string in case of empty CBOR objects #2879 Unhandled exception in test-cbor.exe Stack overflow when debugging project with Visual Studio 2019 16.7.7 compiled with c++17 or c++latest #2598
• Cleaned up maintainer Makefiles

Licensing

• Clarified license of is_complete_type implementation. Clarify license of is_complete_type implementation #2534
• License fix for integer_sequence and index_sequence implementation. License fix #2683

🔥 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 are deprecated. Please use the member function items() instead.
• Functions friend std::istream& operator<<(basic_json&, std::istream&) and friend std::ostream& operator>>(const basic_json&, std::ostream&) are deprecated. Please use friend std::istream& operator>>(std::istream&, basic_json&) and friend operator<<(std::ostream&, const basic_json&) instead.

All deprecations are annotated with HEDLEY_DEPRECATED_FOR to report which function to use instead.

---

This discussion was created from the release JSON for Modern C++ version 3.10.0.

[bl-ue]

Amazing, thank you so much Niels. I've been waiting for this for, well, over a year ;)

I just checked a few hours ago, for the first time in a fews months for a new release, and there wasn't any!

_{Off-topic, but GitHub appears to have revamped the release/discussion voting/reactions UI this very day as well...}

[acohenOT]

Will this be added to NuGet https://www.nuget.org/packages/nlohmann.json/ ? That page is showing 3.9.1 as the latest version. Thank you.

[nlohmann]

It's not maintained by myself. I created an issue: hnkb/nlohmann-json-nuget#2

[nlohmann]

It should be updated now.