Improve documentation: byte layouts, release pages, See also, dark-mode images (#5906) - Make the iterator range illustrations legible in dark mode (prefers-color-scheme rules inside the SVGs). - Add a "Byte layout" section with a color-coded byte table to each binary format page (BJData, BON8, BSON, CBOR, MessagePack, UBJSON), and highlight the smallest size per file in the comparison table. - Add "See also" sections to the overview pages that lacked one. - Split the release notes into one page per release, grouped by minor version on the overview page, with an "API changes" section per release generated from the API pages' version histories (hooks/api_changes.py). - Fact-check the release notes and version histories against the release tags and correct wrong or misleading entries (e.g., json_serializer 2.1.0, merge_patch 3.1.0, items, count, operator[], to_bjdata, std::string_view key support). Signed-off-by: Niels Lohmann <mail@nlohmann.me>
diff --git a/docs/mkdocs/docs/api/adl_serializer/index.md b/docs/mkdocs/docs/api/adl_serializer/index.md index e83b66d..e994a30 100644 --- a/docs/mkdocs/docs/api/adl_serializer/index.md +++ b/docs/mkdocs/docs/api/adl_serializer/index.md
@@ -30,6 +30,14 @@ - [**from_json**](from_json.md) - convert a JSON value to any value type - [**to_json**](to_json.md) - convert any value type to a JSON value +## See also + +- [Arbitrary type conversions](../../features/arbitrary_types.md) - how to make your types convertible +- [**get**](../basic_json/get.md) / [**get_to**](../basic_json/get_to.md) - convert a JSON value to a C++ type +- [**basic_json**](../basic_json/basic_json.md) - construct a JSON value from a C++ value +- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE**](../macros/nlohmann_define_type_intrusive.md) - generate the conversion functions for a type +- [Specializing enum conversion](../../features/enum_conversion.md) + ## Version history - Added in version 2.1.0.
diff --git a/docs/mkdocs/docs/api/basic_json/at.md b/docs/mkdocs/docs/api/basic_json/at.md index 22df4b5..194b123 100644 --- a/docs/mkdocs/docs/api/basic_json/at.md +++ b/docs/mkdocs/docs/api/basic_json/at.md
@@ -239,9 +239,8 @@ 1. Added in version 1.0.0. 2. Added in version 1.0.0. -3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as - already supported by [`operator[]`](operator[].md), [`value`](value.md), [`find`](find.md), and other lookup - functions. +3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently + across the lookup functions. 4. Added in version 2.0.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
diff --git a/docs/mkdocs/docs/api/basic_json/back.md b/docs/mkdocs/docs/api/basic_json/back.md index 685c1c8..32066d8 100644 --- a/docs/mkdocs/docs/api/basic_json/back.md +++ b/docs/mkdocs/docs/api/basic_json/back.md
@@ -63,4 +63,4 @@ ## Version history - Added in version 1.0.0. -- Adjusted code to return reference to binary values in version 3.8.0. +- Binary values are supported since version 3.8.0.
diff --git a/docs/mkdocs/docs/api/basic_json/basic_json.md b/docs/mkdocs/docs/api/basic_json/basic_json.md index e553509..d3df598 100644 --- a/docs/mkdocs/docs/api/basic_json/basic_json.md +++ b/docs/mkdocs/docs/api/basic_json/basic_json.md
@@ -482,15 +482,15 @@ ## Version history -1. Since version 1.0.0. -2. Since version 1.0.0. -3. Since version 2.1.0. -4. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since +1. Added in version 1.0.0. +2. Added in version 1.0.0. +3. Added in version 2.1.0. +4. Added in version 3.1.2. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.0. -5. Since version 1.0.0. -6. Since version 1.0.0. -7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range +5. Added in version 1.0.0. +6. Added in version 1.0.0. +7. Added in version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied, unlike the other primitive types. -8. Since version 1.0.0. -9. Since version 1.0.0. +8. Added in version 1.0.0. +9. Added in version 1.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/contains.md b/docs/mkdocs/docs/api/basic_json/contains.md index 64a3e49..c6e2e7d 100644 --- a/docs/mkdocs/docs/api/basic_json/contains.md +++ b/docs/mkdocs/docs/api/basic_json/contains.md
@@ -141,9 +141,8 @@ ## Version history 1. Added in version 3.11.0. -2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Fixed in - version 3.13.0 to consistently accept `std::string_view`-convertible keys, as already supported by - [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup functions. +2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Support for keys + convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions. 3. Added in version 3.7.0. 4. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime.
diff --git a/docs/mkdocs/docs/api/basic_json/count.md b/docs/mkdocs/docs/api/basic_json/count.md index 52dc0ff..580b798 100644 --- a/docs/mkdocs/docs/api/basic_json/count.md +++ b/docs/mkdocs/docs/api/basic_json/count.md
@@ -92,8 +92,7 @@ ## Version history 1. Added in version 3.11.0. -2. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0. Fixed in version 3.13.0 to - consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md), - [`at`](at.md), [`value`](value.md), and other lookup functions. +2. Added in version 1.0.0. Changed to support comparable key types in version 3.11.0. Support for keys convertible to + `std::string_view` added in version 3.13.0, consistently across the lookup functions. 3. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime.
diff --git a/docs/mkdocs/docs/api/basic_json/emplace.md b/docs/mkdocs/docs/api/basic_json/emplace.md index 09953d3..b1fd856 100644 --- a/docs/mkdocs/docs/api/basic_json/emplace.md +++ b/docs/mkdocs/docs/api/basic_json/emplace.md
@@ -69,6 +69,6 @@ ## Version history -- Since version 2.0.8. +- Added in version 2.0.8. - Fixed in version 3.13.0: for [`ordered_json`](../ordered_json.md), the value could previously only be passed as an rvalue; it can now also be passed as an lvalue or a `#!cpp const` lvalue, matching the behavior of `json`.
diff --git a/docs/mkdocs/docs/api/basic_json/emplace_back.md b/docs/mkdocs/docs/api/basic_json/emplace_back.md index 782b61f..38a6d5c 100644 --- a/docs/mkdocs/docs/api/basic_json/emplace_back.md +++ b/docs/mkdocs/docs/api/basic_json/emplace_back.md
@@ -67,5 +67,5 @@ ## Version history -- Since version 2.0.8. +- Added in version 2.0.8. - Returns reference since 3.7.0.
diff --git a/docs/mkdocs/docs/api/basic_json/erase.md b/docs/mkdocs/docs/api/basic_json/erase.md index 47531fe..1782b61 100644 --- a/docs/mkdocs/docs/api/basic_json/erase.md +++ b/docs/mkdocs/docs/api/basic_json/erase.md
@@ -213,7 +213,6 @@ 1. Added in version 1.0.0. Added support for binary types in version 3.8.0. 2. Added in version 1.0.0. Added support for binary types in version 3.8.0. 3. Added in version 1.0.0. -4. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as - already supported by [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup - functions. +4. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently + across the lookup functions. 5. Added in version 1.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/exception.md b/docs/mkdocs/docs/api/basic_json/exception.md index b592d62..88cf51b 100644 --- a/docs/mkdocs/docs/api/basic_json/exception.md +++ b/docs/mkdocs/docs/api/basic_json/exception.md
@@ -84,4 +84,4 @@ ## Version history -- Since version 3.0.0. +- Added in version 3.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/find.md b/docs/mkdocs/docs/api/basic_json/find.md index 92ab380..8883dc3 100644 --- a/docs/mkdocs/docs/api/basic_json/find.md +++ b/docs/mkdocs/docs/api/basic_json/find.md
@@ -99,8 +99,7 @@ ## Version history 1. Added in version 3.11.0. -2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Fixed in version 3.13.0 to - consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md), - [`at`](at.md), [`value`](value.md), and other lookup functions. +2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Support for keys convertible to + `std::string_view` added in version 3.13.0, consistently across the lookup functions. 3. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime.
diff --git a/docs/mkdocs/docs/api/basic_json/front.md b/docs/mkdocs/docs/api/basic_json/front.md index dbe92f5..08c871b 100644 --- a/docs/mkdocs/docs/api/basic_json/front.md +++ b/docs/mkdocs/docs/api/basic_json/front.md
@@ -57,4 +57,4 @@ ## Version history - Added in version 1.0.0. -- Adjusted code to return reference to binary values in version 3.8.0. +- Binary values are supported since version 3.8.0.
diff --git a/docs/mkdocs/docs/api/basic_json/get.md b/docs/mkdocs/docs/api/basic_json/get.md index fef1be7..fcb5c59 100644 --- a/docs/mkdocs/docs/api/basic_json/get.md +++ b/docs/mkdocs/docs/api/basic_json/get.md
@@ -188,6 +188,6 @@ ## Version history -1. Since version 2.1.0. -2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0. -3. Since version 1.0.0. +1. Added in version 2.1.0. +2. Added in version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.1.2. +3. Added in version 1.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/get_to.md b/docs/mkdocs/docs/api/basic_json/get_to.md index 29a78f0..233d151 100644 --- a/docs/mkdocs/docs/api/basic_json/get_to.md +++ b/docs/mkdocs/docs/api/basic_json/get_to.md
@@ -76,5 +76,5 @@ ## Version history -- Since version 3.3.0. +- Added in version 3.3.0. - Added a `static_assert` with a clear message for `const` arguments in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/basic_json/invalid_iterator.md b/docs/mkdocs/docs/api/basic_json/invalid_iterator.md index 6c19a3e..d757825 100644 --- a/docs/mkdocs/docs/api/basic_json/invalid_iterator.md +++ b/docs/mkdocs/docs/api/basic_json/invalid_iterator.md
@@ -75,4 +75,4 @@ ## Version history -- Since version 3.0.0. +- Added in version 3.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/items.md b/docs/mkdocs/docs/api/basic_json/items.md index 06e725d..025002e 100644 --- a/docs/mkdocs/docs/api/basic_json/items.md +++ b/docs/mkdocs/docs/api/basic_json/items.md
@@ -104,8 +104,8 @@ ## Version history -- Added `iterator_wrapper` in version 3.0.0. -- Added `items` and deprecated `iterator_wrapper` in version 3.1.0. +- Added in version 3.1.0 as the replacement of the static function `iterator_wrapper`, which was available since + version 1.0.0 and is deprecated since version 3.1.0. - Added structured binding support in version 3.5.0. !!! warning "Deprecation"
diff --git a/docs/mkdocs/docs/api/basic_json/json_serializer.md b/docs/mkdocs/docs/api/basic_json/json_serializer.md index 20e9cfd..011f7d1 100644 --- a/docs/mkdocs/docs/api/basic_json/json_serializer.md +++ b/docs/mkdocs/docs/api/basic_json/json_serializer.md
@@ -51,4 +51,4 @@ ## Version history -- Since version 2.0.0. +- Added in version 2.1.0.
diff --git a/docs/mkdocs/docs/api/basic_json/merge_patch.md b/docs/mkdocs/docs/api/basic_json/merge_patch.md index 00e1bc8..1fafb1e 100644 --- a/docs/mkdocs/docs/api/basic_json/merge_patch.md +++ b/docs/mkdocs/docs/api/basic_json/merge_patch.md
@@ -71,6 +71,6 @@ ## Version history -- Added in version 3.0.0. +- Added in version 3.1.0. - Fixed use of freed or relocated memory when `apply_patch` is `#!cpp *this` or refers to a value contained in `#!cpp *this`, in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/basic_json/operator+=.md b/docs/mkdocs/docs/api/basic_json/operator+=.md index a3dc61b..3aee3f2 100644 --- a/docs/mkdocs/docs/api/basic_json/operator+=.md +++ b/docs/mkdocs/docs/api/basic_json/operator+=.md
@@ -128,6 +128,6 @@ ## Version history -1. Since version 1.0.0. -2. Since version 1.0.0. -3. Since version 2.0.0. +1. Added in version 1.0.0. +2. Added in version 1.0.0. +3. Added in version 2.0.0.
diff --git "a/docs/mkdocs/docs/api/basic_json/operator\133\135.md" "b/docs/mkdocs/docs/api/basic_json/operator\133\135.md" index d8df9b7..4356969 100644 --- "a/docs/mkdocs/docs/api/basic_json/operator\133\135.md" +++ "b/docs/mkdocs/docs/api/basic_json/operator\133\135.md"
@@ -284,10 +284,10 @@ 1. Added in version 1.0.0. Fixed in version 3.13.0 to throw `#!cpp std::length_error` instead of emptying the array and accessing it out of bounds when `idx` equals the maximum value of `size_type`. A missing index in the const version is guarded by a runtime assertion since version 3.13.0. -2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) - in version 3.11.0. -3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as - already supported by [`at`](at.md), [`value`](value.md), [`find`](find.md), and other lookup functions. +2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. The `T* key` overloads forward to + overload 3 since version 3.11.0. +3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently + across the lookup functions. 4. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
diff --git a/docs/mkdocs/docs/api/basic_json/operator_ValueType.md b/docs/mkdocs/docs/api/basic_json/operator_ValueType.md index 48abfb3..dca5ebf 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_ValueType.md +++ b/docs/mkdocs/docs/api/basic_json/operator_ValueType.md
@@ -89,6 +89,6 @@ ## Version history -- Since version 1.0.0. +- Added in version 1.0.0. - Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added in version 3.9.0.
diff --git a/docs/mkdocs/docs/api/basic_json/other_error.md b/docs/mkdocs/docs/api/basic_json/other_error.md index 7019e75..6149cc3 100644 --- a/docs/mkdocs/docs/api/basic_json/other_error.md +++ b/docs/mkdocs/docs/api/basic_json/other_error.md
@@ -75,4 +75,4 @@ ## Version history -- Since version 3.0.0. +- Added in version 3.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/out_of_range.md b/docs/mkdocs/docs/api/basic_json/out_of_range.md index e1e54ae..be579b3 100644 --- a/docs/mkdocs/docs/api/basic_json/out_of_range.md +++ b/docs/mkdocs/docs/api/basic_json/out_of_range.md
@@ -76,4 +76,4 @@ ## Version history -- Since version 3.0.0. +- Added in version 3.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/parse_error.md b/docs/mkdocs/docs/api/basic_json/parse_error.md index c3f49ef..0daae8d 100644 --- a/docs/mkdocs/docs/api/basic_json/parse_error.md +++ b/docs/mkdocs/docs/api/basic_json/parse_error.md
@@ -84,4 +84,4 @@ ## Version history -- Since version 3.0.0. +- Added in version 3.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/push_back.md b/docs/mkdocs/docs/api/basic_json/push_back.md index 386a589..f6ed6a4 100644 --- a/docs/mkdocs/docs/api/basic_json/push_back.md +++ b/docs/mkdocs/docs/api/basic_json/push_back.md
@@ -125,6 +125,6 @@ ## Version history -1. Since version 1.0.0. -2. Since version 1.0.0. -3. Since version 2.0.0. +1. Added in version 1.0.0. +2. Added in version 1.0.0. +3. Added in version 2.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/swap.md b/docs/mkdocs/docs/api/basic_json/swap.md index 4704852..4bc36b1 100644 --- a/docs/mkdocs/docs/api/basic_json/swap.md +++ b/docs/mkdocs/docs/api/basic_json/swap.md
@@ -182,10 +182,10 @@ ## Version history -1. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0. -2. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0. -3. Since version 1.0.0. -4. Since version 1.0.0. -5. Since version 1.0.0. -6. Since version 3.8.0. -7. Since version 3.8.0. \ No newline at end of file +1. Added in version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0. +2. Added in version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0. +3. Added in version 1.0.0. +4. Added in version 1.0.0. +5. Added in version 1.0.0. +6. Added in version 3.8.0. +7. Added in version 3.8.0. \ No newline at end of file
diff --git a/docs/mkdocs/docs/api/basic_json/to_bjdata.md b/docs/mkdocs/docs/api/basic_json/to_bjdata.md index aa0240a..a85d8ff 100644 --- a/docs/mkdocs/docs/api/basic_json/to_bjdata.md +++ b/docs/mkdocs/docs/api/basic_json/to_bjdata.md
@@ -124,5 +124,3 @@ [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`. - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an array or object was silently skipped, producing invalid BJData. -- Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0; previously, they were - silently truncated to 64 bits. \ No newline at end of file
diff --git a/docs/mkdocs/docs/api/basic_json/type_error.md b/docs/mkdocs/docs/api/basic_json/type_error.md index b13fdd2..dcc30b2 100644 --- a/docs/mkdocs/docs/api/basic_json/type_error.md +++ b/docs/mkdocs/docs/api/basic_json/type_error.md
@@ -76,4 +76,4 @@ ## Version history -- Since version 3.0.0. +- Added in version 3.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/value.md b/docs/mkdocs/docs/api/basic_json/value.md index 12293fd..aee09a5 100644 --- a/docs/mkdocs/docs/api/basic_json/value.md +++ b/docs/mkdocs/docs/api/basic_json/value.md
@@ -231,11 +231,8 @@ 1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version 3.11.0. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime. -2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Fixed in version 3.13.0 - to consistently accept `std::string_view`-convertible keys, as already supported by - [`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md), and other lookup functions. -3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving - `ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or - `default_value`, as documented). Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) +2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Support for keys + convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions. +3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of returning `default_value` for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
diff --git a/docs/mkdocs/docs/api/basic_json_document/index.md b/docs/mkdocs/docs/api/basic_json_document/index.md index d132195..f2cc375 100644 --- a/docs/mkdocs/docs/api/basic_json_document/index.md +++ b/docs/mkdocs/docs/api/basic_json_document/index.md
@@ -115,6 +115,13 @@ [`source_offset()`](../basic_json_view/source_offset.md) of a value introduced by an edit is `#!cpp static_cast<std::size_t>(-1)`, the same value it reports for a decoded string. +## See also + +- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views +- [**basic_json_view**](../basic_json_view/index.md) - the non-owning handle to a value in a document +- [**json_document**](../json_document.md) and [**json_editable_document**](../json_editable_document.md) - the default specializations +- [**materialize**](../basic_json_view/materialize.md) - build a `basic_json` value from a view + ## Version history - Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/basic_json_view/index.md b/docs/mkdocs/docs/api/basic_json_view/index.md index 4d6d7dd..5f0d906 100644 --- a/docs/mkdocs/docs/api/basic_json_view/index.md +++ b/docs/mkdocs/docs/api/basic_json_view/index.md
@@ -143,6 +143,13 @@ - [**source_offset**](source_offset.md) - byte offset of this value in the document's source text +## See also + +- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views +- [**basic_json_document**](../basic_json_document/index.md) - the document that owns the parsed data +- [**json_view**](../json_view.md) and [**json_editable_view**](../json_editable_view.md) - the default specializations +- [**materialize**](materialize.md) - build a `basic_json` value from a view + ## Version history - Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md b/docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md index 23d5c9b..62b0e24 100644 --- a/docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md +++ b/docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md
@@ -51,4 +51,4 @@ ## Version history -Since version 3.8.0. +Added in version 3.8.0.
diff --git a/docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md b/docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md index 7fd8fe9..ec2e617 100644 --- a/docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md +++ b/docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md
@@ -39,4 +39,4 @@ ## Version history -Since version 3.8.0. +Added in version 3.8.0.
diff --git a/docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md b/docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md index 98596da..e22429f 100644 --- a/docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md +++ b/docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md
@@ -42,4 +42,4 @@ ## Version history -Since version 3.8.0. +Added in version 3.8.0.
diff --git a/docs/mkdocs/docs/api/byte_container_with_subtype/index.md b/docs/mkdocs/docs/api/byte_container_with_subtype/index.md index cb5a378..b184d84 100644 --- a/docs/mkdocs/docs/api/byte_container_with_subtype/index.md +++ b/docs/mkdocs/docs/api/byte_container_with_subtype/index.md
@@ -29,6 +29,14 @@ - [**has_subtype**](has_subtype.md) - return whether the value has a subtype - [**clear_subtype**](clear_subtype.md) - clears the binary subtype +## See also + +- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled +- [**binary**](../basic_json/binary.md) - create a binary array value +- [**get_binary**](../basic_json/get_binary.md) - get a reference to the stored binary value +- [**binary_t**](../basic_json/binary_t.md) - type for binary arrays +- [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values + ## Version history - Added in version 3.8.0.
diff --git a/docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md b/docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md index 6cd319e..281de5a 100644 --- a/docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md +++ b/docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md
@@ -44,4 +44,4 @@ ## Version history -Since version 3.8.0. +Added in version 3.8.0.
diff --git a/docs/mkdocs/docs/api/json.md b/docs/mkdocs/docs/api/json.md index 55504ef..b41b691 100644 --- a/docs/mkdocs/docs/api/json.md +++ b/docs/mkdocs/docs/api/json.md
@@ -30,4 +30,4 @@ ## Version history -Since version 1.0.0. +Added in version 1.0.0.
diff --git a/docs/mkdocs/docs/api/json_document.md b/docs/mkdocs/docs/api/json_document.md index ea365ba..cfa22e8 100644 --- a/docs/mkdocs/docs/api/json_document.md +++ b/docs/mkdocs/docs/api/json_document.md
@@ -32,4 +32,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/json_editable_document.md b/docs/mkdocs/docs/api/json_editable_document.md index ab3fc38..ec5226b 100644 --- a/docs/mkdocs/docs/api/json_editable_document.md +++ b/docs/mkdocs/docs/api/json_editable_document.md
@@ -40,4 +40,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/json_editable_view.md b/docs/mkdocs/docs/api/json_editable_view.md index f5fa59e..ddee4e3 100644 --- a/docs/mkdocs/docs/api/json_editable_view.md +++ b/docs/mkdocs/docs/api/json_editable_view.md
@@ -38,4 +38,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/json_pointer/operator_string_t.md b/docs/mkdocs/docs/api/json_pointer/operator_string_t.md index 9fd8bce..44dde73 100644 --- a/docs/mkdocs/docs/api/json_pointer/operator_string_t.md +++ b/docs/mkdocs/docs/api/json_pointer/operator_string_t.md
@@ -51,5 +51,5 @@ ## Version history -- Since version 2.0.0. +- Added in version 2.0.0. - Changed type to `string_t` and deprecated in version 3.11.0.
diff --git a/docs/mkdocs/docs/api/json_pointer/to_string.md b/docs/mkdocs/docs/api/json_pointer/to_string.md index 2f700e1..b994ff8 100644 --- a/docs/mkdocs/docs/api/json_pointer/to_string.md +++ b/docs/mkdocs/docs/api/json_pointer/to_string.md
@@ -49,5 +49,5 @@ ## Version history -- Since version 2.0.0. +- Added in version 2.0.0. - Changed return type to `string_t` in version 3.11.0.
diff --git a/docs/mkdocs/docs/api/json_sax/index.md b/docs/mkdocs/docs/api/json_sax/index.md index 19d0a52..fec1e04 100644 --- a/docs/mkdocs/docs/api/json_sax/index.md +++ b/docs/mkdocs/docs/api/json_sax/index.md
@@ -59,6 +59,13 @@ - [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read - [**string**](string.md) (_virtual_) - a string value was read +## See also + +- [SAX interface](../../features/parsing/sax_interface.md) - guide to event-based parsing +- [**sax_parse**](../basic_json/sax_parse.md) - generate SAX events from an input +- [**parse**](../basic_json/parse.md) - DOM parsing, with optional [parser callbacks](../../features/parsing/parser_callbacks.md) +- [Parse exceptions](../../features/parsing/parse_exceptions.md) + ## Version history - Added in version 3.2.0.
diff --git a/docs/mkdocs/docs/api/json_view.md b/docs/mkdocs/docs/api/json_view.md index 819dfe5..89229ed 100644 --- a/docs/mkdocs/docs/api/json_view.md +++ b/docs/mkdocs/docs/api/json_view.md
@@ -31,4 +31,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/macros/index.md b/docs/mkdocs/docs/api/macros/index.md index 1230cd0..ae11a60 100644 --- a/docs/mkdocs/docs/api/macros/index.md +++ b/docs/mkdocs/docs/api/macros/index.md
@@ -137,4 +137,13 @@ - [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES**](nlohmann_define_type_with_names.md) - serialize/deserialize a derived class; uses default values; uses custom names - [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES**](nlohmann_define_type_with_names.md) - serialize a derived - class; uses custom names \ No newline at end of file + class; uses custom names + +## See also + +- [Macros](../../features/macros.md) - guide to the supported macros +- [Runtime assertions](../../features/assertions.md) +- [Arbitrary type conversions](../../features/arbitrary_types.md) - using the `NLOHMANN_DEFINE_TYPE_*` macros +- [Enum conversion](../../features/enum_conversion.md) - using `NLOHMANN_JSON_SERIALIZE_ENUM` +- [The `nlohmann` namespace](../../features/namespace.md) +- [CMake integration](../../integration/cmake.md) - setting macros from the build system
diff --git a/docs/mkdocs/docs/api/ordered_json.md b/docs/mkdocs/docs/api/ordered_json.md index feea642..30f295f 100644 --- a/docs/mkdocs/docs/api/ordered_json.md +++ b/docs/mkdocs/docs/api/ordered_json.md
@@ -42,4 +42,4 @@ ## Version history -Since version 3.9.0. +Added in version 3.9.0.
diff --git a/docs/mkdocs/docs/api/ordered_json_document.md b/docs/mkdocs/docs/api/ordered_json_document.md index dd6760e..b737c2e 100644 --- a/docs/mkdocs/docs/api/ordered_json_document.md +++ b/docs/mkdocs/docs/api/ordered_json_document.md
@@ -35,4 +35,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/ordered_json_editable_document.md b/docs/mkdocs/docs/api/ordered_json_editable_document.md index 3127eea..cf86307 100644 --- a/docs/mkdocs/docs/api/ordered_json_editable_document.md +++ b/docs/mkdocs/docs/api/ordered_json_editable_document.md
@@ -44,4 +44,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/ordered_json_editable_view.md b/docs/mkdocs/docs/api/ordered_json_editable_view.md index 7835112..1c9953d 100644 --- a/docs/mkdocs/docs/api/ordered_json_editable_view.md +++ b/docs/mkdocs/docs/api/ordered_json_editable_view.md
@@ -37,4 +37,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/ordered_json_view.md b/docs/mkdocs/docs/api/ordered_json_view.md index 9800b07..9df7204 100644 --- a/docs/mkdocs/docs/api/ordered_json_view.md +++ b/docs/mkdocs/docs/api/ordered_json_view.md
@@ -32,4 +32,4 @@ ## Version history -Since version 3.13.0. +Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/community/roadmap.md b/docs/mkdocs/docs/community/roadmap.md index 1b1f287..d294bd5 100644 --- a/docs/mkdocs/docs/community/roadmap.md +++ b/docs/mkdocs/docs/community/roadmap.md
@@ -58,7 +58,7 @@ - remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does. Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are -documented in the [release notes](../home/releases.md). +documented in the [release notes](../home/releases/index.md). The following are **not** part of the public API and may change in any release, including patch releases:
diff --git a/docs/mkdocs/docs/css/custom.css b/docs/mkdocs/docs/css/custom.css index 1fec0e5..133609e 100644 --- a/docs/mkdocs/docs/css/custom.css +++ b/docs/mkdocs/docs/css/custom.css
@@ -18,3 +18,32 @@ white-space: nowrap; cursor: help; } + +/* byte layout tables of the binary formats */ +.md-typeset .byte-layout td code { + white-space: pre-wrap; +} + +.md-typeset .bl { + display: inline-block; + padding: 0 .25em; + border-radius: .2em; + font-family: var(--md-code-font-family); + font-size: .85em; + white-space: nowrap; +} + +.md-typeset .bl-t { + background-color: rgba(66, 133, 244, .25); + box-shadow: inset 0 -.12em 0 rgba(66, 133, 244, .8); +} + +.md-typeset .bl-l { + background-color: rgba(251, 140, 0, .25); + box-shadow: inset 0 -.12em 0 rgba(251, 140, 0, .8); +} + +.md-typeset .bl-d { + background-color: rgba(67, 160, 71, .25); + box-shadow: inset 0 -.12em 0 rgba(67, 160, 71, .8); +}
diff --git a/docs/mkdocs/docs/features/binary_formats/bjdata.md b/docs/mkdocs/docs/features/binary_formats/bjdata.md index 12ef19d..4591652 100644 --- a/docs/mkdocs/docs/features/binary_formats/bjdata.md +++ b/docs/mkdocs/docs/features/binary_formats/bjdata.md
@@ -190,6 +190,41 @@ --8<-- "examples/to_bjdata.output" ``` + + + + +### Byte layout + +Consider the following JSON value (shown formatted for readability): + +```json +{ + "id": 300, + "name": "json", + "pi": 3.14, + "tags": [ + "a", + "b" + ] +} +``` + +`to_bjdata` encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>. + +<div class="byte-layout" markdown="0"><table> +<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> +<tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr> +<tr><td><code>"id": 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">2C 01</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), little-endian</td></tr> +<tr><td><code>"name": "json",</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr> +<tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>key: length 2; value: float64 (<code>D</code>), little-endian</td></tr> +<tr><td><code>"tags": [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr> +<tr><td><code>"a",</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr> +<tr><td><code>"b"</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr> +<tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr> +<tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr> +</tbody></table></div> + ## Deserialization The library maps BJData types to JSON value types as follows:
diff --git a/docs/mkdocs/docs/features/binary_formats/bon8.md b/docs/mkdocs/docs/features/binary_formats/bon8.md index d2d20da..555942d 100644 --- a/docs/mkdocs/docs/features/binary_formats/bon8.md +++ b/docs/mkdocs/docs/features/binary_formats/bon8.md
@@ -105,6 +105,41 @@ --8<-- "examples/to_bon8.output" ``` + + + + +### Byte layout + +Consider the following JSON value (shown formatted for readability): + +```json +{ + "id": 300, + "name": "json", + "pi": 3.14, + "tags": [ + "a", + "b" + ] +} +``` + +`to_bon8` encodes it to 35 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>. + +<div class="byte-layout" markdown="0"><table> +<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> +<tr><td><code>{</code></td><td><span class="bl bl-t">8A</span></td><td>object with 4 members</td></tr> +<tr><td><code>"id": 300,</code></td><td><span class="bl bl-d">69 64</span> <span class="bl bl-t">C4</span> <span class="bl bl-d">04</span></td><td>key: UTF-8 bytes; the string ends at the next byte, which cannot continue a UTF-8 character; value: 2-byte positive integer (lead byte, then a byte below 0x80)</td></tr> +<tr><td><code>"name": "json",</code></td><td><span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-l">FF</span> <span class="bl bl-d">6A 73 6F 6E</span> <span class="bl bl-l">FF</span></td><td>key: UTF-8 bytes; 0xFF terminates the string as another string follows; value: UTF-8 bytes; terminated as a string key follows</td></tr> +<tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-d">70 69</span> <span class="bl bl-t">8F</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: UTF-8 bytes; value: binary64 (IEEE 754, big-endian); its marker also ends <code>"pi"</code></td></tr> +<tr><td><code>"tags": [</code></td><td><span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">82</span></td><td>key: UTF-8 bytes; value: array with 2 elements; its marker also ends <code>"tags"</code></td></tr> +<tr><td><code>"a",</code></td><td><span class="bl bl-d">61</span> <span class="bl bl-l">FF</span></td><td>UTF-8 bytes; terminated as a string follows</td></tr> +<tr><td><code>"b"</code></td><td><span class="bl bl-d">62</span> <span class="bl bl-l">FF</span></td><td>UTF-8 bytes; terminated as nothing follows</td></tr> +<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr> +<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr> +</tbody></table></div> + ## Deserialization The library maps BON8 types to JSON value types as follows:
diff --git a/docs/mkdocs/docs/features/binary_formats/bson.md b/docs/mkdocs/docs/features/binary_formats/bson.md index f205cba..7a9f78d 100644 --- a/docs/mkdocs/docs/features/binary_formats/bson.md +++ b/docs/mkdocs/docs/features/binary_formats/bson.md
@@ -61,6 +61,41 @@ ``` + + + + +### Byte layout + +Consider the following JSON value (shown formatted for readability): + +```json +{ + "id": 300, + "name": "json", + "pi": 3.14, + "tags": [ + "a", + "b" + ] +} +``` + +`to_bson` encodes it to 69 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>. + +<div class="byte-layout" markdown="0"><table> +<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> +<tr><td><code>{</code></td><td><span class="bl bl-l">45 00 00 00</span></td><td>document size: 69 bytes (int32, little-endian)</td></tr> +<tr><td><code>"id": 300,</code></td><td><span class="bl bl-t">10</span> <span class="bl bl-d">69 64 00</span> <span class="bl bl-d">2C 01 00 00</span></td><td>int32 element; key as NUL-terminated string; value (little-endian)</td></tr> +<tr><td><code>"name": "json",</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">6E 61 6D 65 00</span> <span class="bl bl-l">05 00 00 00</span> <span class="bl bl-d">6A 73 6F 6E 00</span></td><td>string element; key; length incl. NUL (int32); NUL-terminated UTF-8 bytes</td></tr> +<tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-t">01</span> <span class="bl bl-d">70 69 00</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>double element; key; value (little-endian)</td></tr> +<tr><td><code>"tags": [</code></td><td><span class="bl bl-t">04</span> <span class="bl bl-d">74 61 67 73 00</span> <span class="bl bl-l">17 00 00 00</span></td><td>array element; key; embedded document of 23 bytes (keys are the indices)</td></tr> +<tr><td><code>"a",</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">30 00</span> <span class="bl bl-l">02 00 00 00</span> <span class="bl bl-d">61 00</span></td><td>string element; key <code>"0"</code>; length 2; <code>a</code> + NUL</td></tr> +<tr><td><code>"b"</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">31 00</span> <span class="bl bl-l">02 00 00 00</span> <span class="bl bl-d">62 00</span></td><td>string element; key <code>"1"</code>; length 2; <code>b</code> + NUL</td></tr> +<tr><td><code>]</code></td><td><span class="bl bl-t">00</span></td><td>end of the array document</td></tr> +<tr><td><code>}</code></td><td><span class="bl bl-t">00</span></td><td>end of the document</td></tr> +</tbody></table></div> + ## Deserialization The library maps BSON record types to JSON value types as follows:
diff --git a/docs/mkdocs/docs/features/binary_formats/cbor.md b/docs/mkdocs/docs/features/binary_formats/cbor.md index a0a0ed8..20f9230 100644 --- a/docs/mkdocs/docs/features/binary_formats/cbor.md +++ b/docs/mkdocs/docs/features/binary_formats/cbor.md
@@ -110,6 +110,41 @@ --8<-- "examples/to_cbor.output" ``` + + + + +### Byte layout + +Consider the following JSON value (shown formatted for readability): + +```json +{ + "id": 300, + "name": "json", + "pi": 3.14, + "tags": [ + "a", + "b" + ] +} +``` + +`to_cbor` encodes it to 39 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>. + +<div class="byte-layout" markdown="0"><table> +<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> +<tr><td><code>{</code></td><td><span class="bl bl-t">A4</span></td><td>map with 4 key/value pairs</td></tr> +<tr><td><code>"id": 300,</code></td><td><span class="bl bl-t">62</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">19</span> <span class="bl bl-d">01 2C</span></td><td>key: text string of length 2, then its UTF-8 bytes; value: unsigned integer, 2 bytes follow (big-endian)</td></tr> +<tr><td><code>"name": "json",</code></td><td><span class="bl bl-t">64</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">64</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: text string of length 4; value: text string of length 4</td></tr> +<tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-t">62</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">FB</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: text string of length 2; value: double-precision float (IEEE 754, big-endian)</td></tr> +<tr><td><code>"tags": [</code></td><td><span class="bl bl-t">64</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">82</span></td><td>key: text string of length 4; value: array with 2 elements</td></tr> +<tr><td><code>"a",</code></td><td><span class="bl bl-t">61</span> <span class="bl bl-d">61</span></td><td>text string of length 1</td></tr> +<tr><td><code>"b"</code></td><td><span class="bl bl-t">61</span> <span class="bl bl-d">62</span></td><td>text string of length 1</td></tr> +<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr> +<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr> +</tbody></table></div> + ## Deserialization The library maps CBOR types to JSON value types as follows:
diff --git a/docs/mkdocs/docs/features/binary_formats/index.md b/docs/mkdocs/docs/features/binary_formats/index.md index 2c45995..8024b99 100644 --- a/docs/mkdocs/docs/features/binary_formats/index.md +++ b/docs/mkdocs/docs/features/binary_formats/index.md
@@ -45,12 +45,19 @@ | BJData | 53.2 % | 91.1 % | 78.1 % | 96.6 % | | BJData (size) | 58.6 % | 92.1 % | 86.7 % | 97.4 % | | BJData (size+type) | 58.6 % | 92.1 % | 86.5 % | 97.4 % | -| BON8 | 50.5 % | 83.8 % | 63.5 % | 87.5 % | +| BON8 | **50.5 %** | **83.8 %** | **63.5 %** | **87.5 %** | | BSON | 85.8 % | 95.2 % | 95.8 % | 106.7 % | -| CBOR | 50.5 % | 86.3 % | 68.4 % | 88.0 % | -| MessagePack | 50.5 % | 86.0 % | 68.5 % | 87.9 % | +| CBOR | **50.5 %** | 86.3 % | 68.4 % | 88.0 % | +| MessagePack | **50.5 %** | 86.0 % | 68.5 % | 87.9 % | | UBJSON | 53.2 % | 91.3 % | 78.2 % | 96.6 % | | UBJSON (size) | 58.6 % | 92.3 % | 86.8 % | 97.4 % | | UBJSON (size+type) | 55.9 % | 92.3 % | 85.0 % | 95.0 % | -Sizes compared to minified JSON value. +Sizes compared to minified JSON value; the smallest size per file is printed in bold. + +## See also + +- [Binary values](../binary_values.md) - binary values and subtypes +- [**to_cbor**](../../api/basic_json/to_cbor.md) / [**from_cbor**](../../api/basic_json/from_cbor.md), [**to_msgpack**](../../api/basic_json/to_msgpack.md) / [**from_msgpack**](../../api/basic_json/from_msgpack.md), [**to_bson**](../../api/basic_json/to_bson.md) / [**from_bson**](../../api/basic_json/from_bson.md), [**to_ubjson**](../../api/basic_json/to_ubjson.md) / [**from_ubjson**](../../api/basic_json/from_ubjson.md), [**to_bjdata**](../../api/basic_json/to_bjdata.md) / [**from_bjdata**](../../api/basic_json/from_bjdata.md), [**to_bon8**](../../api/basic_json/to_bon8.md) / [**from_bon8**](../../api/basic_json/from_bon8.md) - the conversion functions +- [Parsing untrusted input](../parsing/untrusted_input.md) +- [SAX interface](../parsing/sax_interface.md) - decode binary formats without building a value
diff --git a/docs/mkdocs/docs/features/binary_formats/messagepack.md b/docs/mkdocs/docs/features/binary_formats/messagepack.md index 24eeab1..3bdd1a1 100644 --- a/docs/mkdocs/docs/features/binary_formats/messagepack.md +++ b/docs/mkdocs/docs/features/binary_formats/messagepack.md
@@ -91,6 +91,41 @@ --8<-- "examples/to_msgpack.output" ``` + + + + +### Byte layout + +Consider the following JSON value (shown formatted for readability): + +```json +{ + "id": 300, + "name": "json", + "pi": 3.14, + "tags": [ + "a", + "b" + ] +} +``` + +`to_msgpack` encodes it to 39 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>. + +<div class="byte-layout" markdown="0"><table> +<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> +<tr><td><code>{</code></td><td><span class="bl bl-t">84</span></td><td>map with 4 key/value pairs</td></tr> +<tr><td><code>"id": 300,</code></td><td><span class="bl bl-t">A2</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">CD</span> <span class="bl bl-d">01 2C</span></td><td>key: fixstr of length 2, then its UTF-8 bytes; value: uint 16 (big-endian)</td></tr> +<tr><td><code>"name": "json",</code></td><td><span class="bl bl-t">A4</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">A4</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: fixstr of length 4; value: fixstr of length 4</td></tr> +<tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-t">A2</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">CB</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: fixstr of length 2; value: float 64 (IEEE 754, big-endian)</td></tr> +<tr><td><code>"tags": [</code></td><td><span class="bl bl-t">A4</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">92</span></td><td>key: fixstr of length 4; value: fixarray with 2 elements</td></tr> +<tr><td><code>"a",</code></td><td><span class="bl bl-t">A1</span> <span class="bl bl-d">61</span></td><td>fixstr of length 1</td></tr> +<tr><td><code>"b"</code></td><td><span class="bl bl-t">A1</span> <span class="bl bl-d">62</span></td><td>fixstr of length 1</td></tr> +<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr> +<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr> +</tbody></table></div> + ## Deserialization The library maps MessagePack types to JSON value types as follows:
diff --git a/docs/mkdocs/docs/features/binary_formats/ubjson.md b/docs/mkdocs/docs/features/binary_formats/ubjson.md index f7a14d8..6b79736 100644 --- a/docs/mkdocs/docs/features/binary_formats/ubjson.md +++ b/docs/mkdocs/docs/features/binary_formats/ubjson.md
@@ -103,6 +103,41 @@ --8<-- "examples/to_ubjson.output" ``` + + + + +### Byte layout + +Consider the following JSON value (shown formatted for readability): + +```json +{ + "id": 300, + "name": "json", + "pi": 3.14, + "tags": [ + "a", + "b" + ] +} +``` + +`to_ubjson` encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>. + +<div class="byte-layout" markdown="0"><table> +<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> +<tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr> +<tr><td><code>"id": 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">01 2C</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), big-endian</td></tr> +<tr><td><code>"name": "json",</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr> +<tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: length 2; value: float64 (<code>D</code>), big-endian</td></tr> +<tr><td><code>"tags": [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr> +<tr><td><code>"a",</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr> +<tr><td><code>"b"</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr> +<tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr> +<tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr> +</tbody></table></div> + ## Deserialization The library maps UBJSON types to JSON value types as follows:
diff --git a/docs/mkdocs/docs/features/element_access/index.md b/docs/mkdocs/docs/features/element_access/index.md index 262c057..17d0a56 100644 --- a/docs/mkdocs/docs/features/element_access/index.md +++ b/docs/mkdocs/docs/features/element_access/index.md
@@ -21,3 +21,12 @@ A --> F{"just testing first?"} F -->|"yes"| G["contains() / find()"] ``` + +## See also + +- [**operator[]**](../../api/basic_json/operator%5B%5D.md) - unchecked access +- [**at**](../../api/basic_json/at.md) - checked access +- [**value**](../../api/basic_json/value.md) - access with default value +- [**contains**](../../api/basic_json/contains.md) and [**find**](../../api/basic_json/find.md) - test for existence +- [**front**](../../api/basic_json/front.md) and [**back**](../../api/basic_json/back.md) - first and last element +- [**items**](../../api/basic_json/items.md) - iterate over keys and values
diff --git a/docs/mkdocs/docs/features/index.md b/docs/mkdocs/docs/features/index.md index 4ffe7e5..88443c7 100644 --- a/docs/mkdocs/docs/features/index.md +++ b/docs/mkdocs/docs/features/index.md
@@ -59,3 +59,11 @@ This section gives conceptual overviews. For the precise signature, parameters, and return value of a function, see the [API Documentation](../api/basic_json/index.md). + +## See also + +- [API documentation](../api/basic_json/index.md) - reference of all classes and functions +- [FAQ](../home/faq.md) - answers to common questions +- [Exceptions](../home/exceptions.md) - all exceptions and their error codes +- [Design goals](../home/design_goals.md) +- [Integration](../integration/index.md) - how to add the library to a project
diff --git a/docs/mkdocs/docs/features/types/index.md b/docs/mkdocs/docs/features/types/index.md index 67e97df..03e8c0b 100644 --- a/docs/mkdocs/docs/features/types/index.md +++ b/docs/mkdocs/docs/features/types/index.md
@@ -286,3 +286,12 @@ ### Storage Integer number values, unsigned integer number values, and floating-point number values are stored directly inside a `basic_json` type. + +## See also + +- [Number handling](number_handling.md) - how numbers are stored and converted +- [Template parameter requirements](template_parameters.md) +- [**basic_json**](../../api/basic_json/index.md) - the class template and its member types +- [**type**](../../api/basic_json/type.md) and [**value_t**](../../api/basic_json/value_t.md) - query the type of a value +- [**object_t**](../../api/basic_json/object_t.md), [**array_t**](../../api/basic_json/array_t.md), [**string_t**](../../api/basic_json/string_t.md), [**number_integer_t**](../../api/basic_json/number_integer_t.md), [**number_float_t**](../../api/basic_json/number_float_t.md) - the underlying types +- [Object order](../object_order.md)
diff --git a/docs/mkdocs/docs/home/releases.md b/docs/mkdocs/docs/home/releases.md deleted file mode 100644 index c086527..0000000 --- a/docs/mkdocs/docs/home/releases.md +++ /dev/null
@@ -1,453 +0,0 @@ -# Releases - -This page summarizes the notable changes of every release and links to the relevant documentation. -The **complete release notes** — including all changes, the download files, and their checksums — are -published on the [GitHub releases page](https://github.com/nlohmann/json/releases). - -!!! info "Unreleased changes" - - This documentation is built from the `develop` branch and may describe changes that are not part of a release - yet. Their version numbers are followed by an <span class="unreleased-version">unreleased</span> badge. - -## Unreleased - -- Converting an rvalue container to JSON (`json j = std::move(vec);`, `json j = std::map<std::string, std::string>{...};`) - now **moves** the elements instead of copying them (e.g., `std::vector<std::string>` with 100,000 strings: 4.7 ms to - 2.3 ms). Two consequences: the source container is left in a valid but unspecified (moved-from) state, and if an - exception is thrown during the conversion, the source may be partially moved-from, so the strong exception guarantee - no longer holds for the source of an rvalue conversion (the JSON value itself is unaffected). Lvalues and `const` - objects are still copied. See [`basic_json`](../api/basic_json/basic_json.md). - -## v3.12.0 (2025-04-11) - -Fixes bugs found in 3.11.3 and adds several features. All changes are backward-compatible. - -- Adds diagnostic byte positions via [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md), - exposed through the new [`start_pos`](../api/basic_json/start_pos.md) and - [`end_pos`](../api/basic_json/end_pos.md) member functions. -- Makes the [conversion macros](../features/arbitrary_types.md#simplify-your-life-with-macros) - templated (so they also work with [`ordered_json`](../api/ordered_json.md)) and adds - [`NLOHMANN_DEFINE_DERIVED_TYPE`](../api/macros/nlohmann_define_derived_type.md) for derived classes. -- Adds `std::optional` support (C++17) and lets [`patch`](../api/basic_json/patch.md), - [`diff`](../api/basic_json/diff.md), and [`flatten`](../api/basic_json/flatten.md) work with - arbitrary string types. -- Extends the [binary formats](../features/binary_formats/index.md): - [BJData](../features/binary_formats/bjdata.md) draft 3 and unsigned 64-bit integers for - [BSON](../features/binary_formats/bson.md). -- Adds multidimensional C-array conversion and UTF-8 encoded `std::filesystem::path` conversions, and - raises the minimum [CMake](../integration/cmake.md) version to 3.5 and supports CMake 4.0. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.12.0). - -## v3.11.3 (2023-11-28) - -Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible. - -- Adds a [custom base class](../api/basic_json/json_base_class_t.md) as a node customization point. -- Adds serialization-only [conversion macros](../features/macros.md) - (`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE` and `NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE`) - and a clearer parse error for empty input. -- Adds [Bazel](../integration/package_managers.md#bazel) and - [Swift Package Manager](../integration/package_managers.md#swift-package-manager) build support. -- Fixes custom allocators, a memory leak in [`adl_serializer`](../api/adl_serializer/to_json.md)'s - `to_json`, initializer-list construction when `size_type` is not `int`, and many compiler warnings. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.3). - -## v3.11.2 (2022-08-12) - -Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible. - -- Fixes the [`value`](../api/basic_json/value.md) function (broken for strings, size types, and - `nullptr` in 3.11.0) and makes `json_fwd.hpp` self-contained. -- Restores using [`json_pointer`](../api/json_pointer/index.md) as a key in associative containers and - comparing it with strings. -- Restructures the inline [namespace](../features/namespace.md) and allows disabling the version - component, and avoids heap allocations in the [BJData](../features/binary_formats/bjdata.md) parser. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.2). - -## v3.11.1 (2022-08-01) - -Fixes a regression from 3.11.0. All changes are backward-compatible. - -- Restores the global [user-defined string literals](../api/macros/json_use_global_udls.md) - [`operator""_json`](../api/operator_literal_json.md) and - [`operator""_json_pointer`](../api/operator_literal_json_pointer.md), which 3.11.0 had moved into a - namespace by default. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.1). - -## v3.11.0 (2022-08-01) - -One of the largest releases ever. All changes are backward-compatible. - -- Allows `std::string_view` as object keys in [`at`](../api/basic_json/at.md), - [`operator[]`](../api/basic_json/operator%5B%5D.md), [`value`](../api/basic_json/value.md), - [`erase`](../api/basic_json/erase.md), [`find`](../api/basic_json/find.md), - [`contains`](../api/basic_json/contains.md), and [`count`](../api/basic_json/count.md). -- Adds the [BJData](../features/binary_formats/bjdata.md) binary format (the fifth supported format). -- Improves C++20 support, including [`operator<=>`](../api/basic_json/operator_spaceship.md) and - `<ranges>`-compatible iterators. -- Adds a versioned, ABI-tagged inline [namespace](../features/namespace.md) - ([`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md)) and the option to move the - UDLs out of the global namespace ([`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md)). -- Adds [`patch_inplace`](../api/basic_json/patch_inplace.md), default values for the - [conversion macros](../features/arbitrary_types.md#simplify-your-life-with-macros), and an option to - disable enum serialization ([`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md)). - -This release introduced a UDL regression that was fixed in -[3.11.1](https://github.com/nlohmann/json/releases/tag/v3.11.1). -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.0). - -## v3.10.5 (2022-01-03) - -Bug-fix release. All changes are backward-compatible. - -- Guards the `std::filesystem` conversions behind compiler-support checks - ([`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md)), which can be set to `0` to disable - them altogether. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.5). - -## v3.10.4 (2021-10-16) - -Fixes regressions introduced in 3.10.0. All changes are backward-compatible. - -- Fixes the `std::filesystem::path` conversion (which could trigger a stack overflow and broke - compilation on Windows). -- Fixes compilation for types with an explicit defaulted constructor and for code relying on the - return values of `std::find` and `std::remove`. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.4). - -## v3.10.3 (2021-10-08) - -Fixes more regressions from 3.10.0. All changes are backward-compatible. - -- Fixes [extended-diagnostics](../api/macros/json_diagnostics.md) assertions triggered by - [`update`](../api/basic_json/update.md) and by inserting into arrays. -- Supports custom allocators when writing binary formats into a `std::vector`, and allows conversion - from types that only provide `begin()`/`end()`. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.3). - -## v3.10.2 (2021-08-26) - -Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. -All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.2). - -## v3.10.1 (2021-08-24) - -Fixes a regression from 3.10.0. All changes are backward-compatible. - -- Fixes an [extended-diagnostics](../api/macros/json_diagnostics.md) assertion triggered when used - with [`ordered_json`](../api/ordered_json.md), and hardens the GDB pretty-printer. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.1). - -## v3.10.0 (2021-08-17) - -Feature release. All changes are backward-compatible. - -- Adds [extended diagnostic messages](../api/macros/json_diagnostics.md) - ([`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md)) that prepend a JSON pointer to exception - messages to pinpoint the offending value. -- Adds a GDB pretty-printer and a [`cbor_tag_handler_t`](../api/basic_json/cbor_tag_handler_t.md) - `store` option to keep CBOR tags as binary subtypes. -- Supports containers with non-default-constructible types and parsing from `std::byte`. -- Adds [`JSON_NO_IO`](../api/macros/json_no_io.md) to exclude the I/O headers and the - [`JSON_HAS_CPP_*`](../api/macros/json_has_cpp_11.md) macros to override the detected C++ standard. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.0). - -## v3.9.1 (2020-08-06) - -Fixes two regressions from 3.9.0. All changes are backward-compatible. - -- Accepts consecutive [comments](../features/comments.md) and completes the - [`ordered_json`](../api/ordered_json.md) interface (e.g. `ordered_json::parse`). - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.1). - -## v3.9.0 (2020-07-27) - -Feature release adding four long-requested features. All changes are backward-compatible. - -- Optional [comment](../features/comments.md) parsing in [`parse`](../api/basic_json/parse.md) via the - `ignore_comments` parameter. -- [`ordered_json`](../api/ordered_json.md) to preserve the [insertion order](../features/object_order.md) - of object keys. -- An option to switch off [implicit conversions](../api/macros/json_use_implicit_conversions.md). -- The [`NLOHMANN_DEFINE_TYPE_*`](../features/arbitrary_types.md#simplify-your-life-with-macros) - convenience macros, plus high-precision-number support for - [UBJSON](../features/binary_formats/ubjson.md) and CBOR tag handling. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.0). - -## v3.8.0 (2020-06-14) - -Feature release. All changes are backward-compatible. - -- Introduces a [binary value](../features/binary_values.md) type that is read from and written to - [CBOR](../features/binary_formats/cbor.md), [BSON](../features/binary_formats/bson.md), and - [MessagePack](../features/binary_formats/messagepack.md), and can be shared between formats. -- Generalizes the input adapters to read from any `LegacyInputIterator` container (3–10 % faster - parsing). -- Fixes [`contains`](../api/basic_json/contains.md) for JSON pointers and makes the binary - [`from_cbor`](../api/basic_json/from_cbor.md)/[`from_msgpack`](../api/basic_json/from_msgpack.md)/etc. - functions respect `allow_exceptions`. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.8.0). - -## v3.7.3 (2019-11-17) - -Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes -are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.3). - -## v3.7.2 (2019-11-10) - -Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing is now -bounded only by available memory. All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.2). - -## v3.7.1 (2019-11-06) - -Bug-fix release. All changes are backward-compatible. - -- Fixes a segmentation fault when serializing the `std::int64_t` minimum value and fixes - [`contains`](../api/basic_json/contains.md) for JSON pointers. -- Allows [`items`](../api/basic_json/items.md) with a custom string type and makes `json_pointer::back` - `const`. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.1). - -## v3.7.0 (2019-07-28) - -Convenience features and house-keeping. All changes are backward-compatible. - -- Adds a [`contains`](../api/basic_json/contains.md) overload that checks a JSON pointer without - throwing, a generic `to_string`, and a return value for - [`emplace_back`](../api/basic_json/emplace_back.md). - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.0). - -## v3.6.1 (2019-03-20) - -Fixes a regression (GCC 7/8 compilation) and a `<Windows.h>` build error introduced in 3.6.0. All -changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.1). - -## v3.6.0 (2019-03-20) - -Feature release. All changes are backward-compatible. - -- Reworks the [JSON pointer](../features/json_pointer.md) interface (`operator/`, `push_back`, - `parent_pointer`, …). -- Adds a [`contains`](../api/basic_json/contains.md) function to test for an object key and greatly - improves the performance of integer serialization. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.0). - -## v3.5.0 (2018-12-22) - -Feature release. All changes are backward-compatible. - -- Adds structured-binding support via the [`items`](../api/basic_json/items.md) function and reading - from `FILE*` in the [`parse`](../api/basic_json/parse.md) function. -- Fixes the `eofbit` handling on input streams and a bug in the BSON SAX parser. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.5.0). - -## v3.4.0 (2018-10-30) - -Feature release. All changes are backward-compatible. - -- Adds [BSON](../features/binary_formats/bson.md) read/write support. -- Adds configurable Unicode error handlers to [`dump`](../api/basic_json/dump.md) (throw, replace with - U+FFFD, or ignore) and the - [`NLOHMANN_JSON_SERIALIZE_ENUM`](../api/macros/nlohmann_json_serialize_enum.md) macro for - [enum conversion](../features/enum_conversion.md). -- Improves parse-error messages with line/column positions and context. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.4.0). - -## v3.3.0 (2018-10-05) - -Feature release. All changes are backward-compatible. - -- Adds GCC 4.8 support, the [`get_to`](../api/basic_json/get_to.md) function, and an overhauled and - documented [CMake](../integration/cmake.md) integration. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.3.0). - -## v3.2.0 (2018-08-20) - -Feature release. All changes are backward-compatible. - -- Adds a [SAX interface](../features/parsing/sax_interface.md) and a non-recursive parser. -- Adds parsing from wide-string types (`std::wstring`, `std::u16string`, `std::u32string`) and - `std::string_view` (C++17), and round-tripping of `std::map`/`std::unordered_map` with non-string - keys. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.2.0). - -## v3.1.2 (2018-03-14) - -Bug-fix release. All changes are backward-compatible. - -- Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser - and serializer. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.2). - -## v3.1.1 (2018-02-13) - -Bug-fix release. All changes are backward-compatible. - -- Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and - overflow detection for UBJSON containers. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.1). - -## v3.1.0 (2018-02-01) - -Feature release. All changes are backward-compatible. - -- Adds [UBJSON](../features/binary_formats/ubjson.md) read/write support and - [JSON Merge Patch](../features/merge_patch.md) via [`merge_patch`](../api/basic_json/merge_patch.md). -- Switches to the Grisu2 algorithm for short, round-trippable floating-point output, and splits the - header into [multiple files](../integration/index.md) with a forward-declaration header. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.0). - -## v3.0.1 (2017-12-29) - -Fixes small issues in the [JSON Pointer](../features/json_pointer.md) and -[JSON Patch](../features/json_patch.md) implementations (invalid "copy" targets and non-integer array -indices). All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.1). - -## v3.0.0 (2017-12-17) - -First 3.x release — a major release with breaking changes (see the -[migration guide](../integration/migration_guide.md)). - -- Introduces user-defined [exceptions](exceptions.md) (`json::exception` and subtypes, each with an - identifier). -- Adds a non-throwing [`accept`](../api/basic_json/accept.md) function and an `allow_exceptions` flag - for [`parse`](../api/basic_json/parse.md), and an [`update`](../api/basic_json/update.md) function to - merge objects. -- Adds streaming for CBOR and MessagePack and allows storing NaN/infinity. -- Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.0). - -## v2.1.1 (2017-02-25) - -Bug-fix release. All changes are backward-compatible. - -- Makes number parsing and serialization locale-independent with correct floating-point - round-tripping; released files are now GPG-signed. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.1). - -## v2.1.0 (2017-01-28) - -Feature release. All changes are backward-compatible. - -- Adds conversions from and to [arbitrary user-defined types](../features/arbitrary_types.md) via - `to_json`/`from_json`, the [`meta`](../api/basic_json/meta.md) function, and the option to switch off - exceptions ([`JSON_NOEXCEPTION`](../api/macros/json_noexception.md)). - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.0). - -## v2.0.10 (2017-01-02) - -Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All -changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.10). - -## v2.0.9 (2016-12-16) - -Adds the [CBOR](../features/binary_formats/cbor.md) and -[MessagePack](../features/binary_formats/messagepack.md) binary formats. All changes are -backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.9). - -## v2.0.8 (2016-12-02) - -Adds the [`emplace`](../api/basic_json/emplace.md) and -[`emplace_back`](../api/basic_json/emplace_back.md) functions and improves parsing and serialization -performance. All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.8). - -## v2.0.7 (2016-11-02) - -Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding -detection, surrogate pairs). All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.7). - -## v2.0.6 (2016-10-15) - -Fixes [`operator[]`](../api/basic_json/operator%5B%5D.md) for [JSON pointers](../features/json_pointer.md) -so that it creates missing values like the other overloads. All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.6). - -## v2.0.5 (2016-09-14) - -Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.5). - -## v2.0.4 (2016-09-11) - -Fixes stream end-of-file detection in the parser. All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.4). - -## v2.0.3 (2016-08-31) - -Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the -input-stream constructor in favor of the [`parse`](../api/basic_json/parse.md) function. All changes -are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.3). - -## v2.0.2 (2016-07-31) - -Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and -cleans up the code. All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.2). - -## v2.0.1 (2016-06-28) - -Fixes a performance regression in the [`dump`](../api/basic_json/dump.md) function by adjusting the -stream locale once per serialization. All changes are backward-compatible. -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.1). - -## v2.0.0 (2016-06-24) - -Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept` -and `constexpr` specifiers. - -- Adds [JSON Pointer](../features/json_pointer.md) support in [`at`](../api/basic_json/at.md) and - [`operator[]`](../api/basic_json/operator%5B%5D.md), plus [`flatten`](../api/basic_json/flatten.md) - and [`unflatten`](../api/basic_json/unflatten.md). -- Adds [JSON Patch](../features/json_patch.md) via [`diff`](../api/basic_json/diff.md) and - [`patch`](../api/basic_json/patch.md), unsigned 64-bit integer support, and locale-independent - serialization. - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.0). - -## v1.1.0 (2016-01-24) - -Bug-fix and feature release. All changes are backward-compatible. - -- Improves floating-point round-tripping, adds a `get_ref` accessor for stored values, and introduces - runtime [assertions](../features/assertions.md). - -[Full release notes](https://github.com/nlohmann/json/releases/tag/v1.1.0). - -## v1.0.0 (2015-12-28) - -First official release. [Full release notes](https://github.com/nlohmann/json/releases/tag/v1.0.0). - -## See also - -- [Migration Guide](../integration/migration_guide.md) — how to future-proof your code for the next - major version and replace deprecated functions.
diff --git a/docs/mkdocs/docs/home/releases/index.md b/docs/mkdocs/docs/home/releases/index.md new file mode 100644 index 0000000..e0dbca2 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/index.md
@@ -0,0 +1,155 @@ +# Releases + +This section summarizes the notable changes of every release and links to the relevant documentation. +The **complete release notes** — including all changes, the download files, and their checksums — are +published on the [GitHub releases page](https://github.com/nlohmann/json/releases). + +!!! info "Unreleased changes" + + This documentation is built from the `develop` branch and may describe changes that are not part of a release + yet. Their version numbers are followed by an <span class="unreleased-version">unreleased</span> badge. + +Every release has its own page with a summary of its notable changes and an overview of the API that was added or +changed in it. The API overview is generated from the "Version history" section of the +[API pages](../../api/basic_json/index.md); it is not a change log, but helps to see whether a feature is available in +the version you use. + +## Unreleased + +| Release | Date | Summary | +|---------|------|---------| +| [Unreleased](unreleased.md) | | Changes on the `develop` branch that are not part of a release yet. | + +## Version 3.12.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.12.0](v3.12.0.md) | 2025-04-11 | Fixes bugs found in 3.11.3 and adds several features. No public API was removed or renamed. | + +## Version 3.11.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.11.3](v3.11.3.md) | 2023-11-28 | Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible. | +| [v3.11.2](v3.11.2.md) | 2022-08-12 | Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible. | +| [v3.11.1](v3.11.1.md) | 2022-08-01 | Fixes a regression from 3.11.0. All changes are backward-compatible. | +| [v3.11.0](v3.11.0.md) | 2022-08-01 | One of the largest releases ever. All changes are backward-compatible. | + +## Version 3.10.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.10.5](v3.10.5.md) | 2022-01-03 | Bug-fix release. All changes are backward-compatible. | +| [v3.10.4](v3.10.4.md) | 2021-10-16 | Fixes regressions introduced in 3.10.0. All changes are backward-compatible. | +| [v3.10.3](v3.10.3.md) | 2021-10-08 | Fixes more regressions from 3.10.0. All changes are backward-compatible. | +| [v3.10.2](v3.10.2.md) | 2021-08-26 | Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. All changes are backward-compatible. | +| [v3.10.1](v3.10.1.md) | 2021-08-24 | Fixes a regression from 3.10.0. All changes are backward-compatible. | +| [v3.10.0](v3.10.0.md) | 2021-08-17 | Feature release. All changes are backward-compatible. | + +## Version 3.9.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.9.1](v3.9.1.md) | 2020-08-06 | Fixes two regressions from 3.9.0. All changes are backward-compatible. | +| [v3.9.0](v3.9.0.md) | 2020-07-27 | Feature release adding four long-requested features. All changes are backward-compatible. | + +## Version 3.8.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.8.0](v3.8.0.md) | 2020-06-14 | Feature release. All changes are backward-compatible. | + +## Version 3.7.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.7.3](v3.7.3.md) | 2019-11-17 | Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes are backward-compatible. | +| [v3.7.2](v3.7.2.md) | 2019-11-10 | Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing of JSON text is now bounded only by available memory (the binary-format parsers still recurse). All changes are backward-compatible. | +| [v3.7.1](v3.7.1.md) | 2019-11-06 | Bug-fix release. All changes are backward-compatible. | +| [v3.7.0](v3.7.0.md) | 2019-07-28 | Convenience features and house-keeping. All changes are backward-compatible. | + +## Version 3.6.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.6.1](v3.6.1.md) | 2019-03-20 | Fixes a regression (GCC 7/8 compilation) and a `<Windows.h>` build error introduced in 3.6.0. All changes are backward-compatible. | +| [v3.6.0](v3.6.0.md) | 2019-03-20 | Feature release. All changes are backward-compatible. | + +## Version 3.5.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.5.0](v3.5.0.md) | 2018-12-22 | Feature release. All changes are backward-compatible. | + +## Version 3.4.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.4.0](v3.4.0.md) | 2018-10-30 | Feature release. All changes are backward-compatible. | + +## Version 3.3.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.3.0](v3.3.0.md) | 2018-10-05 | Feature release. All changes are backward-compatible. | + +## Version 3.2.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.2.0](v3.2.0.md) | 2018-08-20 | Feature release. All changes are backward-compatible. | + +## Version 3.1.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.1.2](v3.1.2.md) | 2018-03-14 | Bug-fix release. All changes are backward-compatible. | +| [v3.1.1](v3.1.1.md) | 2018-02-13 | Bug-fix release. All changes are backward-compatible. | +| [v3.1.0](v3.1.0.md) | 2018-02-01 | Feature release. All changes are backward-compatible. | + +## Version 3.0.x + +| Release | Date | Summary | +|---------|------|---------| +| [v3.0.1](v3.0.1.md) | 2017-12-29 | Fixes small issues in the [JSON Pointer](../../features/json_pointer.md) and [JSON Patch](../../features/json_patch.md) implementations (invalid "copy" targets and non-integer array indices). All changes are backward-compatible. | +| [v3.0.0](v3.0.0.md) | 2017-12-17 | First 3.x release — a major release with breaking changes (see the [migration guide](../../integration/migration_guide.md)). | + +## Version 2.1.x + +| Release | Date | Summary | +|---------|------|---------| +| [v2.1.1](v2.1.1.md) | 2017-02-25 | Bug-fix release. All changes are backward-compatible. | +| [v2.1.0](v2.1.0.md) | 2017-01-28 | Feature release. All changes are backward-compatible. | + +## Version 2.0.x + +| Release | Date | Summary | +|---------|------|---------| +| [v2.0.10](v2.0.10.md) | 2017-01-02 | Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All changes are backward-compatible. | +| [v2.0.9](v2.0.9.md) | 2016-12-16 | Adds the [CBOR](../../features/binary_formats/cbor.md) and [MessagePack](../../features/binary_formats/messagepack.md) binary formats. All changes are backward-compatible. | +| [v2.0.8](v2.0.8.md) | 2016-12-02 | Adds the [`emplace`](../../api/basic_json/emplace.md) and [`emplace_back`](../../api/basic_json/emplace_back.md) functions and improves parsing and serialization performance. All changes are backward-compatible. | +| [v2.0.7](v2.0.7.md) | 2016-11-02 | Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding detection, surrogate pairs). All changes are backward-compatible. | +| [v2.0.6](v2.0.6.md) | 2016-10-15 | Fixes [`operator[]`](../../api/basic_json/operator%5B%5D.md) for [JSON pointers](../../features/json_pointer.md) so that it creates missing values like the other overloads. All changes are backward-compatible. | +| [v2.0.5](v2.0.5.md) | 2016-09-14 | Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. | +| [v2.0.4](v2.0.4.md) | 2016-09-11 | Fixes stream end-of-file detection in the parser. All changes are backward-compatible. | +| [v2.0.3](v2.0.3.md) | 2016-08-31 | Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the input-stream constructor in favor of the [`parse`](../../api/basic_json/parse.md) function. All changes are backward-compatible. | +| [v2.0.2](v2.0.2.md) | 2016-07-31 | Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and cleans up the code. All changes are backward-compatible. | +| [v2.0.1](v2.0.1.md) | 2016-06-28 | Fixes a performance regression in the [`dump`](../../api/basic_json/dump.md) function by adjusting the stream locale once per serialization. All changes are backward-compatible. | +| [v2.0.0](v2.0.0.md) | 2016-06-24 | Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept` and `constexpr` specifiers. | + +## Version 1.1.x + +| Release | Date | Summary | +|---------|------|---------| +| [v1.1.0](v1.1.0.md) | 2016-01-24 | Bug-fix and feature release. All changes are backward-compatible. | + +## Version 1.0.x + +| Release | Date | Summary | +|---------|------|---------| +| [v1.0.0](v1.0.0.md) | 2015-12-28 | First official release. | + +## See also + +- [Migration Guide](../../integration/migration_guide.md) — how to future-proof your code for the next + major version and replace deprecated functions.
diff --git a/docs/mkdocs/docs/home/releases/unreleased.md b/docs/mkdocs/docs/home/releases/unreleased.md new file mode 100644 index 0000000..b27da97 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/unreleased.md
@@ -0,0 +1,14 @@ +# Unreleased + +These changes are part of the `develop` branch, but not of a release yet. + +- Converting an rvalue container to JSON (`json j = std::move(vec);`, `json j = std::map<std::string, std::string>{...};`) + now **moves** the elements instead of copying them (e.g., `std::vector<std::string>` with 100,000 strings: 4.7 ms to + 2.3 ms). Two consequences: the source container is left in a valid but unspecified (moved-from) state, and if an + exception is thrown during the conversion, the source may be partially moved-from, so the strong exception guarantee + no longer holds for the source of an rvalue conversion (the JSON value itself is unaffected). Lvalues and `const` + objects are still copied. See [`basic_json`](../../api/basic_json/basic_json.md). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v1.0.0.md b/docs/mkdocs/docs/home/releases/v1.0.0.md new file mode 100644 index 0000000..dde38ca --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v1.0.0.md
@@ -0,0 +1,9 @@ +# v1.0.0 + +Released on 2015-12-28. + +First official release. [Full release notes](https://github.com/nlohmann/json/releases/tag/v1.0.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v1.1.0.md b/docs/mkdocs/docs/home/releases/v1.1.0.md new file mode 100644 index 0000000..1bdff4b --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v1.1.0.md
@@ -0,0 +1,14 @@ +# v1.1.0 + +Released on 2016-01-24. + +Bug-fix and feature release. All changes are backward-compatible. + +- Improves floating-point round-tripping, adds a `get_ref` accessor for stored values, and introduces + runtime [assertions](../../features/assertions.md). + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v1.1.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.0.md b/docs/mkdocs/docs/home/releases/v2.0.0.md new file mode 100644 index 0000000..5405935 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.0.md
@@ -0,0 +1,19 @@ +# v2.0.0 + +Released on 2016-06-24. + +Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept` +and `constexpr` specifiers. + +- Adds [JSON Pointer](../../features/json_pointer.md) support in [`at`](../../api/basic_json/at.md) and + [`operator[]`](../../api/basic_json/operator%5B%5D.md), plus [`flatten`](../../api/basic_json/flatten.md) + and [`unflatten`](../../api/basic_json/unflatten.md). +- Adds [JSON Patch](../../features/json_patch.md) via [`diff`](../../api/basic_json/diff.md) and + [`patch`](../../api/basic_json/patch.md), unsigned 64-bit integer support, and locale-independent + serialization. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.1.md b/docs/mkdocs/docs/home/releases/v2.0.1.md new file mode 100644 index 0000000..8d2820f --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.1.md
@@ -0,0 +1,11 @@ +# v2.0.1 + +Released on 2016-06-28. + +Fixes a performance regression in the [`dump`](../../api/basic_json/dump.md) function by adjusting the +stream locale once per serialization. All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.10.md b/docs/mkdocs/docs/home/releases/v2.0.10.md new file mode 100644 index 0000000..56e390f --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.10.md
@@ -0,0 +1,10 @@ +# v2.0.10 + +Released on 2017-01-02. + +Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All +changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.10). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.2.md b/docs/mkdocs/docs/home/releases/v2.0.2.md new file mode 100644 index 0000000..4824db4 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.2.md
@@ -0,0 +1,11 @@ +# v2.0.2 + +Released on 2016-07-31. + +Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and +cleans up the code. All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.2). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.3.md b/docs/mkdocs/docs/home/releases/v2.0.3.md new file mode 100644 index 0000000..66182cb --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.3.md
@@ -0,0 +1,11 @@ +# v2.0.3 + +Released on 2016-08-31. + +Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the +input-stream constructor in favor of the [`parse`](../../api/basic_json/parse.md) function. All changes +are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.3). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.4.md b/docs/mkdocs/docs/home/releases/v2.0.4.md new file mode 100644 index 0000000..b7cebb9 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.4.md
@@ -0,0 +1,10 @@ +# v2.0.4 + +Released on 2016-09-11. + +Fixes stream end-of-file detection in the parser. All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.4). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.5.md b/docs/mkdocs/docs/home/releases/v2.0.5.md new file mode 100644 index 0000000..2f383ef --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.5.md
@@ -0,0 +1,10 @@ +# v2.0.5 + +Released on 2016-09-14. + +Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.5). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.6.md b/docs/mkdocs/docs/home/releases/v2.0.6.md new file mode 100644 index 0000000..cfee027 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.6.md
@@ -0,0 +1,11 @@ +# v2.0.6 + +Released on 2016-10-15. + +Fixes [`operator[]`](../../api/basic_json/operator%5B%5D.md) for [JSON pointers](../../features/json_pointer.md) +so that it creates missing values like the other overloads. All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.6). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.7.md b/docs/mkdocs/docs/home/releases/v2.0.7.md new file mode 100644 index 0000000..3d8069a --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.7.md
@@ -0,0 +1,11 @@ +# v2.0.7 + +Released on 2016-11-02. + +Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding +detection, surrogate pairs). All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.7). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.8.md b/docs/mkdocs/docs/home/releases/v2.0.8.md new file mode 100644 index 0000000..177e335 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.8.md
@@ -0,0 +1,12 @@ +# v2.0.8 + +Released on 2016-12-02. + +Adds the [`emplace`](../../api/basic_json/emplace.md) and +[`emplace_back`](../../api/basic_json/emplace_back.md) functions and improves parsing and serialization +performance. All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.8). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.0.9.md b/docs/mkdocs/docs/home/releases/v2.0.9.md new file mode 100644 index 0000000..2587c79 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.0.9.md
@@ -0,0 +1,11 @@ +# v2.0.9 + +Released on 2016-12-16. + +Adds the [CBOR](../../features/binary_formats/cbor.md) and +[MessagePack](../../features/binary_formats/messagepack.md) binary formats. All changes are +backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.9). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.1.0.md b/docs/mkdocs/docs/home/releases/v2.1.0.md new file mode 100644 index 0000000..3e42cbd --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.1.0.md
@@ -0,0 +1,15 @@ +# v2.1.0 + +Released on 2017-01-28. + +Feature release. All changes are backward-compatible. + +- Adds conversions from and to [arbitrary user-defined types](../../features/arbitrary_types.md) via + `to_json`/`from_json`, the [`meta`](../../api/basic_json/meta.md) function, and the option to switch off + exceptions ([`JSON_NOEXCEPTION`](../../api/macros/json_noexception.md)). + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v2.1.1.md b/docs/mkdocs/docs/home/releases/v2.1.1.md new file mode 100644 index 0000000..7167dcd --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v2.1.1.md
@@ -0,0 +1,14 @@ +# v2.1.1 + +Released on 2017-02-25. + +Bug-fix release. All changes are backward-compatible. + +- Makes number parsing and serialization locale-independent with correct floating-point + round-tripping; commits and released files are GPG-signed. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.0.0.md b/docs/mkdocs/docs/home/releases/v3.0.0.md new file mode 100644 index 0000000..cea928e --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.0.0.md
@@ -0,0 +1,20 @@ +# v3.0.0 + +Released on 2017-12-17. + +First 3.x release — a major release with breaking changes (see the +[migration guide](../../integration/migration_guide.md)). + +- Introduces user-defined [exceptions](../exceptions.md) (`json::exception` and subtypes, each with an + identifier). +- Adds a non-throwing [`accept`](../../api/basic_json/accept.md) function and an `allow_exceptions` flag + for [`parse`](../../api/basic_json/parse.md), and an [`update`](../../api/basic_json/update.md) function to + merge objects. +- Adds streaming for CBOR and MessagePack and allows storing NaN/infinity. +- Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.0.1.md b/docs/mkdocs/docs/home/releases/v3.0.1.md new file mode 100644 index 0000000..95c6141 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.0.1.md
@@ -0,0 +1,12 @@ +# v3.0.1 + +Released on 2017-12-29. + +Fixes small issues in the [JSON Pointer](../../features/json_pointer.md) and +[JSON Patch](../../features/json_patch.md) implementations (invalid "copy" targets and non-integer array +indices). All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.1.0.md b/docs/mkdocs/docs/home/releases/v3.1.0.md new file mode 100644 index 0000000..31428a6 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.1.0.md
@@ -0,0 +1,16 @@ +# v3.1.0 + +Released on 2018-02-01. + +Feature release. All changes are backward-compatible. + +- Adds [UBJSON](../../features/binary_formats/ubjson.md) read/write support and + [JSON Merge Patch](../../features/merge_patch.md) via [`merge_patch`](../../api/basic_json/merge_patch.md). +- Switches to the Grisu2 algorithm for short, round-trippable floating-point output, and splits the + header into [multiple files](../../integration/index.md) with a forward-declaration header. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.1.1.md b/docs/mkdocs/docs/home/releases/v3.1.1.md new file mode 100644 index 0000000..b7c6aca --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.1.1.md
@@ -0,0 +1,14 @@ +# v3.1.1 + +Released on 2018-02-13. + +Bug-fix release. All changes are backward-compatible. + +- Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and + overflow detection for UBJSON containers. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.1.2.md b/docs/mkdocs/docs/home/releases/v3.1.2.md new file mode 100644 index 0000000..30917e0 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.1.2.md
@@ -0,0 +1,14 @@ +# v3.1.2 + +Released on 2018-03-14. + +Bug-fix release. All changes are backward-compatible. + +- Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser + and serializer. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.2). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.10.0.md b/docs/mkdocs/docs/home/releases/v3.10.0.md new file mode 100644 index 0000000..520e8ab --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.10.0.md
@@ -0,0 +1,20 @@ +# v3.10.0 + +Released on 2021-08-17. + +Feature release. All changes are backward-compatible. + +- Adds [extended diagnostic messages](../../api/macros/json_diagnostics.md) + ([`JSON_DIAGNOSTICS`](../../api/macros/json_diagnostics.md)) that prepend a JSON pointer to exception + messages to pinpoint the offending value. +- Adds a GDB pretty-printer and a [`cbor_tag_handler_t`](../../api/basic_json/cbor_tag_handler_t.md) + `store` option to keep CBOR tags as binary subtypes. +- Supports containers with non-default-constructible types and parsing from `std::byte`. +- Adds [`JSON_NO_IO`](../../api/macros/json_no_io.md) to exclude the I/O headers and the + [`JSON_HAS_CPP_*`](../../api/macros/json_has_cpp_11.md) macros to override the detected C++ standard. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.10.1.md b/docs/mkdocs/docs/home/releases/v3.10.1.md new file mode 100644 index 0000000..e6881be --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.10.1.md
@@ -0,0 +1,14 @@ +# v3.10.1 + +Released on 2021-08-24. + +Fixes a regression from 3.10.0. All changes are backward-compatible. + +- Fixes an [extended-diagnostics](../../api/macros/json_diagnostics.md) assertion triggered when used + with [`ordered_json`](../../api/ordered_json.md), and hardens the GDB pretty-printer. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.10.2.md b/docs/mkdocs/docs/home/releases/v3.10.2.md new file mode 100644 index 0000000..c442ac6 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.10.2.md
@@ -0,0 +1,11 @@ +# v3.10.2 + +Released on 2021-08-26. + +Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. +All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.2). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.10.3.md b/docs/mkdocs/docs/home/releases/v3.10.3.md new file mode 100644 index 0000000..0c84ccf --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.10.3.md
@@ -0,0 +1,16 @@ +# v3.10.3 + +Released on 2021-10-08. + +Fixes more regressions from 3.10.0. All changes are backward-compatible. + +- Fixes [extended-diagnostics](../../api/macros/json_diagnostics.md) assertions triggered by + [`update`](../../api/basic_json/update.md) and by inserting into arrays. +- Supports custom allocators when writing binary formats into a `std::vector`, and allows conversion + from types that only provide `begin()`/`end()`. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.3). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.10.4.md b/docs/mkdocs/docs/home/releases/v3.10.4.md new file mode 100644 index 0000000..dcb81e3 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.10.4.md
@@ -0,0 +1,16 @@ +# v3.10.4 + +Released on 2021-10-16. + +Fixes regressions introduced in 3.10.0. All changes are backward-compatible. + +- Fixes the `std::filesystem::path` conversion (which could trigger a stack overflow and broke + compilation on Windows). +- Fixes compilation for types with an explicit defaulted constructor and for code relying on the + return values of `std::find` and `std::remove`. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.4). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.10.5.md b/docs/mkdocs/docs/home/releases/v3.10.5.md new file mode 100644 index 0000000..e1c82ba --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.10.5.md
@@ -0,0 +1,15 @@ +# v3.10.5 + +Released on 2022-01-03. + +Bug-fix release. All changes are backward-compatible. + +- Guards the `std::filesystem` conversions behind compiler-support checks + ([`JSON_HAS_FILESYSTEM`](../../api/macros/json_has_filesystem.md)), which can be set to `0` to disable + them altogether. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.5). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.11.0.md b/docs/mkdocs/docs/home/releases/v3.11.0.md new file mode 100644 index 0000000..c25a069 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.11.0.md
@@ -0,0 +1,27 @@ +# v3.11.0 + +Released on 2022-08-01. + +One of the largest releases ever. All changes are backward-compatible. + +- Allows `std::string_view` as object keys in [`at`](../../api/basic_json/at.md), + [`operator[]`](../../api/basic_json/operator%5B%5D.md), [`value`](../../api/basic_json/value.md), + [`erase`](../../api/basic_json/erase.md), [`find`](../../api/basic_json/find.md), + [`contains`](../../api/basic_json/contains.md), and [`count`](../../api/basic_json/count.md). +- Adds the [BJData](../../features/binary_formats/bjdata.md) binary format (the fifth supported format). +- Improves C++20 support, including [`operator<=>`](../../api/basic_json/operator_spaceship.md) and + `<ranges>`-compatible iterators. +- Adds a versioned, ABI-tagged inline [namespace](../../features/namespace.md) + ([`NLOHMANN_JSON_NAMESPACE`](../../api/macros/nlohmann_json_namespace.md)) and the option to move the + UDLs out of the global namespace ([`JSON_USE_GLOBAL_UDLS`](../../api/macros/json_use_global_udls.md)). +- Adds [`patch_inplace`](../../api/basic_json/patch_inplace.md), default values for the + [conversion macros](../../features/arbitrary_types.md#simplify-your-life-with-macros), and an option to + disable enum serialization ([`JSON_DISABLE_ENUM_SERIALIZATION`](../../api/macros/json_disable_enum_serialization.md)). + +This release introduced a UDL regression that was fixed in +[3.11.1](https://github.com/nlohmann/json/releases/tag/v3.11.1). +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.11.1.md b/docs/mkdocs/docs/home/releases/v3.11.1.md new file mode 100644 index 0000000..666a895 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.11.1.md
@@ -0,0 +1,16 @@ +# v3.11.1 + +Released on 2022-08-01. + +Fixes a regression from 3.11.0. All changes are backward-compatible. + +- Restores the global [user-defined string literals](../../api/macros/json_use_global_udls.md) + [`operator""_json`](../../api/operator_literal_json.md) and + [`operator""_json_pointer`](../../api/operator_literal_json_pointer.md), which 3.11.0 had moved into a + namespace by default. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.11.2.md b/docs/mkdocs/docs/home/releases/v3.11.2.md new file mode 100644 index 0000000..a5f9e7c --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.11.2.md
@@ -0,0 +1,18 @@ +# v3.11.2 + +Released on 2022-08-12. + +Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible. + +- Fixes the [`value`](../../api/basic_json/value.md) function (broken for strings, size types, and + `nullptr` in 3.11.0) and makes `json_fwd.hpp` self-contained. +- Restores using [`json_pointer`](../../api/json_pointer/index.md) as a key in associative containers and + comparing it with strings. +- Restructures the inline [namespace](../../features/namespace.md) and allows disabling the version + component, and avoids heap allocations in the [BJData](../../features/binary_formats/bjdata.md) parser. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.2). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.11.3.md b/docs/mkdocs/docs/home/releases/v3.11.3.md new file mode 100644 index 0000000..238a774 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.11.3.md
@@ -0,0 +1,20 @@ +# v3.11.3 + +Released on 2023-11-28. + +Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible. + +- Adds a [custom base class](../../api/basic_json/json_base_class_t.md) as a node customization point. +- Adds serialization-only [conversion macros](../../features/macros.md) + (`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE` and `NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE`) + and a clearer parse error for empty input. +- Adds [Bazel](../../integration/package_managers.md#bazel) and + [Swift Package Manager](../../integration/package_managers.md#swift-package-manager) build support. +- Fixes custom allocators, a memory leak in [`adl_serializer`](../../api/adl_serializer/to_json.md)'s + `to_json`, initializer-list construction when `size_type` is not `int`, and many compiler warnings. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.3). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.12.0.md b/docs/mkdocs/docs/home/releases/v3.12.0.md new file mode 100644 index 0000000..07be554 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.12.0.md
@@ -0,0 +1,26 @@ +# v3.12.0 + +Released on 2025-04-11. + +Fixes bugs found in 3.11.3 and adds several features. No public API was removed or renamed. + +- Adds diagnostic byte positions via [`JSON_DIAGNOSTIC_POSITIONS`](../../api/macros/json_diagnostic_positions.md), + exposed through the new [`start_pos`](../../api/basic_json/start_pos.md) and + [`end_pos`](../../api/basic_json/end_pos.md) member functions. +- Makes the [conversion macros](../../features/arbitrary_types.md#simplify-your-life-with-macros) + templated (so they also work with [`ordered_json`](../../api/ordered_json.md)) and adds + [`NLOHMANN_DEFINE_DERIVED_TYPE`](../../api/macros/nlohmann_define_derived_type.md) for derived classes. +- Adds `std::optional` support (C++17) and lets [`patch`](../../api/basic_json/patch.md), + [`diff`](../../api/basic_json/diff.md), and [`flatten`](../../api/basic_json/flatten.md) work with + arbitrary string types. +- Extends the [binary formats](../../features/binary_formats/index.md): + [BJData](../../features/binary_formats/bjdata.md) draft 3 and unsigned 64-bit integers for + [BSON](../../features/binary_formats/bson.md). +- Adds multidimensional C-array conversion and UTF-8 encoded `std::filesystem::path` conversions, and + raises the minimum [CMake](../../integration/cmake.md) version to 3.5 and supports CMake 4.0. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.12.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.2.0.md b/docs/mkdocs/docs/home/releases/v3.2.0.md new file mode 100644 index 0000000..6e66902 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.2.0.md
@@ -0,0 +1,16 @@ +# v3.2.0 + +Released on 2018-08-20. + +Feature release. All changes are backward-compatible. + +- Adds a [SAX interface](../../features/parsing/sax_interface.md) and a non-recursive parser. +- Adds parsing from wide-string types (`std::wstring`, `std::u16string`, `std::u32string`), conversion to + `std::string_view` (C++17), and round-tripping of `std::map`/`std::unordered_map` with non-string + keys. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.2.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.3.0.md b/docs/mkdocs/docs/home/releases/v3.3.0.md new file mode 100644 index 0000000..e4ee07c --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.3.0.md
@@ -0,0 +1,14 @@ +# v3.3.0 + +Released on 2018-10-05. + +Feature release. All changes are backward-compatible. + +- Adds GCC 4.8 support, the [`get_to`](../../api/basic_json/get_to.md) function, and an overhauled and + documented [CMake](../../integration/cmake.md) integration. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.3.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.4.0.md b/docs/mkdocs/docs/home/releases/v3.4.0.md new file mode 100644 index 0000000..49a4cf5 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.4.0.md
@@ -0,0 +1,18 @@ +# v3.4.0 + +Released on 2018-10-30. + +Feature release. All changes are backward-compatible. + +- Adds [BSON](../../features/binary_formats/bson.md) read/write support. +- Adds configurable Unicode error handlers to [`dump`](../../api/basic_json/dump.md) (throw, replace with + U+FFFD, or ignore) and the + [`NLOHMANN_JSON_SERIALIZE_ENUM`](../../api/macros/nlohmann_json_serialize_enum.md) macro for + [enum conversion](../../features/enum_conversion.md). +- Improves parse-error messages with line/column positions and context. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.4.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.5.0.md b/docs/mkdocs/docs/home/releases/v3.5.0.md new file mode 100644 index 0000000..40a14e1 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.5.0.md
@@ -0,0 +1,15 @@ +# v3.5.0 + +Released on 2018-12-22. + +Feature release. All changes are backward-compatible. + +- Adds structured-binding support via the [`items`](../../api/basic_json/items.md) function and reading + from `FILE*` in the [`parse`](../../api/basic_json/parse.md) function. +- Fixes the `eofbit` handling on input streams and a bug in the BSON SAX parser. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.5.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.6.0.md b/docs/mkdocs/docs/home/releases/v3.6.0.md new file mode 100644 index 0000000..48aa6e9 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.6.0.md
@@ -0,0 +1,16 @@ +# v3.6.0 + +Released on 2019-03-20. + +Feature release. All changes are backward-compatible. + +- Reworks the [JSON pointer](../../features/json_pointer.md) interface (`operator/`, `push_back`, + `parent_pointer`, …). +- Adds a [`contains`](../../api/basic_json/contains.md) function to test for an object key and greatly + improves the performance of integer serialization. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.6.1.md b/docs/mkdocs/docs/home/releases/v3.6.1.md new file mode 100644 index 0000000..c1e8daf --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.6.1.md
@@ -0,0 +1,10 @@ +# v3.6.1 + +Released on 2019-03-20. + +Fixes a regression (GCC 7/8 compilation) and a `<Windows.h>` build error introduced in 3.6.0. All +changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.7.0.md b/docs/mkdocs/docs/home/releases/v3.7.0.md new file mode 100644 index 0000000..c9e7b15 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.7.0.md
@@ -0,0 +1,15 @@ +# v3.7.0 + +Released on 2019-07-28. + +Convenience features and house-keeping. All changes are backward-compatible. + +- Adds a [`contains`](../../api/basic_json/contains.md) overload that checks a JSON pointer without + throwing, a generic `to_string`, and a return value for + [`emplace_back`](../../api/basic_json/emplace_back.md). + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.7.1.md b/docs/mkdocs/docs/home/releases/v3.7.1.md new file mode 100644 index 0000000..98a85fb --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.7.1.md
@@ -0,0 +1,16 @@ +# v3.7.1 + +Released on 2019-11-06. + +Bug-fix release. All changes are backward-compatible. + +- Fixes a segmentation fault when serializing the `std::int64_t` minimum value and fixes + [`contains`](../../api/basic_json/contains.md) for JSON pointers. +- Allows [`items`](../../api/basic_json/items.md) with a custom string type and makes `json_pointer::back` + `const`. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.7.2.md b/docs/mkdocs/docs/home/releases/v3.7.2.md new file mode 100644 index 0000000..aea237b --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.7.2.md
@@ -0,0 +1,11 @@ +# v3.7.2 + +Released on 2019-11-10. + +Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing of JSON +text is now bounded only by available memory (the binary-format parsers still recurse). All changes are backward-compatible. +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.2). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.7.3.md b/docs/mkdocs/docs/home/releases/v3.7.3.md new file mode 100644 index 0000000..f0a106f --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.7.3.md
@@ -0,0 +1,10 @@ +# v3.7.3 + +Released on 2019-11-17. + +Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes +are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.3). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.8.0.md b/docs/mkdocs/docs/home/releases/v3.8.0.md new file mode 100644 index 0000000..babd55f --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.8.0.md
@@ -0,0 +1,20 @@ +# v3.8.0 + +Released on 2020-06-14. + +Feature release. All changes are backward-compatible. + +- Introduces a [binary value](../../features/binary_values.md) type that is read from and written to + [CBOR](../../features/binary_formats/cbor.md), [BSON](../../features/binary_formats/bson.md), and + [MessagePack](../../features/binary_formats/messagepack.md), and can be shared between formats. +- Generalizes the input adapters to read from any `LegacyInputIterator` container (3–10 % faster + parsing). +- Fixes [`contains`](../../api/basic_json/contains.md) for JSON pointers and makes the binary + [`from_cbor`](../../api/basic_json/from_cbor.md)/[`from_msgpack`](../../api/basic_json/from_msgpack.md)/etc. + functions respect `allow_exceptions`. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.8.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.9.0.md b/docs/mkdocs/docs/home/releases/v3.9.0.md new file mode 100644 index 0000000..c04668c --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.9.0.md
@@ -0,0 +1,20 @@ +# v3.9.0 + +Released on 2020-07-27. + +Feature release adding four long-requested features. All changes are backward-compatible. + +- Optional [comment](../../features/comments.md) parsing in [`parse`](../../api/basic_json/parse.md) via the + `ignore_comments` parameter. +- [`ordered_json`](../../api/ordered_json.md) to preserve the [insertion order](../../features/object_order.md) + of object keys. +- An option to switch off [implicit conversions](../../api/macros/json_use_implicit_conversions.md). +- The [`NLOHMANN_DEFINE_TYPE_*`](../../features/arbitrary_types.md#simplify-your-life-with-macros) + convenience macros, plus high-precision-number support for + [UBJSON](../../features/binary_formats/ubjson.md) and CBOR tag handling. + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.0). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/home/releases/v3.9.1.md b/docs/mkdocs/docs/home/releases/v3.9.1.md new file mode 100644 index 0000000..a06f819 --- /dev/null +++ b/docs/mkdocs/docs/home/releases/v3.9.1.md
@@ -0,0 +1,14 @@ +# v3.9.1 + +Released on 2020-08-06. + +Fixes two regressions from 3.9.0. All changes are backward-compatible. + +- Accepts consecutive [comments](../../features/comments.md) and completes the + [`ordered_json`](../../api/ordered_json.md) interface (e.g. `ordered_json::parse`). + +[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.1). + +## API changes + +<!-- api-changes -->
diff --git a/docs/mkdocs/docs/images/range-begin-end.svg b/docs/mkdocs/docs/images/range-begin-end.svg index 8e2b2fb..99c9f86 100644 --- a/docs/mkdocs/docs/images/range-begin-end.svg +++ b/docs/mkdocs/docs/images/range-begin-end.svg
@@ -16,6 +16,18 @@ version="1.1" inkscape:version="0.48.4 r9939" sodipodi:docname="range-begin-end.svg"> + <style type="text/css"> + @media (prefers-color-scheme: dark) { + [style*="stroke:#000000"] { stroke: #e6e6e6 !important; } + [style*="fill:#000000"] { fill: #e6e6e6 !important; } + [style*="fill:#ffffff"] { fill: #1e1e1e !important; } + [style*="fill:#0000ff"] { fill: #7aa2ff !important; } + marker path { fill: #e6e6e6 !important; stroke: #e6e6e6 !important; } + stop[style*="#c1b1b1"] { stop-color: #5a5a5a !important; } + stop[style*="#b6b6b6"] { stop-color: #4a4a4a !important; } + stop[style*="#e3e3e3"] { stop-color: #2a2a2a !important; } + } + </style> <defs id="defs4"> <marker
diff --git a/docs/mkdocs/docs/images/range-rbegin-rend.svg b/docs/mkdocs/docs/images/range-rbegin-rend.svg index dc6045f..9667efd 100644 --- a/docs/mkdocs/docs/images/range-rbegin-rend.svg +++ b/docs/mkdocs/docs/images/range-rbegin-rend.svg
@@ -16,6 +16,18 @@ version="1.1" inkscape:version="0.48.4 r9939" sodipodi:docname="range-rbegin-rend.svg"> + <style type="text/css"> + @media (prefers-color-scheme: dark) { + [style*="stroke:#000000"] { stroke: #e6e6e6 !important; } + [style*="fill:#000000"] { fill: #e6e6e6 !important; } + [style*="fill:#ffffff"] { fill: #1e1e1e !important; } + [style*="fill:#0000ff"] { fill: #7aa2ff !important; } + marker path { fill: #e6e6e6 !important; stroke: #e6e6e6 !important; } + stop[style*="#c1b1b1"] { stop-color: #5a5a5a !important; } + stop[style*="#b6b6b6"] { stop-color: #4a4a4a !important; } + stop[style*="#e3e3e3"] { stop-color: #2a2a2a !important; } + } + </style> <defs id="defs4"> <marker
diff --git a/docs/mkdocs/docs/index.md b/docs/mkdocs/docs/index.md index 091eca5..798cf05 100644 --- a/docs/mkdocs/docs/index.md +++ b/docs/mkdocs/docs/index.md
@@ -92,7 +92,7 @@ What changed in each release, with links to the relevant documentation. - [:octicons-arrow-right-24: Releases](home/releases.md) + [:octicons-arrow-right-24: Releases](home/releases/index.md) - :octicons-people-24:{ .lg .middle } __Community__ @@ -108,7 +108,7 @@ This documentation is built from the `develop` branch and may describe changes that are not part of a release yet. Their version numbers are followed by an <span class="unreleased-version">unreleased</span> badge; see - [Releases](home/releases.md) for what shipped in each version. + [Releases](home/releases/index.md) for what shipped in each version. The library is licensed under the [MIT License](home/license.md). The source code, issue tracker, and discussions are on [GitHub](https://github.com/nlohmann/json).
diff --git a/docs/mkdocs/docs/integration/index.md b/docs/mkdocs/docs/integration/index.md index f022ec6..f6f3031 100644 --- a/docs/mkdocs/docs/integration/index.md +++ b/docs/mkdocs/docs/integration/index.md
@@ -54,3 +54,12 @@ types, additionally include [`single_include/nlohmann/json_view.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_view.hpp); see [Zero-copy JSON views](../features/json_view.md). + +## See also + +- [CMake](cmake.md) - integrate the library into a CMake project +- [Package managers](package_managers.md) +- [pkg-config](pkg-config.md) +- [Compile times](compile_times.md) - reduce the compile time overhead +- [Migration guide](migration_guide.md) - upgrade from an earlier version +- [Releases](../home/releases/index.md)
diff --git a/docs/mkdocs/hooks/api_changes.py b/docs/mkdocs/hooks/api_changes.py new file mode 100644 index 0000000..94073f5 --- /dev/null +++ b/docs/mkdocs/hooks/api_changes.py
@@ -0,0 +1,163 @@ +"""Generate the "API changes" section of the release pages from the version histories of the API pages.""" + +# Every page below docs/api ends in a "Version history" section ("Added in version 3.8.0.", "... since version 3.13.0."). +# This hook collects these entries and replaces the `<!-- api-changes -->` marker of each page in home/releases with +# the pages that were added in that release and the changes made to existing pages. The page of a release is named +# after its version (v3.12.0.md); unreleased.md collects all versions newer than the latest release. The result is an +# overview of what changed in the API, not a change log. + +import logging +import os +import posixpath +import re + +log = logging.getLogger("mkdocs.hooks.api_changes") + +_DIR = "home/releases" +_PAGE_VERSION = re.compile(r"v(\d+)\.(\d+)\.(\d+)\.md") +_MARKER = "<!-- api-changes -->" +_HISTORY = re.compile(r"^## Version history\n(.*?)(?=^## |\Z)", re.DOTALL | re.MULTILINE) +_TITLE = re.compile(r"^# (.+)$", re.MULTILINE) +_ITEM = re.compile(r"^(?:[-*]|\d+\.)\s+") +_SENTENCE = re.compile(r"(?<=\.)\s+(?=[A-Z`\[])") +_VERSION = re.compile(r"\b(?:version|since|in)\s+(\d+)\.(\d+)\.(\d+)\b", re.IGNORECASE) +_FUTURE = re.compile(r"\bwill\b|\bplanned\b", re.IGNORECASE) # statements about versions that do not exist yet +_NEXT_MAJOR = (4, 0, 0) # versions from here on are announcements, not changes +_ADDED = re.compile(r"^(?:Added|Introduced)\b.*\bversion \d|^Since version \d+\.\d+\.\d+\.?$", re.IGNORECASE) +_LINK = re.compile(r"(\]\()([^)\s]+)(\))") + + +def on_page_markdown(markdown, *, page, config, files): + uri = page.file.src_uri + if posixpath.dirname(uri) != _DIR or _MARKER not in markdown: + return markdown + docs_dir = config["docs_dir"] + entries = _collect(docs_dir) + released = sorted(tuple(map(int, m.groups())) for m in + (_PAGE_VERSION.fullmatch(name) for name in os.listdir(os.path.join(docs_dir, _DIR))) if m) + match = _PAGE_VERSION.fullmatch(posixpath.basename(uri)) + if match: + versions = [tuple(map(int, match.groups()))] + else: # unreleased.md + versions = sorted((v for v in entries if not released or v > released[-1]), reverse=True) + return markdown.replace(_MARKER, _render(uri, [(v, entries[v]) for v in versions if v in entries])) + + +def _title(text, path): + match = _TITLE.search(text) + title = match.group(1) if match else os.path.splitext(os.path.basename(path))[0] + title = re.sub(r"</?small>", "", title) + title = title.replace("`", "").replace("\\", "").strip() + return title[len("nlohmann::"):] if title.startswith("nlohmann::") else title + + +def _collect(docs_dir): + """Return {version: {"added": [(title, uri)], "changed": [(title, uri, text)]}}.""" + result = {} + api = os.path.join(docs_dir, "api") + for root, _, names in sorted(os.walk(api)): + for name in sorted(names): + if not name.endswith(".md"): + continue + path = os.path.join(root, name) + uri = posixpath.relpath(path.replace(os.sep, "/"), docs_dir.replace(os.sep, "/")) + with open(path, encoding="utf-8") as source: + text = source.read() + history = _HISTORY.search(text) + if not history: + continue + title = _title(text, path) + found = _sentences(history.group(1)) + # a page is added in the earliest version named by an "Added in" sentence that opens an entry (an entry of + # a numbered list describes one overload; later unnumbered entries extend an existing page) + starts = [v for i, n, first, v, sentence in found if first and _ADDED.match(sentence) and (i == 0 or n)] + added = min(starts) if starts else None + page_added = False + for index, number, first, version, sentence in found: + if version >= _NEXT_MAJOR: + continue + bucket = result.setdefault(version, {"added": [], "changed": []}) + opens = first and _ADDED.match(sentence) and (index == 0 or number) + if opens and version == added: + if not page_added: + bucket["added"].append((title, uri)) + page_added = True + continue + if number and re.fullmatch(r"Added in version [\d.]+\.?", sentence): + sentence = f"Overload {number} added." + elif number: + sentence = f"Overload {number}: {sentence}" + if (title, uri, sentence) not in bucket["changed"]: + bucket["changed"].append((title, uri, sentence)) + return result + + +def _sentences(section): + """Yield (entry index, overload number, opens entry, version, sentence) for every sentence naming a version.""" + found = [] + for index, (number, entry) in enumerate(_entries(section)): + for position, sentence in enumerate(_SENTENCE.split(entry)): + version = _VERSION.search(sentence) + if not version or _FUTURE.search(sentence): + continue + found.append((index, number, position == 0, tuple(int(part) for part in version.groups()), sentence.strip())) + return found + + +def _entries(section): + entries = [] + for line in section.split("\n"): + item = _ITEM.match(line) + if item: + number = re.match(r"\d+", line) + entries.append([number.group(0) if number else None, _ITEM.sub("", line).strip()]) + elif line.strip() and entries and line[0].isspace(): + entries[-1][1] += " " + line.strip() # wrapped list item + elif line.strip(): + break # text after the list, such as an admonition + return [tuple(entry) for entry in entries] + + +def _relink(text, uri, page): + """Rewrite links relative to the API page `uri` so they work from the generated page.""" + def fix(match): + target = match.group(2) + if re.match(r"[a-z]+:|#|/", target): + return match.group(0) + resolved = posixpath.normpath(posixpath.join(posixpath.dirname(uri), target)) + return match.group(1) + posixpath.relpath(resolved, posixpath.dirname(page)) + match.group(3) + return _LINK.sub(fix, text) + + +def _link(title, uri, page): + return f"[`{title}`]({posixpath.relpath(uri, posixpath.dirname(page))})" + + +def _added(pages, page): + """Group the added pages by class: `basic_json`: [`get`](..), ...; pages without a class come first.""" + groups, single = {}, [] + for title, uri in pages: + directory = posixpath.dirname(uri) + if directory == "api": + single.append(_link(title, uri, page)) + elif posixpath.basename(uri) == "index.md": + groups.setdefault(directory, []).insert(0, f"[(overview)]({posixpath.relpath(uri, posixpath.dirname(page))})") + else: + groups.setdefault(directory, []).append(_link(title.split("::")[-1], uri, page)) + lines = [f"- {item}" for item in single] + for directory, items in groups.items(): + lines.append(f"- `{posixpath.basename(directory)}`: " + ", ".join(items)) + return lines + + +def _render(page, entries): + lines = [] + for version, bucket in entries: + if len(entries) > 1: + lines += [f"### Version {'.'.join(map(str, version))}", ""] + if bucket["added"]: + lines += [f"**Added ({len(bucket['added'])} pages):**", ""] + _added(bucket["added"], page) + [""] + if bucket["changed"]: + lines += ["**Changed:**", ""] + lines += [f"- {_link(t, u, page)}: {_relink(x, u, page)}" for t, u, x in bucket["changed"]] + [""] + return "\n".join(lines) if lines else "No documented API changes."
diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index 90393ff..469ae92 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml
@@ -51,7 +51,53 @@ - home/license.md - "FAQ": home/faq.md - home/exceptions.md - - home/releases.md + - Releases: + - 'Overview': home/releases/index.md + - 'Unreleased': home/releases/unreleased.md + - 'v3.12.0': home/releases/v3.12.0.md + - 'v3.11.3': home/releases/v3.11.3.md + - 'v3.11.2': home/releases/v3.11.2.md + - 'v3.11.1': home/releases/v3.11.1.md + - 'v3.11.0': home/releases/v3.11.0.md + - 'v3.10.5': home/releases/v3.10.5.md + - 'v3.10.4': home/releases/v3.10.4.md + - 'v3.10.3': home/releases/v3.10.3.md + - 'v3.10.2': home/releases/v3.10.2.md + - 'v3.10.1': home/releases/v3.10.1.md + - 'v3.10.0': home/releases/v3.10.0.md + - 'v3.9.1': home/releases/v3.9.1.md + - 'v3.9.0': home/releases/v3.9.0.md + - 'v3.8.0': home/releases/v3.8.0.md + - 'v3.7.3': home/releases/v3.7.3.md + - 'v3.7.2': home/releases/v3.7.2.md + - 'v3.7.1': home/releases/v3.7.1.md + - 'v3.7.0': home/releases/v3.7.0.md + - 'v3.6.1': home/releases/v3.6.1.md + - 'v3.6.0': home/releases/v3.6.0.md + - 'v3.5.0': home/releases/v3.5.0.md + - 'v3.4.0': home/releases/v3.4.0.md + - 'v3.3.0': home/releases/v3.3.0.md + - 'v3.2.0': home/releases/v3.2.0.md + - 'v3.1.2': home/releases/v3.1.2.md + - 'v3.1.1': home/releases/v3.1.1.md + - 'v3.1.0': home/releases/v3.1.0.md + - 'v3.0.1': home/releases/v3.0.1.md + - 'v3.0.0': home/releases/v3.0.0.md + - 'v2.1.1': home/releases/v2.1.1.md + - 'v2.1.0': home/releases/v2.1.0.md + - 'v2.0.10': home/releases/v2.0.10.md + - 'v2.0.9': home/releases/v2.0.9.md + - 'v2.0.8': home/releases/v2.0.8.md + - 'v2.0.7': home/releases/v2.0.7.md + - 'v2.0.6': home/releases/v2.0.6.md + - 'v2.0.5': home/releases/v2.0.5.md + - 'v2.0.4': home/releases/v2.0.4.md + - 'v2.0.3': home/releases/v2.0.3.md + - 'v2.0.2': home/releases/v2.0.2.md + - 'v2.0.1': home/releases/v2.0.1.md + - 'v2.0.0': home/releases/v2.0.0.md + - 'v1.1.0': home/releases/v1.1.0.md + - 'v1.0.0': home/releases/v1.0.0.md - home/design_goals.md - home/architecture.md - home/customers.md @@ -484,6 +530,7 @@ unrecognized_links: warn hooks: + - hooks/api_changes.py - hooks/copy_markdown_source.py - hooks/unreleased_versions.py
