Nlohmann-json

Release date: 2018-02-13
SHA-256: e14ce5e33d6a2daf748026bd4947f3d9686ca4cfd53d10c3da46a0a9aceb7f2e (json.hpp), fde771d4b9e4f222965c00758a2bdd627d04fb7b59e09b7f3d1965abdc848505 (include.zip)

Summary

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

:bug: Bug Fixes

- Fixed parsing of **CBOR strings with indefinite length** (961). Earlier versions of this library misinterpreted the CBOR standard and rejected input with the `0x7F` start byte.
- Fixed user-defined **conversion to vector type** (924, 969). A wrong SFINAE check rejected code though a user-defined conversion was provided.
- Fixed documentation of the parser behavior for **objects with duplicate keys** (963). The exact behavior is not specified by [RFC 8259](https://tools.ietf.org/html/rfc8259) and the library now also provides no guarantee which object key is stored.
- Added check to detect memory **overflow when parsing UBJSON containers** (962). The optimized UBJSON format allowed for specifying an array with billions of `null` elements with a few bytes and the library did not check whether this size exceeded `max_size()`.

:hammer: Further Changes

- [Code coverage](https://coveralls.io/github/nlohmann/json) is now calculated for the individual header files, allowing to find uncovered lines more quickly than by browsing through the single header version (#953, 957).
- A Makefile target `run_benchmarks` was added to quickly build and run the benchmark suite.
- The documentation was harmonized with respect to the header inclusion (955). Now all examples and the README use `include <nlohmann/json.hpp>` to allow for selecting `single_include` or `include` or whatever installation folder as include directory.
- Added note on how to use the library with the [cget](http://cget.readthedocs.io/en/latest/) package manager (#954).

:fire: 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`](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.

Release date: 2018-02-01
SHA-256: d40f614d10a6e4e4e80dca9463da905285f20e93116c36d97d4dc1aa63d10ba4 (json.hpp), 2b7234fca394d1e27b7e017117ed80b7518fafbb4f4c13a7c069624f6f924673 (include.zip)

Summary

This release adds support for the [**UBJSON**](http://ubjson.org) format and [**JSON Merge Patch**](https://tools.ietf.org/html/rfc7386). It also contains some minor changes and bug fixes. All changes are backward-compatible.

:sparkles: New features

- The library now supports [**UBJSON**](http://ubjson.org) (Universal Binary JSON Specification) as binary format to read and write JSON values space-efficiently. See the [documentation overview](https://github.com/nlohmann/json/blob/develop/doc/binary_formats.md) for a comparison of the different formats CBOR, MessagePack, and UBJSON.
- [**JSON Merge Patch**](https://tools.ietf.org/html/rfc7386) (RFC 7386) offers an intuitive means to describe patches between JSON values (#876, 877). See the documentation of [`merge_patch`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a0ec0cd19cce42ae6071f3cc6870ea295.html#a0ec0cd19cce42ae6071f3cc6870ea295) for more information.

:zap: Improvements

- The library now uses the **Grisu2 algorithm** for printing floating-point numbers (based on the reference implementation by Florian Loitsch) which produces a short representation which is guaranteed to round-trip (360, 935, 936).
- The **UTF-8 handling** was further simplified by using the decoder of Björn Hoehrmann in more scenarios.

:truck: Reorganization

- Though the library is released as a single header, its development got more and more complicated. With this release, the header is **split into several files** and the single-header file `json.hpp` can be generated from these development sources. In the repository, folder `include` contains the development sources and `single_include` contains the single `json.hpp` header (700, 906, 907, 910, 911, 915, 920, 924, 925, 928, 944).
- The split further allowed for a **forward declaration header** `include/nlohmann/json_fwd.hpp` to speed up compilation times (314).

:hammer: Further changes

- [Google Benchmark](https://github.com/google/benchmark) is now used for micro benchmarks (see `benchmarks` folder, #921).
- The serialization (JSON and binary formats) now properly work with the libraries string template parameter, allowing for optimized string implementations to be used in constraint environments such as embedded software (941, 950).
- The exceptional behavior can now be overridden by defining macros `JSON_THROW_USER`, `JSON_TRY_USER`, and `JSON_CATCH_USER`, defining the behavior of `throw`, `try` and `catch`, respectively. This allows to switch off C++'s exception mechanism yet still execute user-defined code in case an error condition occurs (938).
- To facilitate the interplay with [flex](https://github.com/westes/flex) and [Bison](https://www.gnu.org/software/bison/), the library does not use the variable name `yytext` any more as it could clash with macro definitions (#933).
- The library now defines `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, and `NLOHMANN_JSON_VERSION_PATCH` to allow for conditional compilation based on the included library version (943, 948).
- A compilation error with ICC has been fixed (947).
- Typos and links in the documentation have been fixed (900, 930).
- A compiler error related to incomplete types has been fixed (919).
- The tests form the [UTF-8 decoder stress test](http://www.cl.cam.ac.uk/~mgk25/ucs/examples/UTF-8-test.txt) have been added to the test suite.

:fire: Deprecated functions

- Function [`iterator_wrapper`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_af1592a06bc63811886ade4f9d965045e.html#af1592a06bc63811886ade4f9d965045e) has been deprecated (874). Since its introduction, the name was up for discussion, as it was too technical. We now introduced the member function [`items()`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_afe3e137ace692efa08590d8df40f58dd.html#afe3e137ace692efa08590d8df40f58dd) with the same semantics. `iterator_wrapper` will be removed in the next major version (i.e., 4.0.0).

Furthermore, the following functions are deprecated since version 3.0.0 and will be removed in the next major version (i.e., 4.0.0):

- [`friend std::istream& operator<<(basic_json&, std::istream&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_ab7285a92514fcdbe6de505ebaba92ea3.html#ab7285a92514fcdbe6de505ebaba92ea3)
- [`friend std::ostream& operator>>(const basic_json&, std::ostream&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a9e06deabe69262c3ffc5533d32856983.html#a9e06deabe69262c3ffc5533d32856983)

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.

Release date: 2017-12-29
SHA-256: c9b3591f1bb94e723a0cd7be861733a3a555b234ef132be1e9027a0364118c4c

Summary

This release fixes small issues in the implementation of **JSON Pointer** and **JSON Patch**. All changes are backward-compatible.

Changes

- :bug: The **"copy" operation of JSON Patch** ([RFC 6902](https://tools.ietf.org/html/rfc6902)) requests that it is an error if the target path points into a non-existing array or object (see #894 for a detailed description). This release fixes the implementation to detect such invalid target paths and throw an exception.
- :bug: An **array index in a JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) must be an integer. This release fixes the implementation to throw an exception in case invalid array indices such as `10e2` are used.
- :white_check_mark: Added the [JSON Patch tests](https://github.com/json-patch/json-patch-tests) from Byron Ruth and Mike McCabe.
- :memo: Fixed the documentation of the [`at(ptr)` function with JSON Pointers](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a8ab61397c10f18b305520da7073b2b45.html#a8ab61397c10f18b305520da7073b2b45) to list all possible exceptions (see 888).
- :memo: Updated the [container overview documentation](https://nlohmann.github.io/json/) (see #883).
- :wrench: The CMake files now respect the [`BUILD_TESTING`](https://cmake.org/cmake/help/latest/module/CTest.html?highlight=build_testing) option (see #846, 885)
- :rotating_light: Fixed some compiler warnings (see 858, 882).

Deprecated functions

:fire: To unify the interfaces and to improve similarity with the STL, the following functions are deprecated since version 3.0.0 and will be removed in the next major version (i.e., 4.0.0):

- [`friend std::istream& operator<<(basic_json&, std::istream&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_ab7285a92514fcdbe6de505ebaba92ea3.html#ab7285a92514fcdbe6de505ebaba92ea3)
- [`friend std::ostream& operator>>(const basic_json&, std::ostream&)`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a9e06deabe69262c3ffc5533d32856983.html#a9e06deabe69262c3ffc5533d32856983)

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.

User-defined Exceptions

There are five different exceptions inheriting from [`json::exception`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a9a0aced019cb1d65bb49703406c84970.html#a9a0aced019cb1d65bb49703406c84970):

- [`json::parse_error`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_af1efc2468e6022be6e35fc2944cabe4d.html#af1efc2468e6022be6e35fc2944cabe4d) for syntax errors (including the binary formats),
- [`json::invalid_iterator`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_ac13d32f7cbd02d616e71d8dc30dadcbf.html#ac13d32f7cbd02d616e71d8dc30dadcbf) for errors related to iterators,
- [`json::type_error`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a4010e8e268fefd86da773c10318f2902.html#a4010e8e268fefd86da773c10318f2902) for errors where functions were called with the wrong JSON type,
- [`json::out_of_range`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a28f7c2f087274a0012eb7a2333ee1580.html#a28f7c2f087274a0012eb7a2333ee1580) for range errors, and
- [`json::other_error`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a3333a5a8714912adda33a35b369f7b3d.html#a3333a5a8714912adda33a35b369f7b3d) for miscellaneous errors.

To support these exception, the `try`/`catch` blocks of your code need to be adjusted:

| new exception | previous exception |
|:--|:--|
| parse_error.101 | invalid_argument |
| parse_error.102 | invalid_argument |
| parse_error.103 | invalid_argument |
| parse_error.104 | invalid_argument |
| parse_error.105 | invalid_argument |
| parse_error.106 | domain_error |
| parse_error.107 | domain_error |
| parse_error.108 | domain_error |
| parse_error.109 | invalid_argument |
| parse_error.110 | out_of_range |
| parse_error.111 | invalid_argument |
| parse_error.112 | invalid_argument |
| invalid_iterator.201 | domain_error |
| invalid_iterator.202 | domain_error |
| invalid_iterator.203 | domain_error |
| invalid_iterator.204 | out_of_range |
| invalid_iterator.205 | out_of_range |
| invalid_iterator.206 | domain_error |
| invalid_iterator.207 | domain_error |
| invalid_iterator.208 | domain_error |
| invalid_iterator.209 | domain_error |
| invalid_iterator.210 | domain_error |
| invalid_iterator.211 | domain_error |
| invalid_iterator.212 | domain_error |
| invalid_iterator.213 | domain_error |
| invalid_iterator.214 | out_of_range |
| type_error.301 | domain_error |
| type_error.302 | domain_error |
| type_error.303 | domain_error |
| type_error.304 | domain_error |
| type_error.305 | domain_error |
| type_error.306 | domain_error |
| type_error.307 | domain_error |
| type_error.308 | domain_error |
| type_error.309 | domain_error |
| type_error.310 | domain_error |
| type_error.311 | domain_error |
| type_error.313 | domain_error |
| type_error.314 | domain_error |
| type_error.315 | domain_error |
| out_of_range.401 | out_of_range |
| out_of_range.402 | out_of_range |
| out_of_range.403 | out_of_range |
| out_of_range.404 | out_of_range |
| out_of_range.405 | domain_error |
| other_error.501 | domain_error |

Handling of NaN and INF

- If an overflow occurs during parsing a number from a JSON text, an exception [`json::out_of_range`](http://nlohmann.github.io/json/classnlohmann_1_1basic__json_a28f7c2f087274a0012eb7a2333ee1580.html#a28f7c2f087274a0012eb7a2333ee1580) is thrown so that the overflow is detected early and roundtripping is guaranteed.

- NaN and INF floating-point values can be stored in a JSON value and are not replaced by null. That is, the basic_json class behaves like `double` in this regard (no exception occurs). However, NaN and INF are serialized to `null`.

Removal of deprecated functions

Function `explicit basic_json(std::istream& i, const parser_callback_t cb = nullptr)` should be replaced by the `parse` function: Let `ss` be a stream and `cb` be a parse callback function.

Old code:

cpp
json j(ss, cb);


New code:

cpp
json j = json::parse(ss, cb);


If no callback function is used, also the following code works:

cpp
json j;
j << ss;


or

cpp
json j;
ss >> j;

Release date: 2017-02-25
SHA-256: faa2321beb1aa7416d035e7417fcfa59692ac3d8c202728f9bcc302e2d558f57

Summary

This release **fixes a locale-related bug in the parser**. To do so, the whole number handling (lexer, parser, and also the serialization) have been overworked. Furthermore, a lot of small changes added up that were added to this release. All changes are backward-compatible.

Changes
- :bug: Locales that have a different character than `.` as decimal separator (e.g., the Norwegian locale `nb_NO.UTF-8`) led to truncated number parsing or parse errors. The library now has been fixed to work with **any locale**. Note that `.` is still the only valid decimal separator for JSON input.
- :bug: Numbers like `1.0` were correctly parsed as floating-point number, but serialized as integer (`1`). Now, **floating-point numbers correctly round trip**.
- :bug: Parsing incorrect JSON numbers with leading 0 (`0123`) could yield a [buffer overflow](https://github.com/nlohmann/json/issues/452). This is fixed now by detecting such errors directly by the lexer.
- :bug: Constructing a JSON value from a pointer was incorrectly interpreted as a Boolean; such code will now yield a compiler error.
- :bug: Comparing a JSON number with `0` led to a comparison with `null`. This is fixed now.
- :bug: All throw calls are now wrapped in macros.
- :lock: Starting during the preparation of this release (since 8 February 2017), commits and released files are **cryptographically signed** with [this GPG key](https://keybase.io/nlohmann/pgp_keys.asc?fingerprint=797167ae41c0a6d9232e48457f3cea63ae251b69). Previous releases have also been signed.
- :sparkles: The parser for MessagePack and CBOR now supports an optional start index parameter to define a byte offset for the parser.
- :rotating_light: Some more warnings have been fixed. With Clang, the code compiles **without warnings** with `-Weverything` (well, it needs `-Wno-documentation-unknown-command` and `-Wno-deprecated-declarations`, but you get the point).
- :hammer: The code can be compiled easier with many Android NDKs by avoiding macros like `UINT8_MAX` which previously required defining a preprocessor macro for compilation.
- :zap: The unit tests now compile two times faster.
- :heavy_plus_sign: [Cotire](https://github.com/sakra/cotire) is used to speed up the build.
- :pencil2: Fixed a lot of typos in the documentation.
- :memo: Added a section to the README file that lists all used [third-party code/tools](https://github.com/nlohmann/json#used-third-party-tools).
- :memo: Added a note on constructing a string value vs. parsing.
- :white_check_mark: The test suite now contains 11202597 unit tests.
- :memo: Improved the [Doxygen documentation](https://nlohmann.github.io/json/) by shortening the template parameters of class `basic_json`.
- :construction_worker: Removed Doozer.
- :construction_worker: Added Codacity.
- :arrow_up: Upgraded Catch to version 1.7.2.

- Release date: 2017-01-28
- SHA-256: a571dee92515b685784fd527e38405cf3f5e13e96edbfe3f03d6df2e363a767b

Summary

This release introduces a means to convert from/to user-defined types. The release is backwards compatible.


Changes
- :sparkles: The library now offers an elegant way to **convert from and to arbitrary value types**. All you need to do is to implement two functions: `to_json` and `from_json`. Then, a conversion is as simple as putting a `=` between variables. See the [README](https://github.com/nlohmann/json#arbitrary-types-conversions) for more information and examples.
- :sparkles: **Exceptions can now be switched off.** This can be done by defining the preprocessor symbol `JSON_NOEXCEPTION` or by passing `-fno-exceptions` to your compiler. In case the code would usually thrown an exception, `abort()` is now called.
- :sparkles: **Information on the library** can be queried with the new (static) function `meta()` which returns a JSON object with information on the version, compiler, and platform. See the [documentation]() for an example.
- :bug: A bug in the CBOR parser was fixed which led to a buffer overflow.
- :sparkles: The function [`type_name()`]() is now public. It allows to query the type of a JSON value as string.
- :white_check_mark: Added the [Big List of Naughty Strings](https://github.com/minimaxir/big-list-of-naughty-strings) as test case.
- :arrow_up: Updated to [Catch v1.6.0](https://github.com/philsquared/Catch/releases/tag/v1.6.0).
- :memo: Some typos in the documentation have been fixed.