JSON for Modern C++ version 3.9.0

Release date: 2020-07-27
SHA-256: d8089d52d285ef2c5368eb39ae665b39ea464206b1ca674a88a915c0245ff4f0 (json.hpp), 5b9b819aed31626aefe2eace23498cafafc1691890556cd36d2a8002f6905009 (include.zip)

JSON for Modern C++ 3.9.0 is a feature release that adds four long-awaited features, some requested five years ago.

• The parser functions have now an option to ignore // and /* */ style comments. Though comments are not officially part of the JSON specification (see here for a discussion), comment support was a frequently requested feature, and its implementation was much less effort than continuously explaining the lack of comment support.
• The second-most requested feature was a way to preserve the insertion order of object keys. Though this was possible via template specialization for a while, we now added a new type nlohmann::ordered_json as drop-in replacement for nlohmann::json for this.
• To circumvent unexpected behavior, implicit conversions can now be switched off with a CMake or preprocessor option.
• Last, but not least, a mapping between user-defined types and JSON can now be expressed using convenience macros by just listing the names of the member variables to read/write.

All changes are backward-compatible. See below the complete list of changes. See the README or the documentation for more information.

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

✨ New Features

• Add optional support for comments in JSON: passing parameter ignore_comments to the parse function will treat // and /* */ comments like whitespace. #294 #363 #376 #597 #1513 #2061 #2212
• Add type nlohmann::ordered_json to preserve insertion order of object keys. ordered_json is a specialization of basic_json and can be used wherever json is used. #106 #424 #543 #660 #727 #952 #1106 #1717 #1817 #2179 #2206 #2258
• Add CMake option JSON_ImplicitConversions and preprocessor symbol JSON_USE_IMPLICIT_CONVERSIONS to switch off implicit conversions. Implicit conversions, though very practical, are also a source of subtle bugs or unexpected behavior and may be switched off by default in future versions. The new options allow to remove implicit conversions now. #958 #1559
• Add convenience macros NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE and NLOHMANN_DEFINE_TYPE_INTRUSIVE to simplify serialization/deserialization code for user-defined types. #2175 #2225 #2233 #2267 #2280 #2287 #2306 #2313
• Add high-precision number support for UBJSON. Now, any JSON value can serialized to UBJSON, and exception json.exception.out_of_range.407 will no longer occur for integers larger than 9223372036854775807 (LLONG_MAX). #2297 #2286
• Write binary subtype as CBOR tag. #2244
• Add option to ignore CBOR tags as alternative to treat them as invalid input. #2308 #2273 #1968

🐛 Bug Fixes

• Fix bug in CBOR parser where allow_exceptions was not respected. #2299 #2298
• Fix bug in CBOR parser where incomplete binary values or strings could crash the parser. #2293 #2294

⚡ Improvements

• Make code compile with Clang on Windows. #2259 #1119
• Use 32-bit float encoding in MessagePack wherever this is possible without loss of precision. #2201 #2196
• Replace std::hash<nlohmann::basic_json> with a function that does not allocate memory. #2292 #2285 #2269

🔨 Further Changes

• Use GitLab Discussions for support and feature requests. Removed and adjusted issue templates accordingly.
• Allow CMake 3.13+ to override options when using FetchContent. #2222
• Add support for pkg-config. #2253
• Add CMake option JSON_TestDataDirectory to select directory of previously downloaded test data for situations where Internet access is forbidden during testing. #2189 #2190
• Add option to skip tests that assume the code is checked out via Git. #2189
• Add JSON_ASSERT macro to control behavior of assert calls. #2242
• Add CI step for GitHub CodeQL analysis (GitHub actions).
• Add CI step for Clang 9 and Clang 10 on Windows (GitHub actions). #2259
• Add CI step for Clang 10 CL with MSVC 2019 on Windows (GitHub actions). #2268
• Clean up GitHub actions CI. #2300
• Add CI step for Xcode 12 (Travis). #2262
• Add CI step for explicit conversions (Travis, AppVeyor).
• Remove swap specialization to support C++20. #2176
• Add missing check for binary() function in SAX interface. #2282
• Add test for CMake target_include_directories. #2279
• Add test to use library in multiple translation units. #2301
• Add more sections to new project website. #2312
• Fix warnings. #2304 #2305 #2303 #2274 #2224 #2211 #2203
• Cleanup maintainer Makefiles. #2264 #2274
• Improve documentation. #2232
• Fix inconsistency in int-to-string function. #2193

🔥 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.