Summary

This release introduces three new features:

• BSON (Binary JSON) is next to CBOR, MessagePack, and UBJSON the fourth binary (de)serialization format supported by the library.
• Adjustable error handlers for invalid Unicode allows to specify the behavior when invalid byte sequences are serialized.
• Simplified enum/JSON mapping with a macro in case the default mapping to integers is not desired.

Furthermore, some effort has been invested in improving the parse error messages. Besides, a few bugs have been fixed. All changes are backward-compatible.

New Features

• The library can read and write a subset of BSON (Binary JSON). All data types known from JSON are supported, whereas other types more tied to MongoDB such as timestamps, object ids, or binary data are currently not implemented. See the README for examples. #1244 #1320
• The behavior when the library encounters an invalid Unicode sequence during serialization can now be controlled by defining one of three Unicode error handlers: (1) throw an exception (default behavior), (2) replace invalid sequences by the Unicode replacement character (U+FFFD), or (3) ignore/filter invalid sequences. See the documentation of the dump function for examples. #1198 #1314
• To easily specify a user-defined enum/JSON mapping, a macro NLOHMANN_JSON_SERIALIZE_ENUM has been introduced. See the README section for more information. #1208 #1323

Bug Fixes

• fixed truncation #1286 #1315
• fixed an issue with std::pair #1299 #1301
• fixed an issue with std::variant #1292 #1294
• fixed a bug in the JSON Pointer parser

Improvements

• The diagnosis messages for parse errors have been improved: error messages now indicated line/column positions where possible (in addition to a byte count) and also the context in which the error occurred (e.g., "while parsing a JSON string"). Example: error parse error at 2: syntax error - invalid string: control character must be escaped; last read: '<U+0009>' is now reported as parse error at line 1, column 2: syntax error while parsing value - invalid string: control character U+0009 (HT) must be escaped to \u0009 or \t; last read: '<U+0009>'. #1280 #1288 #1303

Further Changes

• improved Meson documentation #1305
• fixed some more linter warnings #1280
• fixed Clang detection for third-party Google Benchmark library #1277

Deprecated functions

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