From 48188b45694dacb7083b18f17efd2e02013890be Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 10 Oct 2026 13:34:47 +0200 Subject: [PATCH] Fix inaccuracies in the documentation - version history: json_base_class_t (3.11.3), JSON_HAS_CPP_11 (3.10.0), JSON_HAS_RANGES exclusions, define-type macros, ABI tags - releases: 3.12.0 raised the minimum CMake version - from_*: the (ptr, len) overloads are deleted, not removed, in 4.0.0 - contains/count/find: document the deleted integral overloads - add JSON_HAS_RANGE_VIEW_CONVERSION and list the JSON_HAS_* macros in the macro overview - mention BON8 and error_handler where binary formats are listed - broken links, outdated URLs, warning count, Hunter v0.26.12 - copy_markdown_source hook: expand snippets in the Markdown copies Signed-off-by: Niels Lohmann --- docs/mkdocs/docs/api/basic_json/contains.md | 9 ++++ docs/mkdocs/docs/api/basic_json/count.md | 7 +++ .../docs/api/basic_json/error_handler_t.md | 4 +- docs/mkdocs/docs/api/basic_json/find.md | 9 ++++ .../mkdocs/docs/api/basic_json/from_bjdata.md | 3 +- docs/mkdocs/docs/api/basic_json/from_bon8.md | 3 +- docs/mkdocs/docs/api/basic_json/from_bson.md | 3 +- docs/mkdocs/docs/api/basic_json/from_cbor.md | 3 +- .../docs/api/basic_json/from_msgpack.md | 3 +- .../mkdocs/docs/api/basic_json/from_ubjson.md | 3 +- .../docs/api/basic_json/json_base_class_t.md | 2 +- docs/mkdocs/docs/api/macros/index.md | 1 + .../mkdocs/docs/api/macros/json_has_cpp_11.md | 2 +- .../macros/json_has_range_view_conversion.md | 43 +++++++++++++++++++ .../mkdocs/docs/api/macros/json_has_ranges.md | 5 ++- .../api/macros/json_strict_binary_utf8.md | 5 ++- .../macros/nlohmann_define_derived_type.md | 2 + .../macros/nlohmann_define_type_intrusive.md | 3 ++ .../nlohmann_define_type_non_intrusive.md | 3 ++ .../api/macros/nlohmann_json_namespace.md | 4 +- .../macros/nlohmann_json_namespace_begin.md | 2 +- docs/mkdocs/docs/community/assurance_case.md | 2 +- .../docs/community/quality_assurance.md | 4 +- docs/mkdocs/docs/features/conversions.md | 3 +- docs/mkdocs/docs/features/macros.md | 39 +++++++++++++++++ docs/mkdocs/docs/features/namespace.md | 6 +++ docs/mkdocs/docs/home/architecture.md | 2 +- docs/mkdocs/docs/home/design_goals.md | 4 +- docs/mkdocs/docs/home/exceptions.md | 4 +- docs/mkdocs/docs/home/releases.md | 2 +- .../docs/integration/hunter/CMakeLists.txt | 4 +- docs/mkdocs/hooks/copy_markdown_source.py | 31 +++++++++++-- docs/mkdocs/includes/glossary.md | 2 +- docs/mkdocs/mkdocs.yml | 1 + 34 files changed, 193 insertions(+), 30 deletions(-) create mode 100644 docs/mkdocs/docs/api/macros/json_has_range_view_conversion.md diff --git a/docs/mkdocs/docs/api/basic_json/contains.md b/docs/mkdocs/docs/api/basic_json/contains.md index 63ec87a1d..c982ab9b9 100644 --- a/docs/mkdocs/docs/api/basic_json/contains.md +++ b/docs/mkdocs/docs/api/basic_json/contains.md @@ -10,6 +10,10 @@ bool contains(KeyType&& key) const; // (3) bool contains(const json_pointer& ptr) const; + +// (4) +template +bool contains(T) const = delete; ``` 1. Check whether an element exists in a JSON object with a key equivalent to `key`. If the element is not found or the @@ -17,6 +21,9 @@ bool contains(const json_pointer& ptr) const; 2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and `#!cpp typename object_comparator_t::is_transparent` denotes a type. 3. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value. +4. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with + an integer `key` (for example, `#!cpp j.contains(0)`) fails to compile. Otherwise, the integer literal `0` would convert to + a null `#!cpp const char*` and, from there, to the key type, causing undefined behavior at runtime. ## Template parameters @@ -39,6 +46,7 @@ bool contains(const json_pointer& ptr) const; is not an object, `#!cpp false` is returned. 2. See 1. 3. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise. +4. Deleted; a call with an integral argument does not compile. ## Exception safety @@ -49,6 +57,7 @@ Strong exception safety: if an exception occurs, the original value stays intact 1. The function does not throw exceptions. 2. The function does not throw exceptions. 3. The function does not throw exceptions. +4. Deleted; a call with an integral argument does not compile. ## Complexity diff --git a/docs/mkdocs/docs/api/basic_json/count.md b/docs/mkdocs/docs/api/basic_json/count.md index 14b707525..707e1d439 100644 --- a/docs/mkdocs/docs/api/basic_json/count.md +++ b/docs/mkdocs/docs/api/basic_json/count.md @@ -7,12 +7,19 @@ size_type count(const typename object_t::key_type& key) const; // (2) template size_type count(KeyType&& key) const; + +// (3) +template +size_type count(T) const = delete; ``` 1. Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will always be `0` (`key` was not found) or `1` (`key` was found). 2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and `#!cpp typename object_comparator_t::is_transparent` denotes a type. +3. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with + an integer `key` (for example, `#!cpp j.count(0)`) fails to compile. Otherwise, the integer literal `0` would convert to + a null `#!cpp const char*` and, from there, to the key type, causing undefined behavior at runtime. ## Template parameters diff --git a/docs/mkdocs/docs/api/basic_json/error_handler_t.md b/docs/mkdocs/docs/api/basic_json/error_handler_t.md index 17327fe26..a80f74a55 100644 --- a/docs/mkdocs/docs/api/basic_json/error_handler_t.md +++ b/docs/mkdocs/docs/api/basic_json/error_handler_t.md @@ -37,8 +37,8 @@ ignore : ignore invalid UTF-8 sequences; all valid bytes are copied to the output unchanged, and invalid bytes are dropped keep -: keep invalid UTF-8 sequences unchanged; only meaningful for the binary formats mentioned above, since [`dump`] - (dump.md) itself must produce text, and `keep` there writes the ill-formed bytes to the output as is, so the +: keep invalid UTF-8 sequences unchanged; only meaningful for the binary formats mentioned above, since + [`dump`](dump.md) itself must produce text, and `keep` there writes the ill-formed bytes to the output as is, so the result is then not valid UTF-8 (but still equals the input bytes exactly, including around any well-formed characters, which are still escaped as usual) diff --git a/docs/mkdocs/docs/api/basic_json/find.md b/docs/mkdocs/docs/api/basic_json/find.md index 59c2eab68..dc9a410d7 100644 --- a/docs/mkdocs/docs/api/basic_json/find.md +++ b/docs/mkdocs/docs/api/basic_json/find.md @@ -10,12 +10,21 @@ template iterator find(KeyType&& key); template const_iterator find(KeyType&& key) const; + +// (3) +template +iterator find(T) = delete; +template +const_iterator find(T) const = delete; ``` 1. Finds an element in a JSON object with a key equivalent to `key`. If the element is not found or the JSON value is not an object, `end()` is returned. 2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and `#!cpp typename object_comparator_t::is_transparent` denotes a type. +3. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with + an integer `key` (for example, `#!cpp j.find(0)`) fails to compile. Otherwise, the integer literal `0` would convert to + a null `#!cpp const char*` and, from there, to the key type, causing undefined behavior at runtime. ## Template parameters diff --git a/docs/mkdocs/docs/api/basic_json/from_bjdata.md b/docs/mkdocs/docs/api/basic_json/from_bjdata.md index f19f9e4a9..370124c8a 100644 --- a/docs/mkdocs/docs/api/basic_json/from_bjdata.md +++ b/docs/mkdocs/docs/api/basic_json/from_bjdata.md @@ -124,7 +124,8 @@ Linear in the size of the input. !!! warning "Deprecation" - Overload (2) replaces calls to `from_bjdata` with a pointer and a length as first two parameters, which has been - deprecated in version 3.13.0. This overload will be removed in version 4.0.0. Please replace all calls like + deprecated in version 3.13.0. In version 4.0.0, this overload + will be deleted (`= delete`) rather than removed. Please replace all calls like `#!cpp from_bjdata(ptr, len, ...);` with `#!cpp from_bjdata(ptr, ptr+len, ...);`. You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated diff --git a/docs/mkdocs/docs/api/basic_json/from_bon8.md b/docs/mkdocs/docs/api/basic_json/from_bon8.md index cac6b31eb..e566b8688 100644 --- a/docs/mkdocs/docs/api/basic_json/from_bon8.md +++ b/docs/mkdocs/docs/api/basic_json/from_bon8.md @@ -110,7 +110,8 @@ Linear in the size of the input. !!! warning "Deprecation" - Overload (2) replaces calls to `from_bon8` with a pointer and a length as first two parameters, which has been - deprecated in version 3.13.0. This overload will be removed in version 4.0.0. Please replace all calls like + deprecated in version 3.13.0. In version 4.0.0, this overload + will be deleted (`= delete`) rather than removed. Please replace all calls like `#!cpp from_bon8(ptr, len, ...);` with `#!cpp from_bon8(ptr, ptr+len, ...);`. You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated diff --git a/docs/mkdocs/docs/api/basic_json/from_bson.md b/docs/mkdocs/docs/api/basic_json/from_bson.md index b037e8e07..6e0beafce 100644 --- a/docs/mkdocs/docs/api/basic_json/from_bson.md +++ b/docs/mkdocs/docs/api/basic_json/from_bson.md @@ -126,7 +126,8 @@ Linear in the size of the input. !!! warning "Deprecation" - Overload (2) replaces calls to `from_bson` with a pointer and a length as first two parameters, which has been - deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + deprecated in version 3.8.0. In version 4.0.0, this overload + will be deleted (`= delete`) rather than removed. Please replace all calls like `#!cpp from_bson(ptr, len, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`. - Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like diff --git a/docs/mkdocs/docs/api/basic_json/from_cbor.md b/docs/mkdocs/docs/api/basic_json/from_cbor.md index 7d7df08a5..4fcd7fe98 100644 --- a/docs/mkdocs/docs/api/basic_json/from_cbor.md +++ b/docs/mkdocs/docs/api/basic_json/from_cbor.md @@ -135,7 +135,8 @@ Linear in the size of the input. !!! warning "Deprecation" - Overload (2) replaces calls to `from_cbor` with a pointer and a length as first two parameters, which has been - deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + deprecated in version 3.8.0. In version 4.0.0, this overload + will be deleted (`= delete`) rather than removed. Please replace all calls like `#!cpp from_cbor(ptr, len, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`. - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like diff --git a/docs/mkdocs/docs/api/basic_json/from_msgpack.md b/docs/mkdocs/docs/api/basic_json/from_msgpack.md index 2e7fa5062..51e23de7b 100644 --- a/docs/mkdocs/docs/api/basic_json/from_msgpack.md +++ b/docs/mkdocs/docs/api/basic_json/from_msgpack.md @@ -127,7 +127,8 @@ Linear in the size of the input. !!! warning "Deprecation" - Overload (2) replaces calls to `from_msgpack` with a pointer and a length as first two parameters, which has been - deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + deprecated in version 3.8.0. In version 4.0.0, this overload + will be deleted (`= delete`) rather than removed. Please replace all calls like `#!cpp from_msgpack(ptr, len, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`. - Overload (2) replaces calls to `from_msgpack` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like diff --git a/docs/mkdocs/docs/api/basic_json/from_ubjson.md b/docs/mkdocs/docs/api/basic_json/from_ubjson.md index ac9404d4c..3881f9ea4 100644 --- a/docs/mkdocs/docs/api/basic_json/from_ubjson.md +++ b/docs/mkdocs/docs/api/basic_json/from_ubjson.md @@ -125,7 +125,8 @@ Linear in the size of the input. !!! warning "Deprecation" - Overload (2) replaces calls to `from_ubjson` with a pointer and a length as first two parameters, which has been - deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + deprecated in version 3.8.0. In version 4.0.0, this overload + will be deleted (`= delete`) rather than removed. Please replace all calls like `#!cpp from_ubjson(ptr, len, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`. - Overload (2) replaces calls to `from_ubjson` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like diff --git a/docs/mkdocs/docs/api/basic_json/json_base_class_t.md b/docs/mkdocs/docs/api/basic_json/json_base_class_t.md index 6f0026558..2beed5a22 100644 --- a/docs/mkdocs/docs/api/basic_json/json_base_class_t.md +++ b/docs/mkdocs/docs/api/basic_json/json_base_class_t.md @@ -62,5 +62,5 @@ same name. Hidden members remain accessible via [`as_base_class`](as_base_class. ## Version history -- Added in version 3.12.0. +- Added in version 3.11.3. - Made a public member type in version 3.13.0; it was private before, so it could not be named outside the class. diff --git a/docs/mkdocs/docs/api/macros/index.md b/docs/mkdocs/docs/api/macros/index.md index eb2807b69..be9f6332c 100644 --- a/docs/mkdocs/docs/api/macros/index.md +++ b/docs/mkdocs/docs/api/macros/index.md @@ -27,6 +27,7 @@ header. See also the [macro overview page](../../features/macros.md). - [**JSON_HAS_CPP_11**
**JSON_HAS_CPP_14**
**JSON_HAS_CPP_17**
**JSON_HAS_CPP_20**](json_has_cpp_11.md) - set supported C++ standard - [**JSON_HAS_FILESYSTEM**
**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support +- [**JSON_HAS_RANGE_VIEW_CONVERSION**](json_has_range_view_conversion.md) - control construction from `std::ranges` views - [**JSON_HAS_RANGES**](json_has_ranges.md) - control `std::ranges` support - [**JSON_HAS_STATIC_RTTI**](json_has_static_rtti.md) - control RTTI (run time type information) support - [**JSON_HAS_STD_FORMAT**](json_has_std_format.md) - control `std::format`/`std::formatter` support diff --git a/docs/mkdocs/docs/api/macros/json_has_cpp_11.md b/docs/mkdocs/docs/api/macros/json_has_cpp_11.md index 6ab33bfe0..f32fe0277 100644 --- a/docs/mkdocs/docs/api/macros/json_has_cpp_11.md +++ b/docs/mkdocs/docs/api/macros/json_has_cpp_11.md @@ -49,6 +49,6 @@ The default value is detected based on preprocessor macros such as `#!cpp __cplu ## Version history -- Added in version 3.10.5. +- Added in version 3.10.0. - Added `JSON_HAS_CPP_23` in version 3.12.0. - Added `JSON_HAS_CPP_26` in version 3.13.0. diff --git a/docs/mkdocs/docs/api/macros/json_has_range_view_conversion.md b/docs/mkdocs/docs/api/macros/json_has_range_view_conversion.md new file mode 100644 index 000000000..6392170c9 --- /dev/null +++ b/docs/mkdocs/docs/api/macros/json_has_range_view_conversion.md @@ -0,0 +1,43 @@ +# JSON_HAS_RANGE_VIEW_CONVERSION + +```cpp +#define JSON_HAS_RANGE_VIEW_CONVERSION /* value */ +``` + +This macro indicates whether a JSON array can be constructed directly from a C++20 range view (`std::ranges::view`), +such as the result of `std::views::filter` or `std::views::transform`. Possible values are `1` when supported or `0` +when unsupported. + +## Default definition + +The default value is `1` if [`JSON_HAS_RANGES`](json_has_ranges.md) is `1` and the compiler is not MinGW (that is, +`#!cpp __MINGW32__` is not defined), and `0` otherwise. + +When the macro is not defined, the library will define it to its default value. + +!!! info "Known compiler/stdlib exclusions" + + - **MinGW** -- disabled, because its `std::ranges` support is incomplete ([issue #4916](https://github.com/nlohmann/json/issues/4916)). + - All toolchains for which [`JSON_HAS_RANGES`](json_has_ranges.md#default-definition) is disabled. + +## Examples + +??? example + + The code below forces the library to disable the conversion from range views: + + ```cpp + #define JSON_HAS_RANGE_VIEW_CONVERSION 0 + #include + + ... + ``` + +## See also + +- [JSON_HAS_RANGES](json_has_ranges.md) - control `std::ranges` support +- [Constructing from a C++20 range view](../../features/conversions.md#putting-values-in) - usage of the feature + +## Version history + +- Added in version 3.13.0. diff --git a/docs/mkdocs/docs/api/macros/json_has_ranges.md b/docs/mkdocs/docs/api/macros/json_has_ranges.md index 0bb3c9b58..b22e816ad 100644 --- a/docs/mkdocs/docs/api/macros/json_has_ranges.md +++ b/docs/mkdocs/docs/api/macros/json_has_ranges.md @@ -20,7 +20,7 @@ When the macro is not defined, the library will define it to its default value. - **GCC 11.1.0** — disabled (the shipped `` header has a syntax error; [issue #4440](https://github.com/nlohmann/json/issues/4440)) - **libstdc++ < 11** — disabled (incomplete C++20 ranges support; [issue #4440](https://github.com/nlohmann/json/issues/4440)) - - **Clang < 16 with libstdc++** — disabled (incomplete ranges support; [issue #4440](https://github.com/nlohmann/json/issues/4440)) + - **Clang < 16 with libstdc++** — disabled (incomplete ranges support; [issue #5161](https://github.com/nlohmann/json/issues/5161)) - **libc++ < 160000** — disabled (incomplete C++20 ranges support; [issue #4440](https://github.com/nlohmann/json/issues/4440)) - **nvcc (CUDA) 12.0.x and 12.1.x** — disabled (the `enable_borrowed_range` variable-template syntax triggers a parse error under these two toolkit versions; fixed in CUDA 12.2; [issue #3907](https://github.com/nlohmann/json/issues/3907)) @@ -44,9 +44,12 @@ When the macro is not defined, the library will define it to its default value. - [JSON_HAS_CPP_11 / JSON_HAS_CPP_14 / JSON_HAS_CPP_17 / JSON_HAS_CPP_20 / JSON_HAS_CPP_23 / JSON_HAS_CPP_26](json_has_cpp_11.md) - set supported C++ standard +- [JSON_HAS_RANGE_VIEW_CONVERSION](json_has_range_view_conversion.md) - control construction from `std::ranges` views - [JSON_HAS_STD_FORMAT](json_has_std_format.md) - a similar feature-detection macro, for `std::format`/`std::formatter` support ## Version history - Added in version 3.11.0. +- Added the exclusions for libstdc++ < 11, Clang < 16 with libstdc++, libc++ < 16, and nvcc (CUDA) 12.0.x and 12.1.x in + version 3.13.0. Before, only GCC 11.1.0 was excluded. diff --git a/docs/mkdocs/docs/api/macros/json_strict_binary_utf8.md b/docs/mkdocs/docs/api/macros/json_strict_binary_utf8.md index 4c573d56e..2369f5f4d 100644 --- a/docs/mkdocs/docs/api/macros/json_strict_binary_utf8.md +++ b/docs/mkdocs/docs/api/macros/json_strict_binary_utf8.md @@ -20,7 +20,10 @@ The macro does not affect: - The binary readers ([`from_cbor`](../basic_json/from_cbor.md), [`from_msgpack`](../basic_json/from_msgpack.md), [`from_ubjson`](../basic_json/from_ubjson.md), [`from_bjdata`](../basic_json/from_bjdata.md), [`from_bson`](../basic_json/from_bson.md)): none of these formats requires a decoder to reject ill-formed UTF-8, so - they always return the bytes unchanged. + by default they return the bytes unchanged (`error_handler_t::keep`), independent of this macro. Pass an + `error_handler` argument explicitly to validate or sanitize the strings they read. +- [`from_bon8`](../basic_json/from_bon8.md): BON8 always validates, because the UTF-8 lead bytes mark where a string + ends. ## Default definition diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md b/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md index f6a01af5b..c539e77a0 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md @@ -190,3 +190,5 @@ void to_json(BasicJsonType& j, const B& b) { 4. Added in version 3.12.0. 5. Added in version 3.12.0. 6. Added in version 3.12.0. + +All six macros were changed to allow an empty member list in version 3.13.0. diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md b/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md index 3db7722d8..dab5c7070 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md @@ -186,3 +186,6 @@ See the examples below for the concrete generated code. 1. Added in version 3.9.0. 2. Added in version 3.11.0. 3. Added in version 3.11.3. + +All three macros were changed to work with any `basic_json` specialization (not only `nlohmann::json`) in version 3.12.0, +and to allow an empty member list in version 3.13.0. diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md b/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md index 744a513b0..07d0166d0 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md @@ -185,3 +185,6 @@ See the examples below for the concrete generated code. 1. Added in version 3.9.0. 2. Added in version 3.11.0. 3. Added in version 3.11.3. + +All three macros were changed to work with any `basic_json` specialization (not only `nlohmann::json`) in version 3.12.0, +and to allow an empty member list in version 3.13.0. diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md index 5c54dba52..669fabda2 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md @@ -38,4 +38,6 @@ the library. ## Version history -- Added in version 3.11.0. Changed inline namespace name in version 3.11.2. +- Added in version 3.11.0. Changed inline namespace name in version 3.11.2. Added the ABI tag `_dp` in + version 3.12.0, and the ABI tags `_bics`, `_psp`, `_snul`, `_sbu8`, and `_ekmo` in version 3.13.0; see + [`nlohmann` Namespace](../../features/namespace.md#structure). diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md index 118fba63a..00911fb89 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md @@ -14,7 +14,7 @@ These macros can be used to open and close the `nlohmann` namespace. See ## Default definition The default definitions open and close the `nlohmann` namespace. The precise definition of -[`NLOHMANN_JSON_NAMESPACE_BEGIN`] varies as described [here](../../features/namespace.md#structure). +`NLOHMANN_JSON_NAMESPACE_BEGIN` varies as described [here](../../features/namespace.md#structure). 1. Default definition of `NLOHMANN_JSON_NAMESPACE_BEGIN`: diff --git a/docs/mkdocs/docs/community/assurance_case.md b/docs/mkdocs/docs/community/assurance_case.md index 9d9712a03..46ebd5ebe 100644 --- a/docs/mkdocs/docs/community/assurance_case.md +++ b/docs/mkdocs/docs/community/assurance_case.md @@ -10,7 +10,7 @@ The library parses, stores, and serializes JSON values in memory. It does not op files (it only reads from streams or `std::FILE*` handles that the caller has already opened), does not read environment variables, and does not implement cryptography or handle credentials. -The primary threat is therefore **untrusted input**: JSON text or binary data (BJData, BSON, CBOR, MessagePack, UBJSON) +The primary threat is therefore **untrusted input**: JSON text or binary data (BJData, BON8, BSON, CBOR, MessagePack, UBJSON) that an attacker controls, passed to [`parse`](../api/basic_json/parse.md), [`accept`](../api/basic_json/accept.md), [`sax_parse`](../api/basic_json/sax_parse.md), or one of the `from_*` functions such as [`from_cbor`](../api/basic_json/from_cbor.md). Such input may try to diff --git a/docs/mkdocs/docs/community/quality_assurance.md b/docs/mkdocs/docs/community/quality_assurance.md index bd8f55790..afef80ff8 100644 --- a/docs/mkdocs/docs/community/quality_assurance.md +++ b/docs/mkdocs/docs/community/quality_assurance.md @@ -12,7 +12,7 @@ violations will result in a failed build. Note: C++20 modules support may hit compiler-specific issues not covered by the general compiler matrix below. See [Modules](../features/modules.md#known-issues) for known issues and workarounds. -Note: Some modern features (like C++20 ranges or filesystem support) may be disabled on specific broken or incomplete toolchains even when standard feature-test macros indicate support. See [`JSON_HAS_RANGES`](../api/macros/json_has_ranges.md) and [`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md) for details on known exclusions. +Note: Some modern features (like C++20 ranges or filesystem support) may be disabled on specific broken or incomplete toolchains even when standard feature-test macros indicate support. See [`JSON_HAS_RANGES`](../api/macros/json_has_ranges.md), [`JSON_HAS_RANGE_VIEW_CONVERSION`](../api/macros/json_has_range_view_conversion.md), and [`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md) for details on known exclusions. - [x] The library is compiled with 50+ different C++ compilers with different operating systems and platforms, including the oldest versions known to compile the library. @@ -107,7 +107,7 @@ Note: Some modern features (like C++20 ranges or filesystem support) may be disa - [x] The library is compiled with all C++ language revisions (C++11, C++14, C++17, C++20, C++23, and C++26) to detect and fix language deprecations early. - [x] The library is checked for compiler warnings: - - On Clang, `-Weverything` is used with 8 exceptions. + - On Clang, `-Weverything` is used with 7 exceptions. ??? abstract "Clang warnings" diff --git a/docs/mkdocs/docs/features/conversions.md b/docs/mkdocs/docs/features/conversions.md index 94a660ec8..5ba42b7cf 100644 --- a/docs/mkdocs/docs/features/conversions.md +++ b/docs/mkdocs/docs/features/conversions.md @@ -217,7 +217,8 @@ json j = numbers; // [1,2,3] ``` This requires [`JSON_HAS_RANGES`](../api/macros/json_has_ranges.md) to be enabled and is unavailable on MinGW due - to incomplete C++20 ranges support there. + to incomplete C++20 ranges support there; see + [`JSON_HAS_RANGE_VIEW_CONVERSION`](../api/macros/json_has_range_view_conversion.md). ## Your own types diff --git a/docs/mkdocs/docs/features/macros.md b/docs/mkdocs/docs/features/macros.md index ef41ce0d5..5df3671e2 100644 --- a/docs/mkdocs/docs/features/macros.md +++ b/docs/mkdocs/docs/features/macros.md @@ -82,6 +82,45 @@ To override the built-in check, define `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERI See [full documentation of `JSON_HAS_FILESYSTEM` and `JSON_HAS_EXPERIMENTAL_FILESYSTEM`](../api/macros/json_has_filesystem.md). +## `JSON_HAS_RANGES` + +The library uses `std::ranges` (and concepts) where available, for example, to parse from C++20 ranges and to +construct JSON arrays from range views. The library detects whether the standard library supports ranges and +disables the support on toolchains with an incomplete implementation. To override the built-in check, define +`JSON_HAS_RANGES` to `1` or `0`. + +See [full documentation of `JSON_HAS_RANGES`](../api/macros/json_has_ranges.md). + +## `JSON_HAS_RANGE_VIEW_CONVERSION` + +When `JSON_HAS_RANGES` is enabled (and the compiler is not MinGW), a JSON array can be constructed directly from a C++20 +range view such as `std::views::filter(...)`. To override the built-in check, define `JSON_HAS_RANGE_VIEW_CONVERSION` to +`1` or `0`. + +See [full documentation of `JSON_HAS_RANGE_VIEW_CONVERSION`](../api/macros/json_has_range_view_conversion.md). + +## `JSON_HAS_STATIC_RTTI` + +The library detects whether the compiler supports run time type information (RTTI), which it needs, for instance, to +exclude `std::any` from the candidate types of the implicit conversion on C++17. To override the built-in check, define +`JSON_HAS_STATIC_RTTI` to `1` or `0`. + +See [full documentation of `JSON_HAS_STATIC_RTTI`](../api/macros/json_has_static_rtti.md). + +## `JSON_HAS_STD_FORMAT` + +When compiling with C++20 and a standard library that provides ``, the library provides a `std::formatter` +specialization for JSON values. To override the built-in check, define `JSON_HAS_STD_FORMAT` to `1` or `0`. + +See [full documentation of `JSON_HAS_STD_FORMAT`](../api/macros/json_has_std_format.md). + +## `JSON_HAS_THREE_WAY_COMPARISON` + +When the compiler and standard library support 3-way comparison (the spaceship operator `<=>`), the library provides it +for JSON values. To override the built-in check, define `JSON_HAS_THREE_WAY_COMPARISON` to `1` or `0`. + +See [full documentation of `JSON_HAS_THREE_WAY_COMPARISON`](../api/macros/json_has_three_way_comparison.md). + ## `JSON_NOEXCEPTION` Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. diff --git a/docs/mkdocs/docs/features/namespace.md b/docs/mkdocs/docs/features/namespace.md index 26e89d09c..407d8a748 100644 --- a/docs/mkdocs/docs/features/namespace.md +++ b/docs/mkdocs/docs/features/namespace.md @@ -101,3 +101,9 @@ follows: - Introduced inline namespace (`json_v3_11_0[_abi-tag]*`) in version 3.11.0. - Changed structure of inline namespace in version 3.11.2. +- Added ABI tag `_dp` ([`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md)) in version 3.12.0. +- Added ABI tags `_bics` ([`JSON_BRACE_INIT_COPY_SEMANTICS`](../api/macros/json_brace_init_copy_semantics.md)), `_psp` + ([`JSON_PRECISE_STREAM_POSITION`](../api/macros/json_precise_stream_position.md)), `_snul` + ([`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md)), `_sbu8` + ([`JSON_STRICT_BINARY_UTF8`](../api/macros/json_strict_binary_utf8.md)), and `_ekmo` + ([`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](../api/macros/json_use_objects_for_enum_keyed_maps.md)) in version 3.13.0. diff --git a/docs/mkdocs/docs/home/architecture.md b/docs/mkdocs/docs/home/architecture.md index 6c0892f11..ea47bab6e 100644 --- a/docs/mkdocs/docs/home/architecture.md +++ b/docs/mkdocs/docs/home/architecture.md @@ -34,7 +34,7 @@ flowchart LR - **JSON text** is read by an [input adapter](#input-adapters), tokenized by the lexer, and turned into SAX events by the parser. -- **Binary formats** (BJData, BSON, CBOR, MessagePack, UBJSON) are read by an input adapter and turned into the same SAX +- **Binary formats** (BJData, BON8, BSON, CBOR, MessagePack, UBJSON) are read by an input adapter and turned into the same SAX events by the `binary_reader`. - A [SAX consumer](#sax-interface) receives the events. The one used by [`parse`](../api/basic_json/parse.md) builds a `basic_json` value tree. diff --git a/docs/mkdocs/docs/home/design_goals.md b/docs/mkdocs/docs/home/design_goals.md index 549ba9a1a..987124378 100644 --- a/docs/mkdocs/docs/home/design_goals.md +++ b/docs/mkdocs/docs/home/design_goals.md @@ -6,7 +6,7 @@ There are myriads of [JSON](https://json.org) libraries out there, and each may - **Trivial integration**. Our whole code consists of a single header file [`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp). That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings. -- **Serious testing**. Our class is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/tests/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](http://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [OpenSSF Best Practices](https://www.bestpractices.dev/projects/289). +- **Serious testing**. Our class is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/tests/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [OpenSSF Best Practices](https://www.bestpractices.dev/projects/289). Other aspects were not so important to us: @@ -14,4 +14,4 @@ Other aspects were not so important to us: - **Speed**. There are certainly [faster JSON libraries](https://github.com/miloyip/nativejson-benchmark#parsing-time) out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a `std::vector` or `std::map`, you are already set. -See the [contribution guidelines](https://github.com/nlohmann/json/blob/master/.github/CONTRIBUTING.md#please-dont) for more information. +See the [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#please-dont) for more information. diff --git a/docs/mkdocs/docs/home/exceptions.md b/docs/mkdocs/docs/home/exceptions.md index d6fdce37a..cd5d76543 100644 --- a/docs/mkdocs/docs/home/exceptions.md +++ b/docs/mkdocs/docs/home/exceptions.md @@ -104,7 +104,7 @@ See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for ## Parse errors The library throws this exception when a parse error occurs. Parse errors -can occur during the deserialization of JSON text, CBOR, MessagePack, as well +can occur during the deserialization of JSON text or of one of the binary formats (BJData, BON8, BSON, CBOR, MessagePack, UBJSON), as well as when using JSON Patch. Exceptions have ids 1xx. @@ -190,7 +190,7 @@ This error indicates a syntax error while deserializing a JSON text. The error m !!! tip - Make sure the input is correctly read. Try to write the input to standard output to check if, for instance, the input file was successfully opened. - - Paste the input to a JSON validator like or a tool like [jq](https://stedolan.github.io/jq/). + - Paste the input to a JSON validator like or a tool like [jq](https://jqlang.github.io/jq/). ### json.exception.parse_error.102 diff --git a/docs/mkdocs/docs/home/releases.md b/docs/mkdocs/docs/home/releases.md index f91f82dda..fabf95e8a 100644 --- a/docs/mkdocs/docs/home/releases.md +++ b/docs/mkdocs/docs/home/releases.md @@ -26,7 +26,7 @@ Fixes bugs found in 3.11.3 and adds several features. All changes are backward-c [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 - lowers the minimum [CMake](../integration/cmake.md) version to allow CMake 4.0. + 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). diff --git a/docs/mkdocs/docs/integration/hunter/CMakeLists.txt b/docs/mkdocs/docs/integration/hunter/CMakeLists.txt index 4acc32586..46f249f30 100644 --- a/docs/mkdocs/docs/integration/hunter/CMakeLists.txt +++ b/docs/mkdocs/docs/integration/hunter/CMakeLists.txt @@ -2,8 +2,8 @@ cmake_minimum_required(VERSION 3.15) include("cmake/HunterGate.cmake") HunterGate( - URL "https://github.com/cpp-pm/hunter/archive/v0.23.297.tar.gz" - SHA1 "3319fe6a3b08090df7df98dee75134d68e2ef5a3" + URL "https://github.com/cpp-pm/hunter/archive/v0.26.12.tar.gz" + SHA1 "6498c5d0dec25d7fffb2b0574ebaf265179b894d" ) project(json_example) diff --git a/docs/mkdocs/hooks/copy_markdown_source.py b/docs/mkdocs/hooks/copy_markdown_source.py index dfdd9cc7b..967796c55 100644 --- a/docs/mkdocs/hooks/copy_markdown_source.py +++ b/docs/mkdocs/hooks/copy_markdown_source.py @@ -2,12 +2,30 @@ # Creates a `.md` sibling of each HTML output (for example, # `features/comments/` becomes `features/comments.md`) so agents and tools can -# fetch the raw Markdown directly instead of parsing rendered HTML. +# fetch the raw Markdown directly instead of parsing rendered HTML. The +# `--8<-- "path"` lines of pymdownx.snippets are expanded with the extension's +# own preprocessor and the settings from mkdocs.yml, so the copies contain the +# included example code and files instead of the include directives. +import io import os -import shutil + +import markdown +from pymdownx.snippets import SnippetMissingError _pages = [] +_snippets = None + + +def on_config(config): + global _snippets + md = markdown.Markdown( + extensions=["pymdownx.snippets"], + extension_configs={"pymdownx.snippets": config["mdx_configs"].get("pymdownx.snippets", {})}, + ) + _snippets = md.preprocessors["snippet"] + _snippets.auto_append = [] # the glossary is only needed to render abbreviations + return config def on_files(files, config): @@ -22,4 +40,11 @@ def on_post_build(config): url = file.url.rstrip("/") target = os.path.join(site_dir, (url or "index") + ".md") os.makedirs(os.path.dirname(target), exist_ok=True) - shutil.copyfile(file.abs_src_path, target) + with io.open(file.abs_src_path, encoding="utf-8", newline="") as source: + text = source.read() + try: + text = "\n".join(_snippets.run(text.split("\n"))) + except (SnippetMissingError, OSError): + pass # keep the include directives; the regular build reports the missing file + with io.open(target, "w", encoding="utf-8", newline="") as copy: + copy.write(text) diff --git a/docs/mkdocs/includes/glossary.md b/docs/mkdocs/includes/glossary.md index 9f2c6329d..86fbe313e 100644 --- a/docs/mkdocs/includes/glossary.md +++ b/docs/mkdocs/includes/glossary.md @@ -1,7 +1,7 @@ *[ADL]: Argument-dependent lookup -*[API]: Application Programming Interfaces +*[API]: Application Programming Interface *[ASCII]: American Standard Code for Information Interchange *[BDFL]: Benevolent Dictator for Life *[BJData]: Binary JData diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index f38d70038..111e0da81 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -299,6 +299,7 @@ nav: - 'JSON_DISABLE_TUPLE_REFERENCE_CONVERSION': api/macros/json_disable_tuple_reference_conversion.md - 'JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26': api/macros/json_has_cpp_11.md - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM, JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md + - 'JSON_HAS_RANGE_VIEW_CONVERSION': api/macros/json_has_range_view_conversion.md - 'JSON_HAS_RANGES': api/macros/json_has_ranges.md - 'JSON_HAS_STATIC_RTTI': api/macros/json_has_static_rtti.md - 'JSON_HAS_STD_FORMAT': api/macros/json_has_std_format.md