Move elements when converting rvalue containers to JSON

Add to_json overloads for rvalue array-like and object-like containers
that build the array/object from move iterators, so that
json j = std::move(vec) moves the elements instead of copying them.
std::vector<std::string> (100k x 40 chars): 4.7 ms -> 2.3 ms;
std::map<std::string, std::string>: -18 % (keys are const and still copied).

array_t/object_t, std::vector<bool>, std::filesystem::path and
std::u8string keep their dedicated overloads. Lvalues and const rvalues
are copied as before.

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

docs/mkdocs/docs/api/basic_json/basic_json.md

@@ -68,6 +68,14 @@ basic_json(basic_json&& other) noexcept;
      `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with a `key_type` compatible to `string_t`
      and a `value_type` from which a `basic_json` value can be constructed.
     - **strings**: `string_t`, string literals, and all compatible string containers can be used.
+
+    !!! note "Rvalue containers are moved from"
+
+        If `val` is an rvalue of a compatible array-like or object-like container other than `array_t`/`object_t`
+        (e.g., `json j = std::move(vec);` or `json j(std::vector<std::string>{...});`), the elements are moved into
+        the JSON value instead of copied. Afterwards, the elements of the source container are in a valid but
+        unspecified state (**moved-from**). Keys of associative containers are `const` and therefore still copied.
+        Lvalues and `const` rvalues are copied, and the source is left unchanged.
     - **numbers**: [`number_integer_t`](number_integer_t.md), [`number_unsigned_t`](number_unsigned_t.md),
      [`number_float_t`](number_float_t.md), and all convertible number types such as `int`, `size_t`, `int64_t`, `float`
      or `double` can be used.
@@ -236,7 +244,9 @@ basic_json(basic_json&& other) noexcept;
 2. No-throw guarantee: this constructor never throws exceptions.
 3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
    `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
-   JSON value.
+   JSON value. **Exception:** when `val` is an rvalue array-like or object-like container, its elements are moved one
+   by one; if an exception is thrown in the middle of the conversion (e.g., an allocation failure), the JSON value is
+   unchanged, but the source container may be left partially moved-from.
 4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
    `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
    JSON value.

docs/mkdocs/docs/home/releases.md

@@ -9,6 +9,15 @@ published on the [GitHub releases page](https://github.com/nlohmann/json/release
     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.

include/nlohmann/detail/conversions/to_json.hpp

@@ -167,6 +167,17 @@ struct external_constructor<value_t::array>
         j.replace_value(value_t::array, value);
     }
 
+    /// an rvalue container: move its elements
+    template<typename BasicJsonType, typename CompatibleArrayType>
+    static void construct_moving(BasicJsonType& j, CompatibleArrayType& arr)
+    {
+        using std::begin;
+        using std::end;
+
+        const typename BasicJsonType::json_value value(j.template create<typename BasicJsonType::array_t>(std::make_move_iterator(begin(arr)), std::make_move_iterator(end(arr))));
+        j.replace_value(value_t::array, value);
+    }
+
     template<typename BasicJsonType>
     static void construct(BasicJsonType& j, const std::vector<bool>& arr)
     {
@@ -217,6 +228,17 @@ struct external_constructor<value_t::object>
         j.replace_value(value_t::object, value);
     }
 
+    /// an rvalue container: move its values
+    template<typename BasicJsonType, typename CompatibleObjectType>
+    static void construct_moving(BasicJsonType& j, CompatibleObjectType& obj)
+    {
+        using std::begin;
+        using std::end;
+
+        const typename BasicJsonType::json_value value(j.template create<typename BasicJsonType::object_t>(std::make_move_iterator(begin(obj)), std::make_move_iterator(end(obj))));
+        j.replace_value(value_t::object, value);
+    }
+
     template < typename BasicJsonType, typename CompatibleObjectType,
                enable_if_t < !std::is_same<CompatibleObjectType, typename BasicJsonType::object_t>::value, int > = 0 >
     static void construct(BasicJsonType& j, const CompatibleObjectType& obj)
@@ -354,6 +376,45 @@ inline void to_json(BasicJsonType& j, const CompatibleArrayType& arr)
     external_constructor<value_t::array>::construct(j, arr);
 }
 
+#if defined(__cpp_lib_char8_t)
+// std::basic_string<char8_t> is converted to a string by a dedicated to_json overload
+template<typename T>
+struct is_u8string : std::false_type {};
+
+template<typename Tr, typename Allocator>
+struct is_u8string<std::basic_string<char8_t, Tr, Allocator>> : std::true_type {};
+#endif
+
+// rvalue containers: their elements are moved instead of copied
+template < typename BasicJsonType, typename CompatibleArrayType,
+           enable_if_t < !std::is_lvalue_reference<CompatibleArrayType>::value
+                         && !std::is_const<CompatibleArrayType>::value
+                         && !std::is_same<CompatibleArrayType, typename BasicJsonType::array_t>::value
+                         && !std::is_same<CompatibleArrayType, std::vector<bool>>::value
+                         && !is_basic_json<CompatibleArrayType>::value
+                         && is_compatible_array_type<BasicJsonType, CompatibleArrayType>::value
+                         && !is_compatible_object_type<BasicJsonType, CompatibleArrayType>::value
+                         && !is_compatible_string_type<BasicJsonType, CompatibleArrayType>::value
+                         && !std::is_same<typename BasicJsonType::binary_t, CompatibleArrayType>::value
+                         && !is_compatible_binary_type<BasicJsonType, CompatibleArrayType>::value
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
+    && !std::is_same<CompatibleArrayType, std_fs::path>::value // has its own to_json
+#endif
+#if defined(__cpp_lib_char8_t)
+    && !is_u8string<CompatibleArrayType>::value // has its own to_json
+#endif
+#if JSON_HAS_RANGE_VIEW_CONVERSION
+    && !is_compatible_range_view<CompatibleArrayType>::value
+#endif
+#if JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+    && !is_enum_keyed_map<CompatibleArrayType>::value
+#endif
+                         , int > = 0 >
+inline void to_json(BasicJsonType& j, CompatibleArrayType && arr)
+{
+    external_constructor<value_t::array>::construct_moving(j, arr);
+}
+
 #if JSON_HAS_RANGE_VIEW_CONVERSION
 template < typename BasicJsonType, typename T,
            enable_if_t < is_compatible_range_view<std::remove_cvref_t<T>>::value
@@ -427,6 +488,21 @@ inline void to_json(BasicJsonType& j, const EnumKeyedMap& map)
 }
 #endif
 
+template < typename BasicJsonType, typename CompatibleObjectType,
+           enable_if_t < !std::is_lvalue_reference<CompatibleObjectType>::value
+                         && !std::is_const<CompatibleObjectType>::value
+                         && !std::is_same<CompatibleObjectType, typename BasicJsonType::object_t>::value
+                         && is_compatible_object_type<BasicJsonType, CompatibleObjectType>::value
+                         && !is_basic_json<CompatibleObjectType>::value
+#if JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+    && !is_enum_keyed_map<CompatibleObjectType>::value
+#endif
+                         , int > = 0 >
+inline void to_json(BasicJsonType& j, CompatibleObjectType && obj)
+{
+    external_constructor<value_t::object>::construct_moving(j, obj);
+}
+
 template<typename BasicJsonType>
 inline void to_json(BasicJsonType& j, typename BasicJsonType::object_t&& obj)
 {

include/nlohmann/detail/json_pointer.hpp

@@ -938,23 +938,6 @@ class json_pointer
     }
 
   private:
-    // Add the entry (key, v) to the object `obj`. Flattened paths are pairwise
-    // distinct, so objects that can append a key known to be absent
-    // (ordered_map) skip the lookup, which is linear and would make flatten
-    // quadratic; all other object types use operator[].
-    template<typename ObjectType, typename ValueType>
-    static auto add_flattened(ObjectType& obj, const string_t& key, ValueType&& v, int /*unused*/)
-    -> decltype(obj.emplace_new_key(key, std::forward<ValueType>(v)), void())
-    {
-        obj.emplace_new_key(key, std::forward<ValueType>(v));
-    }
-
-    template<typename ObjectType, typename ValueType>
-    static void add_flattened(ObjectType& obj, const string_t& key, ValueType&& v, ...)
-    {
-        obj[key] = std::forward<ValueType>(v);
-    }
-
     /*!
     @param[in] reference_string  the reference string to the current value
     @param[in] value             the value to consider
@@ -999,8 +982,7 @@ class json_pointer
 
         // flatten `v`, whose path is `path`: primitives and empty containers
         // are added to the result right away; other containers get a frame
-        auto& object = *result.m_data.m_value.object;
-        const auto enter = [&stack, &path, &object](const BasicJsonType & v)
+        const auto enter = [&stack, &path, &result](const BasicJsonType & v)
         {
             switch (v.type())
             {
@@ -1009,7 +991,7 @@ class json_pointer
                     if (v.m_data.m_value.array->empty())
                     {
                         // flatten empty array as null
-                        add_flattened(object, path, nullptr, 0);
+                        result[path] = nullptr;
                     }
                     else
                     {
@@ -1023,7 +1005,7 @@ class json_pointer
                     if (v.m_data.m_value.object->empty())
                     {
                         // flatten empty object as null
-                        add_flattened(object, path, nullptr, 0);
+                        result[path] = nullptr;
                     }
                     else
                     {
@@ -1043,7 +1025,7 @@ class json_pointer
                 default:
                 {
                     // add a primitive value with its reference string
-                    add_flattened(object, path, v, 0);
+                    result[path] = v;
                     return;
                 }
             }
@@ -1089,10 +1071,6 @@ class json_pointer
                 enter(it->second);
             }
         }
-
-        // the entries were added without going through basic_json, so the
-        // parent pointers (JSON_DIAGNOSTICS) have to be set now
-        result.set_parents();
     }
 
     /*!

include/nlohmann/ordered_map.hpp

@@ -143,17 +143,6 @@ public:
         return {std::prev(this->end()), true};
     }
 
-    /// @brief add an element at the end without checking whether the key exists
-    /// @note The caller must guarantee that @a key is not yet contained, otherwise
-    ///       the container holds duplicate keys. This avoids the linear search of
-    ///       emplace() and operator[] when many keys known to be new are added.
-    template<class V, detail::enable_if_t<
-                 detail::is_constructible<T, V>::value, int> = 0>
-    void emplace_new_key(const key_type& key, V && t)
-    {
-        append(key, std::forward<V>(t));
-    }
-
     T& operator[](const key_type& key)
     {
         return emplace(key, T{}).first->second;

single_include/nlohmann/json.hpp

@@ -7114,6 +7114,17 @@ struct external_constructor<value_t::array>
         j.replace_value(value_t::array, value);
     }
 
+    /// an rvalue container: move its elements
+    template<typename BasicJsonType, typename CompatibleArrayType>
+    static void construct_moving(BasicJsonType& j, CompatibleArrayType& arr)
+    {
+        using std::begin;
+        using std::end;
+
+        const typename BasicJsonType::json_value value(j.template create<typename BasicJsonType::array_t>(std::make_move_iterator(begin(arr)), std::make_move_iterator(end(arr))));
+        j.replace_value(value_t::array, value);
+    }
+
     template<typename BasicJsonType>
     static void construct(BasicJsonType& j, const std::vector<bool>& arr)
     {
@@ -7164,6 +7175,17 @@ struct external_constructor<value_t::object>
         j.replace_value(value_t::object, value);
     }
 
+    /// an rvalue container: move its values
+    template<typename BasicJsonType, typename CompatibleObjectType>
+    static void construct_moving(BasicJsonType& j, CompatibleObjectType& obj)
+    {
+        using std::begin;
+        using std::end;
+
+        const typename BasicJsonType::json_value value(j.template create<typename BasicJsonType::object_t>(std::make_move_iterator(begin(obj)), std::make_move_iterator(end(obj))));
+        j.replace_value(value_t::object, value);
+    }
+
     template < typename BasicJsonType, typename CompatibleObjectType,
                enable_if_t < !std::is_same<CompatibleObjectType, typename BasicJsonType::object_t>::value, int > = 0 >
     static void construct(BasicJsonType& j, const CompatibleObjectType& obj)
@@ -7301,6 +7323,45 @@ inline void to_json(BasicJsonType& j, const CompatibleArrayType& arr)
     external_constructor<value_t::array>::construct(j, arr);
 }
 
+#if defined(__cpp_lib_char8_t)
+// std::basic_string<char8_t> is converted to a string by a dedicated to_json overload
+template<typename T>
+struct is_u8string : std::false_type {};
+
+template<typename Tr, typename Allocator>
+struct is_u8string<std::basic_string<char8_t, Tr, Allocator>> : std::true_type {};
+#endif
+
+// rvalue containers: their elements are moved instead of copied
+template < typename BasicJsonType, typename CompatibleArrayType,
+           enable_if_t < !std::is_lvalue_reference<CompatibleArrayType>::value
+                         && !std::is_const<CompatibleArrayType>::value
+                         && !std::is_same<CompatibleArrayType, typename BasicJsonType::array_t>::value
+                         && !std::is_same<CompatibleArrayType, std::vector<bool>>::value
+                         && !is_basic_json<CompatibleArrayType>::value
+                         && is_compatible_array_type<BasicJsonType, CompatibleArrayType>::value
+                         && !is_compatible_object_type<BasicJsonType, CompatibleArrayType>::value
+                         && !is_compatible_string_type<BasicJsonType, CompatibleArrayType>::value
+                         && !std::is_same<typename BasicJsonType::binary_t, CompatibleArrayType>::value
+                         && !is_compatible_binary_type<BasicJsonType, CompatibleArrayType>::value
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
+    && !std::is_same<CompatibleArrayType, std_fs::path>::value // has its own to_json
+#endif
+#if defined(__cpp_lib_char8_t)
+    && !is_u8string<CompatibleArrayType>::value // has its own to_json
+#endif
+#if JSON_HAS_RANGE_VIEW_CONVERSION
+    && !is_compatible_range_view<CompatibleArrayType>::value
+#endif
+#if JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+    && !is_enum_keyed_map<CompatibleArrayType>::value
+#endif
+                         , int > = 0 >
+inline void to_json(BasicJsonType& j, CompatibleArrayType && arr)
+{
+    external_constructor<value_t::array>::construct_moving(j, arr);
+}
+
 #if JSON_HAS_RANGE_VIEW_CONVERSION
 template < typename BasicJsonType, typename T,
            enable_if_t < is_compatible_range_view<std::remove_cvref_t<T>>::value
@@ -7374,6 +7435,21 @@ inline void to_json(BasicJsonType& j, const EnumKeyedMap& map)
 }
 #endif
 
+template < typename BasicJsonType, typename CompatibleObjectType,
+           enable_if_t < !std::is_lvalue_reference<CompatibleObjectType>::value
+                         && !std::is_const<CompatibleObjectType>::value
+                         && !std::is_same<CompatibleObjectType, typename BasicJsonType::object_t>::value
+                         && is_compatible_object_type<BasicJsonType, CompatibleObjectType>::value
+                         && !is_basic_json<CompatibleObjectType>::value
+#if JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+    && !is_enum_keyed_map<CompatibleObjectType>::value
+#endif
+                         , int > = 0 >
+inline void to_json(BasicJsonType& j, CompatibleObjectType && obj)
+{
+    external_constructor<value_t::object>::construct_moving(j, obj);
+}
+
 template<typename BasicJsonType>
 inline void to_json(BasicJsonType& j, typename BasicJsonType::object_t&& obj)
 {
@@ -21559,23 +21635,6 @@ class json_pointer
     }
 
   private:
-    // Add the entry (key, v) to the object `obj`. Flattened paths are pairwise
-    // distinct, so objects that can append a key known to be absent
-    // (ordered_map) skip the lookup, which is linear and would make flatten
-    // quadratic; all other object types use operator[].
-    template<typename ObjectType, typename ValueType>
-    static auto add_flattened(ObjectType& obj, const string_t& key, ValueType&& v, int /*unused*/)
-    -> decltype(obj.emplace_new_key(key, std::forward<ValueType>(v)), void())
-    {
-        obj.emplace_new_key(key, std::forward<ValueType>(v));
-    }
-
-    template<typename ObjectType, typename ValueType>
-    static void add_flattened(ObjectType& obj, const string_t& key, ValueType&& v, ...)
-    {
-        obj[key] = std::forward<ValueType>(v);
-    }
-
     /*!
     @param[in] reference_string  the reference string to the current value
     @param[in] value             the value to consider
@@ -21620,8 +21679,7 @@ class json_pointer
 
         // flatten `v`, whose path is `path`: primitives and empty containers
         // are added to the result right away; other containers get a frame
-        auto& object = *result.m_data.m_value.object;
-        const auto enter = [&stack, &path, &object](const BasicJsonType & v)
+        const auto enter = [&stack, &path, &result](const BasicJsonType & v)
         {
             switch (v.type())
             {
@@ -21630,7 +21688,7 @@ class json_pointer
                     if (v.m_data.m_value.array->empty())
                     {
                         // flatten empty array as null
-                        add_flattened(object, path, nullptr, 0);
+                        result[path] = nullptr;
                     }
                     else
                     {
@@ -21644,7 +21702,7 @@ class json_pointer
                     if (v.m_data.m_value.object->empty())
                     {
                         // flatten empty object as null
-                        add_flattened(object, path, nullptr, 0);
+                        result[path] = nullptr;
                     }
                     else
                     {
@@ -21664,7 +21722,7 @@ class json_pointer
                 default:
                 {
                     // add a primitive value with its reference string
-                    add_flattened(object, path, v, 0);
+                    result[path] = v;
                     return;
                 }
             }
@@ -21710,10 +21768,6 @@ class json_pointer
                 enter(it->second);
             }
         }
-
-        // the entries were added without going through basic_json, so the
-        // parent pointers (JSON_DIAGNOSTICS) have to be set now
-        result.set_parents();
     }
 
     /*!
@@ -29180,17 +29234,6 @@ public:
         return {std::prev(this->end()), true};
     }
 
-    /// @brief add an element at the end without checking whether the key exists
-    /// @note The caller must guarantee that @a key is not yet contained, otherwise
-    ///       the container holds duplicate keys. This avoids the linear search of
-    ///       emplace() and operator[] when many keys known to be new are added.
-    template<class V, detail::enable_if_t<
-                 detail::is_constructible<T, V>::value, int> = 0>
-    void emplace_new_key(const key_type& key, V && t)
-    {
-        append(key, std::forward<V>(t));
-    }
-
     T& operator[](const key_type& key)
     {
         return emplace(key, T{}).first->second;

tests/src/unit-json_pointer.cpp

@@ -24,8 +24,6 @@ using nlohmann::json;
 #endif
 
 #include <map>
-#include <string>
-#include <vector>
 #include <sstream>
 
 TEST_CASE("JSON pointers")
@@ -1073,53 +1071,3 @@ TEST_CASE("flatten of structured values")
               R"({"/z":"s","/a~1b/~0":1,"/a~1b/k":null,"/a/0":1,"/a/1/c":null,"/a/1/b":null,"/a/2/0/x~0~1/0":true,"/a/2/0/x~0~1/1":null,"/a/2/0/w":2})");
     }
 }
-
-TEST_CASE("flatten of ordered_json")
-{
-    using nlohmann::ordered_json;
-
-    SECTION("keeps the document order of the leaves")
-    {
-        const ordered_json j = ordered_json::parse(R"({
-            "z": 1, "a": {"y": [true, null, {}], "b": "x", "": []},
-            "m~n": 2.5, "o/p": {"k": {}}, "0": [[1], [2, 3]]
-        })");
-
-        const ordered_json flat = j.flatten();
-        std::vector<std::string> keys;
-        for (const auto& el : flat.items())
-        {
-            keys.push_back(el.key());
-        }
-        const std::vector<std::string> expected =
-        {
-            "/z", "/a/y/0", "/a/y/1", "/a/y/2", "/a/b", "/a/", "/m~0n", "/o~1p/k", "/0/0/0", "/0/1/0", "/0/1/1"
-        };
-        CHECK(keys == expected);
-        CHECK(flat.size() == expected.size());
-        CHECK(flat["/m~0n"] == 2.5);
-        CHECK(flat["/a/y/2"].is_null());
-    }
-
-    SECTION("round-trips and agrees with json")
-    {
-        ordered_json j;
-        for (int i = 0; i < 200; ++i)
-        {
-            j["k" + std::to_string(i)] = {{"v", i}, {"l", {i, i + 1, "s"}}};
-        }
-        const ordered_json flat = j.flatten();
-        CHECK(flat.size() == 800);
-        CHECK(flat.unflatten() == j);
-
-        // same entries as for a sorted object
-        const nlohmann::json plain = nlohmann::json::parse(j.dump());
-        CHECK(nlohmann::json::parse(flat.dump()) == plain.flatten());
-    }
-
-    SECTION("primitive and empty root")
-    {
-        CHECK(ordered_json(1).flatten() == ordered_json({{"", 1}}));
-        CHECK(ordered_json::array().flatten() == ordered_json({{"", nullptr}}));
-    }
-}

tests/src/unit-to_json-rvalue.cpp

@@ -0,0 +1,257 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#include "doctest_compatibility.h"
+
+#include <nlohmann/json.hpp>
+using nlohmann::json;
+
+#include <array>
+#include <deque>
+#include <forward_list>
+#include <list>
+#include <map>
+#include <set>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <valarray>
+#include <vector>
+
+#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_HAS_CXX17) && _HAS_CXX17 == 1)
+    #if __has_include(<filesystem>)
+        #include <filesystem>
+        #define TO_JSON_RVALUE_HAS_FS 1
+    #endif
+#endif
+
+namespace
+{
+// element type that counts how it is converted to JSON: a conversion from an
+// lvalue copies, a conversion from an rvalue moves
+struct tracked
+{
+    std::string payload;
+    bool moved_from = false;
+
+    explicit tracked(std::string p) : payload(std::move(p)) {}
+    tracked(const tracked&) = default;
+    tracked& operator=(const tracked&) = default;
+    tracked(tracked&& other) noexcept : payload(std::move(other.payload)), moved_from(other.moved_from)
+    {
+        other.moved_from = true;
+    }
+    tracked& operator=(tracked&& other) noexcept
+    {
+        payload = std::move(other.payload);
+        moved_from = other.moved_from;
+        other.moved_from = true;
+        return *this;
+    }
+    ~tracked() = default;
+};
+
+int tracked_copies = 0; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables,misc-use-internal-linkage)
+int tracked_moves = 0;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables,misc-use-internal-linkage)
+
+void to_json(json& j, const tracked& t)
+{
+    ++tracked_copies;
+    j = t.payload;
+}
+
+void to_json(json& j, tracked&& t)
+{
+    ++tracked_moves;
+    j = std::move(t.payload);
+    t.moved_from = true;
+}
+
+// user type with its own rvalue-aware serializer
+struct udt_container
+{
+    std::vector<int> values;
+};
+} // namespace
+
+namespace nlohmann
+{
+template<>
+struct adl_serializer<udt_container>
+{
+    static void to_json(json& j, const udt_container& c)
+    {
+        j = c.values;
+        j.push_back("copied");
+    }
+    static void to_json(json& j, udt_container&& c)
+    {
+        j = std::move(c.values);
+        j.push_back("moved");
+    }
+};
+} // namespace nlohmann
+
+TEST_CASE("to_json from rvalue containers")
+{
+    const std::string long_a(64, 'a');
+    const std::string long_b(64, 'b');
+
+    SECTION("vector<std::string>: elements are moved")
+    {
+        std::vector<std::string> v{long_a, long_b};
+        const json j = std::move(v);
+        CHECK(j == json::array({long_a, long_b}));
+        for (const auto& s : v) // NOLINT(bugprone-use-after-move,hicpp-invalid-access-moved)
+        {
+            CHECK(s.empty()); // long strings leave the source element empty when moved
+        }
+    }
+
+    SECTION("vector<std::string>: lvalues are copied and left untouched")
+    {
+        const std::vector<std::string> v{long_a, long_b};
+        const json j = v;
+        CHECK(j == json::array({long_a, long_b}));
+        CHECK(v[0] == long_a);
+        CHECK(v[1] == long_b);
+
+        std::vector<std::string> v2{long_a, long_b};
+        const json j2 = v2;
+        CHECK(j2 == j);
+        CHECK(v2[0] == long_a);
+        CHECK(v2[1] == long_b);
+    }
+
+    SECTION("tracked elements: rvalue moves, lvalue copies")
+    {
+        tracked_copies = 0;
+        tracked_moves = 0;
+
+        std::vector<tracked> v;
+        v.emplace_back("x");
+        v.emplace_back("y");
+
+        const json copy = v;
+        CHECK(copy == json::array({"x", "y"}));
+        CHECK(tracked_copies == 2);
+        CHECK(tracked_moves == 0);
+        CHECK_FALSE(v[0].moved_from);
+
+        const json moved = std::move(v);
+        CHECK(moved == copy);
+        CHECK(tracked_copies == 2);
+        CHECK(tracked_moves == 2);
+    }
+
+    SECTION("const rvalue is copied")
+    {
+        tracked_copies = 0;
+        tracked_moves = 0;
+        const std::vector<tracked> v(2, tracked("z"));
+        const json j = std::move(v); // NOLINT(performance-move-const-arg,hicpp-move-const-arg)
+        CHECK(j == json::array({"z", "z"}));
+        CHECK(tracked_copies == 2);
+        CHECK(tracked_moves == 0);
+    }
+
+    SECTION("other sequence containers")
+    {
+        CHECK(json(std::deque<std::string> {long_a, long_b}) == json::array({long_a, long_b}));
+        CHECK(json(std::list<std::string> {long_a, long_b}) == json::array({long_a, long_b}));
+        CHECK(json(std::forward_list<std::string> {long_a, long_b}) == json::array({long_a, long_b}));
+        CHECK(json(std::array<std::string, 2> {{long_a, long_b}}) == json::array({long_a, long_b}));
+        CHECK(json(std::set<std::string> {long_a, long_b}) == json::array({long_a, long_b}));
+        CHECK(json(std::vector<bool> {true, false}) == json::array({true, false}));
+        CHECK(json(std::vector<int> {1, 2, 3}) == json::array({1, 2, 3}));
+        CHECK(json(std::vector<std::vector<std::string>> {{long_a}, {long_b}}) == json::array({json::array({long_a}), json::array({long_b})}));
+        CHECK(json(std::vector<json> {1, "a"}) == json::array({1, "a"}));
+    }
+
+    SECTION("valarray")
+    {
+        std::valarray<int> va(3);
+        va[0] = 1;
+        va[1] = 2;
+        va[2] = 3;
+        CHECK(json(std::move(va)) == json::array({1, 2, 3})); // NOLINT(performance-move-const-arg,hicpp-move-const-arg)
+        CHECK(json(std::valarray<int>(2)) == json::array({0, 0}));
+    }
+
+    SECTION("array_t and json arrays")
+    {
+        json::array_t arr{1, 2};
+        CHECK(json(std::move(arr)) == json::array({1, 2}));
+        json a = json::array({1, 2});
+        const json b = std::move(a);
+        CHECK(b == json::array({1, 2}));
+    }
+
+    SECTION("object-like containers")
+    {
+        std::map<std::string, std::string> m{{"a", long_a}, {"b", long_b}};
+        const json j = std::move(m);
+        CHECK(j == json({{"a", long_a}, {"b", long_b}}));
+        for (const auto& kv : m) // NOLINT(bugprone-use-after-move,hicpp-invalid-access-moved)
+        {
+            CHECK(kv.second.empty()); // values moved, keys (const) copied
+        }
+
+        const std::map<std::string, std::string> cm{{"a", long_a}};
+        const json jc = cm;
+        CHECK(jc["a"] == long_a);
+        CHECK(cm.at("a") == long_a);
+
+        std::unordered_map<std::string, std::string> um{{"a", long_a}};
+        CHECK(json(std::move(um)) == json({{"a", long_a}}));
+
+        std::multimap<std::string, int> mm{{"a", 1}};
+        CHECK(json(std::move(mm)) == json({{"a", 1}}));
+
+        tracked_copies = 0;
+        tracked_moves = 0;
+        std::map<std::string, tracked> mt;
+        mt.emplace("k", tracked("v"));
+        const json jt = std::move(mt);
+        CHECK(jt == json({{"k", "v"}}));
+        CHECK(tracked_moves == 1);
+        CHECK(tracked_copies == 0);
+
+        json::object_t obj{{"a", 1}};
+        CHECK(json(std::move(obj)) == json({{"a", 1}}));
+    }
+
+    SECTION("user type with its own to_json overloads")
+    {
+        udt_container c{{1, 2}};
+        const json lv = c;
+        CHECK(lv == json::array({1, 2, "copied"}));
+        const json rv = std::move(c);
+        CHECK(rv == json::array({1, 2, "moved"}));
+    }
+
+    SECTION("assignment and implicit conversion")
+    {
+        std::vector<std::string> v{long_a};
+        json j;
+        j = std::move(v);
+        CHECK(j == json::array({long_a}));
+        json k = {std::vector<std::string>{long_b}};
+        CHECK(k.size() == 1);
+    }
+
+#ifdef TO_JSON_RVALUE_HAS_FS
+    SECTION("std::filesystem::path rvalue is still a string")
+    {
+        CHECK(json(std::filesystem::path("a/b")) == json("a/b"));
+#ifdef __cpp_lib_char8_t
+        CHECK(json(std::u8string(u8"a/b")) == json("a/b"));
+#endif
+    }
+#endif
+}