Release date: 2018-08-20

SHA-256: ce6b5610a051ec6795fa11c33854abebb086f0fd67c311f5921c3c07f9531b44 (json.hpp), 35ee642558b90e2f9bc758995c4788c4b4d4dec54eef95fb8f38cb4d49c8fc7c (include.zip)

This release introduces a [**SAX interface**](https://nlohmann.github.io/json/structnlohmann_1_1json__sax.html) to the library. While this may be a very special feature used by only few people, it allowed to unify all functions that consumed input and created some kind of JSON value. Internally, now all existing functions like `parse`, `accept`, `from_cbor`, `from_msgpack`, and `from_ubjson` use the SAX interface with different event processors. This allowed to separate the input processing from the value generation. Furthermore, throwing an exception in case of a parse error is now optional and up to the event processor. Finally, the JSON parser is now non-recursive (meaning it does not use the call stack, but `std::vector<bool>` to track the hierarchy of structured values) which allows to process nested input more efficiently.

Furthermore, the library finally is able to parse from **wide string types**. This is the first step toward opening the library from UTF-8 to UTF-16 and UTF-32.

This release further fixes several bugs in the library. All changes are backward-compatible.

- added a parser with a **SAX interface** (#971, #1153)
- support to parse from **wide string types** `std::wstring`, `std::u16string`, and `std::u32string`; the input will be converted to UTF-8 (#1031)
- added support for **`std::string_view`** when using C++17 (#1028)
- allow to **roundtrip `std::map` and `std::unordered_map`** from JSON if key type is not convertible to string; in these cases, values are serialized to arrays of pairs (#1079, #1089, #1133, #1138)

- allow to create `nullptr_t` from JSON allowing to properly roundtrip `null` values (#1169)
- allow compare user-defined string types (#1130)
- better support for algorithms using iterators from `items()` (#1045, #1134)
- added parameter to avoid compilation error with MSVC 2015 debug builds (#1114)
- re-added accidentially skipped unit tests (#1176)
- fixed MSVC issue with `std::swap` (#1168)

- `key()` function for iterators returns a const reference rather than a string copy (#1098)
- binary formats CBOR, MessagePack, and UBJSON now supports `float` as type for floating-point numbers (#1021)

- changed issue templates
- improved continuous integration: added builders for Xcode 9.3 and 9.4, added builders for GCC 8 and Clang 6, added builder for MinGW, added builders for MSVC targeting x86
- required CMake version is now at least 3.8 (#1040)
- overworked CMake file wrt. packaging (#1048)
- added package managers: Spack (#1041) and CocoaPods (#1148)
- fixed Meson include directory (#1142)
- preprocessor macro `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK` can skip the rejection of unsupported compilers - use at your own risk! (#1128)
- preprocessor macro `JSON_INTERNAL_CATCH`/`JSON_INTERNAL_CATCH_USER` allows to control the behavior of exception handling inside the library (#1187)
- added note on `char` to JSON conversion
- added note how to send security-related issue via encrypted email
- removed dependency to `std::stringstream` (#1117)
- added SPDX-License-Identifier
- added updated JSON Parsing Test Suite, described in [Parsing JSON is a Minefield 💣](http://seriot.ch/parsing_json.php)
- updated to Catch 1.12.0

This release does not deprecate any functions. As an overview, 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`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_af1592a06bc63811886ade4f9d965045e.html#af1592a06bc63811886ade4f9d965045e) are deprecated. Please use the member function [`items()`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_afe3e137ace692efa08590d8df40f58dd.html#afe3e137ace692efa08590d8df40f58dd) instead.
- Functions [`friend std::istream& operator<<(basic_json&, std::istream&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_ab7285a92514fcdbe6de505ebaba92ea3.html#ab7285a92514fcdbe6de505ebaba92ea3) and [`friend std::ostream& operator>>(const basic_json&, std::ostream&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a9e06deabe69262c3ffc5533d32856983.html#a9e06deabe69262c3ffc5533d32856983) are deprecated. Please use [`friend std::istream&  operator>>(std::istream&, basic_json&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_aaf363408931d76472ded14017e59c9e8.html#aaf363408931d76472ded14017e59c9e8) and [`friend operator<<(std::ostream&, const basic_json&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a5e34c5435e557d0bf666bd7311211405.html#a5e34c5435e557d0bf666bd7311211405) instead.