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

Conflicts: none textual. Follow-up fixes for develop's changes:
- docs/mkdocs/docs/api/ordered_map/index.md: develop's new paragraph
  (#5609) was written for api/ordered_map.md; fixed its relative
  ordered_json.md link for the page's new location, plus two
  pre-existing links from an earlier merge (ordered_json.md,
  features/object_order.md)
- tools/api_checker/api_surface.json: regenerated with libclang 18.1.1
  on Linux (swap() noexcept now includes json_base_class_t; new
  integral-key contains/count/find/value overloads)

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

tools/amalgamate/CHANGES.md

@@ -8,3 +8,6 @@ The following changes have been made to the code with respect to <https://github
   - membership check
   - made function from `_is_within`
   - removed unused variable `actual_path`
+- Added the optional config key `external`: include paths listed there are kept as
+  `#include` directives instead of being inlined (the first directive per path; the
+  repeated ones are commented out).

tools/amalgamate/README.md

@@ -57,6 +57,11 @@ Python v.2.7.0 or higher is required.
    amalgamation. Have a look at `test/source.c.json` and `test/include.h.json`
    to see two examples.
 
+   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
+   that includes another amalgamated header. Only the first directive for each
+   of these paths is kept; the repeated ones are commented out.
+
  * The `-s, --source` option should specify the path to the source directory.
    This is useful for supporting separate source and build directories.
 

tools/amalgamate/amalgamate.py

@@ -62,6 +62,10 @@ class Amalgamation(object):
         return None
 
     def __init__(self, args):
+        # include paths that are kept as #include directives instead of
+        # being inlined (e.g. a header amalgamated on its own)
+        self.external = []
+        self.included_external = []
         with open(args.config, 'r') as f:
             config = json.loads(f.read())
             for key in config:
@@ -220,11 +224,14 @@ class TranslationUnit(object):
         while include_match:
             if not _is_within(include_match, skippable_contexts):
                 include_path = include_match.group("path")
-                search_same_dir = include_match.group(1) == '"'
-                found_included_path = self.amalgamation.find_included_file(
-                    include_path, self.file_dir if search_same_dir else None)
-                if found_included_path:
-                    includes.append((include_match, found_included_path))
+                if include_path in self.amalgamation.external:
+                    includes.append((include_match, None))
+                else:
+                    search_same_dir = include_match.group(1) == '"'
+                    found_included_path = self.amalgamation.find_included_file(
+                        include_path, self.file_dir if search_same_dir else None)
+                    if found_included_path:
+                        includes.append((include_match, found_included_path))
 
             include_match = self.include_pattern.search(self.content,
                                                         include_match.end())
@@ -235,6 +242,17 @@ class TranslationUnit(object):
         for include in includes:
             include_match, found_included_path = include
             tmp_content += self.content[prev_end:include_match.start()]
+            if found_included_path is None:
+                # an external header: keep the first directive and comment
+                # out the repeated ones
+                include_path = include_match.group("path")
+                if include_path in self.amalgamation.included_external:
+                    tmp_content += "// {0}".format(include_match.group(0))
+                else:
+                    self.amalgamation.included_external.append(include_path)
+                    tmp_content += include_match.group(0)
+                prev_end = include_match.end()
+                continue
             tmp_content += "// {0}\n".format(include_match.group(0))
             if found_included_path not in self.amalgamation.included_files:
                 t = TranslationUnit(found_included_path, self.amalgamation, False)

tools/amalgamate/config_json_view.json

@@ -0,0 +1,9 @@
+{
+	"project": "JSON for Modern C++",
+	"target": "single_include/nlohmann/json_view.hpp",
+	"sources": [
+		"include/nlohmann/json_view.hpp"
+	],
+	"include_paths": ["include"],
+	"external": ["nlohmann/json.hpp"]
+}

tools/api_checker/api_surface.json

@@ -136,7 +136,7 @@
       "name": "swap",
       "pretty_signature": "nlohmann::swap",
       "scope": "nlohmann",
-      "signature": "friend void swap(reference left, reference right) noexcept ( std::is_nothrow_move_constructible<value_t>::value&& std::is_nothrow_move_assignable<value_t>::value&& std::is_nothrow_move_constructible<json_value>::value&& std::is_nothrow_move_assignable<json_value>::value )",
+      "signature": "friend void swap(reference left, reference right) noexcept ( std::is_nothrow_move_constructible<value_t>::value&& std::is_nothrow_move_assignable<value_t>::value&& std::is_nothrow_move_constructible<json_value>::value&& std::is_nothrow_move_assignable<json_value>::value&& std::is_nothrow_move_constructible<json_base_class_t>::value&& std::is_nothrow_move_assignable<json_base_class_t>::value )",
       "tier": "callable"
     },
     {
@@ -607,6 +607,15 @@
       "signature": "template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) bool contains(const typename ::nlohmann::json_pointer<BasicJsonType>& ptr) const",
       "tier": "callable"
     },
+    {
+      "identity_name": "contains",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "contains",
+      "pretty_signature": "nlohmann::basic_json::contains",
+      "scope": "nlohmann::basic_json",
+      "signature": "template<typename T, detail::enable_if_t<std::is_integral<T>::value, int> = 0> bool contains(T) const",
+      "tier": "callable"
+    },
     {
       "identity_name": "count",
       "kind": "CXX_METHOD",
@@ -625,6 +634,15 @@
       "signature": "template<class KeyType, detail::enable_if_t< detail::is_usable_as_basic_json_key_type<basic_json_t, KeyType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT size_type count(KeyType && key) const",
       "tier": "callable"
     },
+    {
+      "identity_name": "count",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "count",
+      "pretty_signature": "nlohmann::basic_json::count",
+      "scope": "nlohmann::basic_json",
+      "signature": "template<typename T, detail::enable_if_t<std::is_integral<T>::value, int> = 0> size_type count(T) const",
+      "tier": "callable"
+    },
     {
       "identity_name": "crbegin",
       "kind": "CXX_METHOD",
@@ -823,6 +841,24 @@
       "signature": "template<class KeyType, detail::enable_if_t< detail::is_usable_as_basic_json_key_type<basic_json_t, KeyType>::value, int> = 0> iterator find(KeyType && key)",
       "tier": "callable"
     },
+    {
+      "identity_name": "find",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "find",
+      "pretty_signature": "nlohmann::basic_json::find",
+      "scope": "nlohmann::basic_json",
+      "signature": "template<typename T, detail::enable_if_t<std::is_integral<T>::value, int> = 0> const_iterator find(T) const",
+      "tier": "callable"
+    },
+    {
+      "identity_name": "find",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "find",
+      "pretty_signature": "nlohmann::basic_json::find",
+      "scope": "nlohmann::basic_json",
+      "signature": "template<typename T, detail::enable_if_t<std::is_integral<T>::value, int> = 0> iterator find(T)",
+      "tier": "callable"
+    },
     {
       "identity_name": "flatten",
       "kind": "CXX_METHOD",
@@ -1936,7 +1972,7 @@
       "name": "swap",
       "pretty_signature": "nlohmann::basic_json::swap",
       "scope": "nlohmann::basic_json",
-      "signature": "void swap(reference other) noexcept ( std::is_nothrow_move_constructible<value_t>::value&& std::is_nothrow_move_assignable<value_t>::value&& std::is_nothrow_move_constructible<json_value>::value&& std::is_nothrow_move_assignable<json_value>::value )",
+      "signature": "void swap(reference other) noexcept ( std::is_nothrow_move_constructible<value_t>::value&& std::is_nothrow_move_assignable<value_t>::value&& std::is_nothrow_move_constructible<json_value>::value&& std::is_nothrow_move_assignable<json_value>::value&& std::is_nothrow_move_constructible<json_base_class_t>::value&& std::is_nothrow_move_assignable<json_base_class_t>::value )",
       "tier": "callable"
     },
     {
@@ -2245,6 +2281,15 @@
       "signature": "template < class ValueType, detail::enable_if_t < detail::is_getable<basic_json_t, ValueType>::value && !std::is_same<value_t, detail::uncvref_t<ValueType>>::value, int > = 0 > ValueType value(const json_pointer& ptr, const ValueType& default_value) const",
       "tier": "callable"
     },
+    {
+      "identity_name": "value",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "value",
+      "pretty_signature": "nlohmann::basic_json::value",
+      "scope": "nlohmann::basic_json",
+      "signature": "template<typename T, typename ValueType, detail::enable_if_t<std::is_integral<T>::value, int> = 0> ValueType value(T, ValueType&&) const",
+      "tier": "callable"
+    },
     {
       "identity_name": "value_t",
       "kind": "TYPE_ALIAS_DECL",