Merge branch 'develop' into claude/todo-191-plan-508110

- ordered_map.hpp: develop's refactored members, with this branch's
  @sa links on every public member
- byte_container_with_subtype operator==/!= and ordered_map docs:
  develop's reviewed text (#5638); drop the now unreferenced examples
- basic_json.md: keep both version-history additions
- add the docset entries that develop's style check now requires for the
  25 API pages this branch adds
- regenerate tools/api_checker/api_surface.json for develop's API

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

tools/amalgamate/README.md

@@ -1,8 +1,8 @@
 # amalgamate.py - Amalgamate C source and header files
 
-Origin: https://bitbucket.org/erikedlund/amalgamate
-
-Mirror: https://github.com/edlund/amalgamate
+Origin: https://github.com/edlund/amalgamate (formerly hosted at
+https://bitbucket.org/erikedlund/amalgamate, which no longer exists; see
+`CHANGES.md` for the upstream commit this copy is based on)
 
 `amalgamate.py` aims to make it easy to use SQLite-style C source and header
 amalgamation in projects.
@@ -41,21 +41,22 @@ results.
 
 ## Installing amalgamate.py
 
-Python v.2.7.0 or higher is required.
+Python 3 is required.
 
-`amalgamate.py` can be tested and installed using the following commands:
-
-        ./test.sh && sudo -k cp ./amalgamate.py /usr/local/bin/
+In this repository, `amalgamate.py` is not installed separately; it is run in
+place through `make amalgamate`, which calls it once for `json.hpp` and once
+for `json_fwd.hpp` (see the root `Makefile`).
 
 ## Using amalgamate.py
 
-        amalgamate.py [-v] -c path/to/config.json -s path/to/source/dir \
-                [-p path/to/prologue.(c|h)]
+        amalgamate.py -c path/to/config.json -s path/to/source/dir \
+                [-p path/to/prologue.(c|h)] [--verbose=yes|no]
 
  * The `-c, --config` option should specify the path to a JSON config file which
    lists the source files, include paths and where to write the resulting
-   amalgamation. Have a look at `test/source.c.json` and `test/include.h.json`
-   to see two examples.
+   amalgamation. `config_json.json` and `config_json_fwd.json` in this
+   directory are the configs used for `json.hpp` and `json_fwd.hpp`; each
+   sets `target`, `sources` and `include_paths`.
 
    The optional `external` list names include paths that are kept as `#include`
    directives instead of being inlined, e.g. `["nlohmann/json.hpp"]` for a header
@@ -68,3 +69,6 @@ Python v.2.7.0 or higher is required.
  * The `-p, --prologue` option should specify the path to a file which will be
    added to the beginning of the amalgamation. It is optional.
 
+ * The `-v, --verbose` option takes `yes` or `no` (for example
+   `--verbose=yes`, as used by the Makefile). It is optional.
+

tools/api_checker/api_surface.json

@@ -220,6 +220,24 @@
       "signature": "using array_t = ArrayType<basic_json, AllocatorType<basic_json>>",
       "tier": "type"
     },
+    {
+      "identity_name": "as_base_class",
+      "kind": "CXX_METHOD",
+      "name": "as_base_class",
+      "pretty_signature": "nlohmann::basic_json::as_base_class",
+      "scope": "nlohmann::basic_json",
+      "signature": "const json_base_class_t& as_base_class() const noexcept",
+      "tier": "callable"
+    },
+    {
+      "identity_name": "as_base_class",
+      "kind": "CXX_METHOD",
+      "name": "as_base_class",
+      "pretty_signature": "nlohmann::basic_json::as_base_class",
+      "scope": "nlohmann::basic_json",
+      "signature": "json_base_class_t& as_base_class() noexcept",
+      "tier": "callable"
+    },
     {
       "identity_name": "at",
       "kind": "CXX_METHOD",
@@ -355,6 +373,15 @@
       "signature": "basic_json(const value_t v)",
       "tier": "callable"
     },
+    {
+      "identity_name": "(constructor)",
+      "kind": "CONSTRUCTOR",
+      "name": "basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
+      "pretty_signature": "nlohmann::basic_json::basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
+      "scope": "nlohmann::basic_json",
+      "signature": "basic_json(copy_construct_tag , const basic_json& src) noexcept(std::is_nothrow_copy_constructible<json_base_class_t>::value)",
+      "tier": "callable"
+    },
     {
       "identity_name": "(constructor)",
       "kind": "CONSTRUCTOR",
@@ -397,7 +424,7 @@
       "name": "basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
       "pretty_signature": "nlohmann::basic_json::basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
       "scope": "nlohmann::basic_json",
-      "signature": "template < typename BasicJsonType, detail::enable_if_t < detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value, int > = 0 > basic_json(const BasicJsonType& val) #if JSON_DIAGNOSTIC_POSITIONS",
+      "signature": "template < typename BasicJsonType, detail::enable_if_t < detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value && !is_implicitly_convertible_basic_json<BasicJsonType>::value, int > = 0 > explicit basic_json(const BasicJsonType& val)",
       "tier": "callable"
     },
     {
@@ -406,7 +433,16 @@
       "name": "basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
       "pretty_signature": "nlohmann::basic_json::basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
       "scope": "nlohmann::basic_json",
-      "signature": "template < typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>, detail::enable_if_t < !detail::is_basic_json<U>::value && detail::is_compatible_type<basic_json_t, U>::value, int > = 0 > basic_json(CompatibleType && val) noexcept(noexcept( JSONSerializer<U>::to_json(std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))",
+      "signature": "template < typename BasicJsonType, detail::enable_if_t < detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value && is_implicitly_convertible_basic_json<BasicJsonType>::value, int > = 0 > basic_json(const BasicJsonType& val)",
+      "tier": "callable"
+    },
+    {
+      "identity_name": "(constructor)",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
+      "pretty_signature": "nlohmann::basic_json::basic_json<ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>",
+      "scope": "nlohmann::basic_json",
+      "signature": "template < typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>, detail::enable_if_t < !detail::is_basic_json<U>::value && detail::is_compatible_type<basic_json_t, U>::value #if JSON_DISABLE_TUPLE_REFERENCE_CONVERSION && !detail::is_basic_json_reference_tuple<basic_json_t, U>::value #endif , int > = 0 > basic_json(CompatibleType && val) noexcept(noexcept( JSONSerializer<U>::to_json(std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))",
       "tier": "callable"
     },
     {
@@ -874,7 +910,7 @@
       "name": "from_bjdata",
       "pretty_signature": "nlohmann::basic_json::from_bjdata",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bjdata(InputType&& i, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bjdata(InputType&& i, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -883,7 +919,7 @@
       "name": "from_bjdata",
       "pretty_signature": "nlohmann::basic_json::from_bjdata",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bjdata(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bjdata(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -919,7 +955,7 @@
       "name": "from_bson",
       "pretty_signature": "nlohmann::basic_json::from_bson",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(InputType&& i, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(InputType&& i, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -928,7 +964,7 @@
       "name": "from_bson",
       "pretty_signature": "nlohmann::basic_json::from_bson",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -955,7 +991,7 @@
       "name": "from_cbor",
       "pretty_signature": "nlohmann::basic_json::from_cbor",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_cbor(InputType&& i, const bool strict = true, const bool allow_exceptions = true, const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error)",
+      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_cbor(InputType&& i, const bool strict = true, const bool allow_exceptions = true, const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -964,7 +1000,7 @@
       "name": "from_cbor",
       "pretty_signature": "nlohmann::basic_json::from_cbor",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_cbor(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true, const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error)",
+      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_cbor(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true, const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -991,7 +1027,7 @@
       "name": "from_msgpack",
       "pretty_signature": "nlohmann::basic_json::from_msgpack",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_msgpack(InputType&& i, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_msgpack(InputType&& i, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -1000,7 +1036,7 @@
       "name": "from_msgpack",
       "pretty_signature": "nlohmann::basic_json::from_msgpack",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_msgpack(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_msgpack(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -1027,7 +1063,7 @@
       "name": "from_ubjson",
       "pretty_signature": "nlohmann::basic_json::from_ubjson",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_ubjson(InputType&& i, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_ubjson(InputType&& i, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -1036,7 +1072,7 @@
       "name": "from_ubjson",
       "pretty_signature": "nlohmann::basic_json::from_ubjson",
       "scope": "nlohmann::basic_json",
-      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_ubjson(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true)",
+      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_ubjson(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -1426,6 +1462,15 @@
       "signature": "JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items()) static iteration_proxy<iterator> iterator_wrapper(reference ref) noexcept",
       "tier": "callable"
     },
+    {
+      "identity_name": "json_base_class_t",
+      "kind": "TYPE_ALIAS_DECL",
+      "name": "json_base_class_t",
+      "pretty_signature": "nlohmann::basic_json::json_base_class_t",
+      "scope": "nlohmann::basic_json",
+      "signature": "using json_base_class_t = ::nlohmann::detail::json_base_class<CustomBaseClass>",
+      "tier": "type"
+    },
     {
       "identity_name": "json_pointer",
       "kind": "TYPE_ALIAS_DECL",
@@ -1999,7 +2044,7 @@
       "name": "to_bjdata",
       "pretty_signature": "nlohmann::basic_json::to_bjdata",
       "scope": "nlohmann::basic_json",
-      "signature": "static std::vector<std::uint8_t> to_bjdata(const basic_json& j, const bool use_size = false, const bool use_type = false, const bjdata_version_t version = bjdata_version_t::draft2)",
+      "signature": "static std::vector<std::uint8_t> to_bjdata(const basic_json& j, const bool use_size = false, const bool use_type = false, const bjdata_version_t version = bjdata_version_t::draft2, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2008,7 +2053,7 @@
       "name": "to_bjdata",
       "pretty_signature": "nlohmann::basic_json::to_bjdata",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_bjdata(const basic_json& j, detail::output_adapter<char> o, const bool use_size = false, const bool use_type = false, const bjdata_version_t version = bjdata_version_t::draft2)",
+      "signature": "static void to_bjdata(const basic_json& j, detail::output_adapter<char> o, const bool use_size = false, const bool use_type = false, const bjdata_version_t version = bjdata_version_t::draft2, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2017,7 +2062,7 @@
       "name": "to_bjdata",
       "pretty_signature": "nlohmann::basic_json::to_bjdata",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_bjdata(const basic_json& j, detail::output_adapter<std::uint8_t> o, const bool use_size = false, const bool use_type = false, const bjdata_version_t version = bjdata_version_t::draft2)",
+      "signature": "static void to_bjdata(const basic_json& j, detail::output_adapter<std::uint8_t> o, const bool use_size = false, const bool use_type = false, const bjdata_version_t version = bjdata_version_t::draft2, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2053,7 +2098,7 @@
       "name": "to_bson",
       "pretty_signature": "nlohmann::basic_json::to_bson",
       "scope": "nlohmann::basic_json",
-      "signature": "static std::vector<std::uint8_t> to_bson(const basic_json& j)",
+      "signature": "static std::vector<std::uint8_t> to_bson(const basic_json& j, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2062,7 +2107,7 @@
       "name": "to_bson",
       "pretty_signature": "nlohmann::basic_json::to_bson",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_bson(const basic_json& j, detail::output_adapter<char> o)",
+      "signature": "static void to_bson(const basic_json& j, detail::output_adapter<char> o, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2071,7 +2116,7 @@
       "name": "to_bson",
       "pretty_signature": "nlohmann::basic_json::to_bson",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_bson(const basic_json& j, detail::output_adapter<std::uint8_t> o)",
+      "signature": "static void to_bson(const basic_json& j, detail::output_adapter<std::uint8_t> o, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2080,7 +2125,7 @@
       "name": "to_cbor",
       "pretty_signature": "nlohmann::basic_json::to_cbor",
       "scope": "nlohmann::basic_json",
-      "signature": "static std::vector<std::uint8_t> to_cbor(const basic_json& j)",
+      "signature": "static std::vector<std::uint8_t> to_cbor(const basic_json& j, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2089,7 +2134,7 @@
       "name": "to_cbor",
       "pretty_signature": "nlohmann::basic_json::to_cbor",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_cbor(const basic_json& j, detail::output_adapter<char> o)",
+      "signature": "static void to_cbor(const basic_json& j, detail::output_adapter<char> o, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2098,7 +2143,7 @@
       "name": "to_cbor",
       "pretty_signature": "nlohmann::basic_json::to_cbor",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_cbor(const basic_json& j, detail::output_adapter<std::uint8_t> o)",
+      "signature": "static void to_cbor(const basic_json& j, detail::output_adapter<std::uint8_t> o, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2107,7 +2152,7 @@
       "name": "to_msgpack",
       "pretty_signature": "nlohmann::basic_json::to_msgpack",
       "scope": "nlohmann::basic_json",
-      "signature": "static std::vector<std::uint8_t> to_msgpack(const basic_json& j)",
+      "signature": "static std::vector<std::uint8_t> to_msgpack(const basic_json& j, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -2116,7 +2161,7 @@
       "name": "to_msgpack",
       "pretty_signature": "nlohmann::basic_json::to_msgpack",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_msgpack(const basic_json& j, detail::output_adapter<char> o)",
+      "signature": "static void to_msgpack(const basic_json& j, detail::output_adapter<char> o, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -2125,7 +2170,7 @@
       "name": "to_msgpack",
       "pretty_signature": "nlohmann::basic_json::to_msgpack",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_msgpack(const basic_json& j, detail::output_adapter<std::uint8_t> o)",
+      "signature": "static void to_msgpack(const basic_json& j, detail::output_adapter<std::uint8_t> o, const error_handler_t error_handler = error_handler_t::keep)",
       "tier": "callable"
     },
     {
@@ -2134,7 +2179,7 @@
       "name": "to_ubjson",
       "pretty_signature": "nlohmann::basic_json::to_ubjson",
       "scope": "nlohmann::basic_json",
-      "signature": "static std::vector<std::uint8_t> to_ubjson(const basic_json& j, const bool use_size = false, const bool use_type = false)",
+      "signature": "static std::vector<std::uint8_t> to_ubjson(const basic_json& j, const bool use_size = false, const bool use_type = false, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2143,7 +2188,7 @@
       "name": "to_ubjson",
       "pretty_signature": "nlohmann::basic_json::to_ubjson",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_ubjson(const basic_json& j, detail::output_adapter<char> o, const bool use_size = false, const bool use_type = false)",
+      "signature": "static void to_ubjson(const basic_json& j, detail::output_adapter<char> o, const bool use_size = false, const bool use_type = false, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2152,7 +2197,7 @@
       "name": "to_ubjson",
       "pretty_signature": "nlohmann::basic_json::to_ubjson",
       "scope": "nlohmann::basic_json",
-      "signature": "static void to_ubjson(const basic_json& j, detail::output_adapter<std::uint8_t> o, const bool use_size = false, const bool use_type = false)",
+      "signature": "static void to_ubjson(const basic_json& j, detail::output_adapter<std::uint8_t> o, const bool use_size = false, const bool use_type = false, const error_handler_t error_handler = detail::binary_writer_default_error_handler())",
       "tier": "callable"
     },
     {
@@ -2473,8 +2518,8 @@
     {
       "identity_name": "operator string_t",
       "kind": "CONVERSION_FUNCTION",
-      "name": "operator typename string_t_helper<type-parameter-0-0>::type",
-      "pretty_signature": "nlohmann::json_pointer::operator typename string_t_helper<type-parameter-0-0>::type",
+      "name": "operator nlohmann::json_pointer::string_t_helper<type-parameter-0-0>::type",
+      "pretty_signature": "nlohmann::json_pointer::operator nlohmann::json_pointer::string_t_helper<type-parameter-0-0>::type",
       "scope": "nlohmann::json_pointer",
       "signature": "JSON_HEDLEY_DEPRECATED_FOR(3.11.0, to_string()) operator string_t() const",
       "tier": "callable"
@@ -2877,11 +2922,11 @@
     },
     {
       "identity_name": "emplace",
-      "kind": "CXX_METHOD",
+      "kind": "FUNCTION_TEMPLATE",
       "name": "emplace",
       "pretty_signature": "nlohmann::ordered_map::emplace",
       "scope": "nlohmann::ordered_map",
-      "signature": "std::pair<iterator, bool> emplace(const key_type& key, T&& t)",
+      "signature": "template<class KeyType, class V, detail::enable_if_t< detail::conjunction<detail::is_usable_as_key_type<key_compare, key_type, KeyType>, detail::is_constructible<T, V>>::value, int> = 0> std::pair<iterator, bool> emplace(KeyType && key, V && t)",
       "tier": "callable"
     },
     {
@@ -2890,7 +2935,7 @@
       "name": "emplace",
       "pretty_signature": "nlohmann::ordered_map::emplace",
       "scope": "nlohmann::ordered_map",
-      "signature": "template<class KeyType, detail::enable_if_t< detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0> std::pair<iterator, bool> emplace(KeyType && key, T && t)",
+      "signature": "template<class V, detail::enable_if_t< detail::is_constructible<T, V>::value, int> = 0> std::pair<iterator, bool> emplace(const key_type& key, V && t)",
       "tier": "callable"
     },
     {

tools/astyle/requirements.txt

@@ -1 +1,4 @@
+# astyle is deliberately pinned: newer versions reformat the code, and this version
+# defines the formatting that `make amalgamate` produces and check_amalgamation.yml enforces.
+# Dependabot is told to ignore it in .github/dependabot.yml.
 astyle==3.4.13

tools/generate_natvis/README.md

@@ -2,8 +2,26 @@
 
 Generate the Natvis debugger visualization file for all supported namespace combinations.
 
+The ABI tag list and the library version are parsed from
+`include/nlohmann/detail/abi_macros.hpp`, so this script must be re-run (via
+`make natvis`) whenever an `NLOHMANN_JSON_ABI_TAG_*` macro is added to that
+file or the library version is bumped — otherwise the committed
+`nlohmann_json.natvis` drifts from the header it visualizes, and
+`make check-amalgamation` fails.
+
 ## Usage
 
 ```shell
-./generate_natvis.py --version X.Y.Z output_directory/
+make natvis
 ```
+
+or, equivalently:
+
+```shell
+./generate_natvis.py [--version X.Y.Z] [repository_root/]
+```
+
+`--version` and the output/repository-root directory both default to values
+derived from this script's own location, so they only need to be given
+explicitly when generating a Natvis file for a different checkout or a
+version other than the one in `abi_macros.hpp`.

tools/generate_natvis/generate_natvis.py

@@ -7,21 +7,75 @@ import os
 import re
 import sys
 
+# Directory of the repository, assuming this script stays at
+# tools/generate_natvis/generate_natvis.py. Used only as the default value
+# for the "output" argument below.
+REPO_ROOT = os.path.normpath(os.path.join(sys.path[0], '..', '..'))
+
+
 def semver(v):
     if not re.fullmatch(r'\d+\.\d+\.\d+', v):
         raise ValueError
     return v
 
+
+def abi_info(repo_root):
+    """Derive the ABI tag list (in NLOHMANN_JSON_ABI_TAGS_CONCAT order) and the
+    library version from <repo_root>/include/nlohmann/detail/abi_macros.hpp,
+    so this script cannot drift from the header it visualizes."""
+    abi_macros_hpp = os.path.join(repo_root, 'include', 'nlohmann', 'detail', 'abi_macros.hpp')
+    with open(abi_macros_hpp) as f:
+        content = f.read()
+
+    # find the NLOHMANN_JSON_ABI_TAGS_CONCAT(...) invocation that lists the
+    # NLOHMANN_JSON_ABI_TAG_* identifiers in order (not its own #define, which
+    # only names its formal parameters a, b, c, ...)
+    tag_idents = None
+    for args in re.findall(r'NLOHMANN_JSON_ABI_TAGS_CONCAT\(\s*(.*?)\)', content, re.S):
+        idents = re.findall(r'NLOHMANN_JSON_ABI_TAG_\w+', args)
+        if idents:
+            tag_idents = idents
+            break
+    if not tag_idents:
+        raise ValueError(f'could not find NLOHMANN_JSON_ABI_TAGS_CONCAT(...) in {abi_macros_hpp}')
+
+    abi_tags = []
+    for ident in tag_idents:
+        # each tag is #define'd to its suffix (e.g. _diag) when the matching
+        # JSON_* option is enabled, and to nothing in the #else branch; only
+        # the non-empty definition matches here
+        match = re.search(r'#define\s+' + re.escape(ident) + r'\s+(_\w+)\s*\n', content)
+        if not match:
+            raise ValueError(f'could not find a non-empty #define for {ident} in {abi_macros_hpp}')
+        abi_tags.append(match.group(1))
+
+    version = {}
+    for part in ('MAJOR', 'MINOR', 'PATCH'):
+        match = re.search(r'#define\s+NLOHMANN_JSON_VERSION_' + part + r'\s+(\d+)', content)
+        if not match:
+            raise ValueError(f'could not find NLOHMANN_JSON_VERSION_{part} in {abi_macros_hpp}')
+        version[part] = match.group(1)
+
+    return abi_tags, '{MAJOR}.{MINOR}.{PATCH}'.format(**version)
+
+
 if __name__ == '__main__':
     parser = argparse.ArgumentParser()
-    parser.add_argument('--version', required=True, type=semver, help='Library version number')
-    parser.add_argument('output', help='Output directory for nlohmann_json.natvis')
+    parser.add_argument('--version', type=semver,
+                         help='Library version number (default: parsed from '
+                              'include/nlohmann/detail/abi_macros.hpp below "output")')
+    parser.add_argument('output', nargs='?', default=REPO_ROOT,
+                         help='Repository root: where include/nlohmann/detail/abi_macros.hpp is '
+                              'read from and where nlohmann_json.natvis is written '
+                              '(default: the repository root this script lives in)')
     args = parser.parse_args()
 
+    derived_tags, derived_version = abi_info(args.output)
+
     namespaces = ['nlohmann']
     abi_prefix = 'json_abi'
-    abi_tags = ['_diag', '_ldvcmp', '_dp', '_bics', '_psp', '_snul']
-    version = '_v' + args.version.replace('.', '_')
+    abi_tags = derived_tags
+    version = '_v' + (args.version or derived_version).replace('.', '_')
     inline_namespaces = []
 
     # generate all combinations of inline namespace names

tools/macro_builder/README.md

@@ -0,0 +1,51 @@
+# macro_builder
+
+Generates the argument-counting macros behind the `NLOHMANN_DEFINE_TYPE_*` and `NLOHMANN_DEFINE_DERIVED_TYPE_*`
+macros in [`include/nlohmann/detail/macro_scope.hpp`](../../include/nlohmann/detail/macro_scope.hpp):
+
+- `NLOHMANN_JSON_EXPAND`
+- `NLOHMANN_JSON_GET_MACRO`, which selects a macro by the number of its arguments (64 slots)
+- `NLOHMANN_JSON_PASTE`, which calls a function-like macro for each member, and its helpers `NLOHMANN_JSON_PASTE2`
+  to `NLOHMANN_JSON_PASTE64`
+- `NLOHMANN_JSON_DOUBLE_PASTE`, which the `*_WITH_NAMES` macros use to call a function-like macro for each
+  (JSON name, member) pair, and its helpers `NLOHMANN_JSON_DOUBLE_PASTE3` to `NLOHMANN_JSON_DOUBLE_PASTE63`
+- the slot table of `NLOHMANN_JSON_TYPE_BODY`, which dispatches `NLOHMANN_DEFINE_TYPE_*(Type)` (no further
+  arguments) to the zero-member implementation and every other argument count to the one-or-more-member
+  implementation
+
+The number of slots (`max_args` in [`main.cpp`](main.cpp)) sets the member limit of these macros.
+`NLOHMANN_JSON_PASTE` and `NLOHMANN_JSON_TYPE_BODY` take the function/prefix as their first argument, so 64 slots
+allow 63 members; `NLOHMANN_JSON_DOUBLE_PASTE` additionally consumes its members two at a time (name, member), so
+it only defines the odd helpers up to `NLOHMANN_JSON_DOUBLE_PASTE63`.
+
+## Usage
+
+From the project root:
+
+```shell
+c++ -std=c++11 tools/macro_builder/main.cpp -o macro_builder
+./macro_builder
+./macro_builder type_body
+```
+
+1. Run `./macro_builder` (no arguments). In `include/nlohmann/detail/macro_scope.hpp`, replace the lines from
+   `#define NLOHMANN_JSON_EXPAND( x ) x` to the `#define NLOHMANN_JSON_DOUBLE_PASTE63(...)` line with the output,
+   without its trailing empty line.
+2. Run `./macro_builder type_body`. Replace the lines from `#define NLOHMANN_JSON_TYPE_BODY(Prefix, ...)` to the
+   `NLOHMANN_JSON_TYPE_BODY_SENTINEL))` line with the output.
+3. Run `make amalgamate`. It updates `single_include/nlohmann/json.hpp` and runs `make pretty`, which indents the
+   continuation lines that the tool writes unindented.
+
+With an unchanged `main.cpp`, these steps reproduce both blocks of `macro_scope.hpp` byte for byte. `make
+macro_builder_check` (also run by CI, see `.github/workflows/check_amalgamation.yml`) automates this: it builds
+`main.cpp`, regenerates both blocks, and fails on a diff against the checked-in header.
+
+## Maintained by hand
+
+The tool does not generate everything that depends on the number of slots. When changing `max_args`, also update:
+
+- the documented limit of 63 members in `docs/mkdocs/docs` and the tests at that limit in
+  `tests/src/unit-udt_macro.cpp`
+
+All three tables pass one macro name per slot to `NLOHMANN_JSON_GET_MACRO`, so they need exactly as many entries as
+it has slots.

tools/macro_builder/main.cpp

@@ -1,10 +1,14 @@
 #include <cstdlib>
 #include <iostream>
 #include <sstream>
+#include <string>
 
 using namespace std;
 
-void build_code(int max_args)
+// Builds NLOHMANN_JSON_EXPAND, NLOHMANN_JSON_GET_MACRO, and the
+// NLOHMANN_JSON_PASTE / NLOHMANN_JSON_PASTE2..PASTE<max_args> dispatch table
+// and recursive definitions.
+string build_paste_code(int max_args)
 {
     stringstream ss;
     ss << "#define NLOHMANN_JSON_EXPAND( x ) x" << endl;
@@ -12,32 +16,93 @@ void build_code(int max_args)
     for (int i = 0 ; i < max_args ; i++)
         ss << "_" << i + 1 << ", ";
     ss << "NAME,...) NAME" << endl;
-    
+
     ss << "#define NLOHMANN_JSON_PASTE(...) NLOHMANN_JSON_EXPAND(NLOHMANN_JSON_GET_MACRO(__VA_ARGS__, \\" << endl;
     for (int i = max_args ; i > 1 ; i--)
         ss << "NLOHMANN_JSON_PASTE" << i << ", \\" << endl;
     ss << "NLOHMANN_JSON_PASTE1)(__VA_ARGS__))" << endl;
-    
+
     ss << "#define NLOHMANN_JSON_PASTE2(func, v1) func(v1)" << endl;
     for (int i = 3 ; i <= max_args ; i++)
     {
-        ss << "#define NLOHMANN_JSON_PASTE" << i << "(func, "; 
+        ss << "#define NLOHMANN_JSON_PASTE" << i << "(func, ";
         for (int j = 1 ; j < i -1 ; j++)
-            ss << "v" << j << ", "; 
+            ss << "v" << j << ", ";
         ss << "v" << i-1 << ") NLOHMANN_JSON_PASTE2(func, v1) NLOHMANN_JSON_PASTE" << i-1 << "(func, ";
         for (int j = 2 ; j < i-1 ; j++)
             ss << "v" << j << ", ";
         ss << "v" << i-1 << ")" << endl;
     }
-    
-    cout << ss.str() << endl;
+
+    return ss.str();
 }
 
-int main(int argc, char** argv) 
+// Builds the NLOHMANN_JSON_DOUBLE_PASTE dispatch table and recursive
+// definitions used by the *_WITH_NAMES macros. Its GET_MACRO dispatch reuses
+// the same max_args slots as NLOHMANN_JSON_PASTE, but DOUBLE_PASTE consumes
+// its arguments two at a time (name, member), so an even slot count falls
+// back to the next lower odd NLOHMANN_JSON_DOUBLE_PASTE<N>.
+string build_double_paste_code(int max_args)
+{
+    stringstream ss;
+    ss << "#define NLOHMANN_JSON_DOUBLE_PASTE(...) NLOHMANN_JSON_EXPAND(NLOHMANN_JSON_GET_MACRO(__VA_ARGS__, \\" << endl;
+    for (int i = max_args ; i > 1 ; i--)
+    {
+        int k = (i % 2 == 1) ? i : i - 1;
+        ss << "NLOHMANN_JSON_DOUBLE_PASTE" << k << ", \\" << endl;
+    }
+    ss << "NLOHMANN_JSON_DOUBLE_PASTE1)(__VA_ARGS__))" << endl;
+
+    ss << "#define NLOHMANN_JSON_DOUBLE_PASTE3(func, v1, v2) func(v1, v2)" << endl;
+    for (int k = 5 ; k <= max_args - 1 ; k += 2)
+    {
+        ss << "#define NLOHMANN_JSON_DOUBLE_PASTE" << k << "(func, ";
+        for (int j = 1 ; j < k - 1 ; j++)
+            ss << "v" << j << ", ";
+        ss << "v" << k - 1 << ") NLOHMANN_JSON_DOUBLE_PASTE3(func, v1, v2) NLOHMANN_JSON_DOUBLE_PASTE" << k - 2 << "(func, ";
+        for (int j = 3 ; j < k - 1 ; j++)
+            ss << "v" << j << ", ";
+        ss << "v" << k - 1 << ")" << endl;
+    }
+
+    return ss.str();
+}
+
+// Builds the NLOHMANN_JSON_TYPE_BODY dispatch table: max_args - 1 slots
+// selecting the *_MEMBERS implementation and a final slot selecting
+// *_EMPTY, so NLOHMANN_DEFINE_TYPE_*(Type) with no further arguments still
+// resolves (issue #4041).
+string build_type_body_table(int max_args)
+{
+    stringstream ss;
+    ss << "#define NLOHMANN_JSON_TYPE_BODY(Prefix, ...) NLOHMANN_JSON_EXPAND(NLOHMANN_JSON_GET_MACRO(__VA_ARGS__, \\" << endl;
+    const int per_line = 8;
+    for (int i = 1 ; i <= max_args ; i++)
+    {
+        ss << (i == max_args ? "Prefix ## EMPTY" : "Prefix ## MEMBERS") << ", ";
+        if (i % per_line == 0)
+            ss << "\\" << endl;
+    }
+    ss << "NLOHMANN_JSON_TYPE_BODY_SENTINEL))" << endl;
+
+    return ss.str();
+}
+
+int main(int argc, char** argv)
 {
     int max_args = 64;
-    build_code(max_args);
-       
+
+    // With "type_body", print only the NLOHMANN_JSON_TYPE_BODY dispatch
+    // table (a separate insertion point in macro_scope.hpp); otherwise
+    // print the EXPAND/GET_MACRO/PASTE/DOUBLE_PASTE block that precedes it.
+    if (argc > 1 && string(argv[1]) == "type_body")
+    {
+        cout << build_type_body_table(max_args);
+    }
+    else
+    {
+        cout << build_paste_code(max_args) << build_double_paste_code(max_args);
+    }
+
     return 0;
 }
-

tools/serve_header/serve_header.py

@@ -5,6 +5,8 @@ import logging
 import os
 import re
 import shutil
+import socket
+import ssl
 import sys
 import subprocess
 
@@ -34,7 +36,7 @@ JSON_VERSION_RE = re.compile(r'\s*#\s*define\s+NLOHMANN_JSON_VERSION_MAJOR\s+')
 
 class ExitHandler(logging.StreamHandler):
     def __init__(self, level):
-        """."""
+        """Exit the process on log records at or above level."""
         super().__init__()
         self.level = level
 
@@ -54,7 +56,7 @@ def is_project_root(test_dir='.'):
 
 class DirectoryEventBucket:
     def __init__(self, callback, delay=1.2, threshold=0.8):
-        """."""
+        """Batch directory events and pass their common path to callback."""
         self.delay = delay
         self.threshold = timedelta(seconds=threshold)
         self.callback = callback
@@ -99,7 +101,7 @@ class WorkTree:
     make_command = 'make'
 
     def __init__(self, root_dir, tree_dir):
-        """."""
+        """Track the working tree at tree_dir and its amalgamated header."""
         self.root_dir = root_dir
         self.tree_dir = tree_dir
         self.rel_dir = os.path.relpath(tree_dir, root_dir)
@@ -114,11 +116,11 @@ class WorkTree:
         self.build_time = t.strftime(DATETIME_FORMAT)
 
     def __hash__(self):
-        """."""
+        """Hash by working tree directory."""
         return hash((self.tree_dir))
 
     def __eq__(self, other):
-        """."""
+        """Compare by working tree directory."""
         if not isinstance(other, type(self)):
             return NotImplemented
         return self.tree_dir == other.tree_dir
@@ -150,7 +152,7 @@ class WorkTree:
 
 class WorkTrees(FileSystemEventHandler):
     def __init__(self, root_dir):
-        """."""
+        """Find the working trees below root_dir and watch it for changes."""
         super().__init__()
         self.root_dir = root_dir
         self.trees = set([])
@@ -250,11 +252,11 @@ class WorkTrees(FileSystemEventHandler):
         self.observer.stop()
         self.observer.join()
 
-class HeaderRequestHandler(SimpleHTTPRequestHandler): # lgtm[py/missing-call-to-init]
+class HeaderRequestHandler(SimpleHTTPRequestHandler):
     cors_origins = DEFAULT_CORS_ORIGINS
 
     def __init__(self, request, client_address, server):
-        """."""
+        """Handle a request for a header below the working trees' root directory."""
         self.worktrees = server.worktrees
         self.worktree = None
         try:
@@ -336,7 +338,7 @@ class HeaderRequestHandler(SimpleHTTPRequestHandler): # lgtm[py/missing-call-to-
 
 class DualStackServer(ThreadingHTTPServer):
     def __init__(self, addr, worktrees):
-        """."""
+        """Serve the headers of worktrees on addr."""
         self.worktrees = worktrees
         super().__init__(addr, HeaderRequestHandler)
 
@@ -349,8 +351,6 @@ class DualStackServer(ThreadingHTTPServer):
 
 if __name__ == '__main__':
     import argparse
-    import ssl
-    import socket
     import yaml
 
     # exit code