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](https://github.com/nlohmann/json#comments-in-json) 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](https://github.com/nlohmann/json/blob/develop/README.md) or the [documentation](https://nlohmann.github.io/json/) for more information.

:moneybag: Note you can **support this project** via [GitHub sponsors](https://github.com/sponsors/nlohmann) or [PayPal](http://paypal.me/nlohmann).

- Add optional support for [**comments in JSON**](https://github.com/nlohmann/json#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**](https://github.com/nlohmann/json#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**](https://github.com/nlohmann/json#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`](https://github.com/nlohmann/json#simplify-your-life-with-macros) 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

- 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

- 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

- Use [GitLab Discussions](https://github.com/nlohmann/json/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](https://github.com/nlohmann/json#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](https://github.com/nlohmann/json#execute-unit-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](https://github.com/nlohmann/json/actions?query=workflow%3A%22Code+scanning+-+action%22) (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](https://github.com/nlohmann/json#sax-interface). #2282
- Add [test](https://github.com/nlohmann/json/tree/develop/test/cmake_target_include_directories/project) for CMake `target_include_directories`. #2279
- Add test to use library in multiple translation units. #2301
- Add more sections to new [project website](https://nlohmann.github.io/json/). #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

This release deprecates 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. Instead, pass the elements individually without braces.

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.