Address review findings on the binary writer output sinks

- binary_reserve_hint(): the 4-bytes-per-element estimate over-reserved by up
  to 4x for arrays of small scalars (CBOR encodes 0..23 in one byte), and the
  returned vector kept that capacity. Make the hint a strict lower bound on the
  encoded size instead, which also removes the 1 MiB clamp whose branch no test
  could reach (the largest container in the suite has 65793 elements).

- Guard the -Wduplicated-branches pragma with __GNUC__ >= 7. The warning does
  not exist before GCC 7, so naming it made GCC 4.8/4.9/5/6 - which the CI
  matrix still builds - warn under -Wpragmas on every including translation
  unit, breaking downstream -Werror builds.

- Constrain the adapter constructor of binary_writer with the enable_if its
  documentation already claimed, so a writer over some other sink type is no
  longer advertised as constructible from an output adapter.

- Let output_vector_adapter wrap output_vector_sink rather than duplicating the
  append logic, so the type-erased and templated paths share one implementation.

- Collapse the three copies of the memcpy/byte_swap/memcpy dance into a single
  byte_swap_buffer() helper, and add the MSVC _byteswap_* intrinsics so MSVC no
  longer falls back to the scalar shuffle this change exists to eliminate.

- Add a vector_writer() helper for the five vector-returning to_* overloads
  instead of spelling out the writer type at each call site, and drop a dead
  default member initializer on output_adapter_sink.

- New tests: the vector sink and the adapter sink must produce identical bytes
  for every format (the two to_* overloads no longer delegate to each other and
  could otherwise drift), and binary_reserve_hint() must never exceed the size
  actually written.

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

docs/mkdocs/requirements.txt

@@ -1,4 +1,4 @@
-wheel==0.48.0
+wheel==0.47.0
 
 mkdocs==1.6.1                                       # documentation framework
 mkdocs-git-revision-date-localized-plugin==1.5.3    # plugin "git-revision-date-localized"

include/nlohmann/detail/output/output_adapters.hpp

@@ -13,6 +13,7 @@
 #include <iterator> // back_inserter
 #include <memory> // shared_ptr, make_shared
 #include <string> // basic_string
+#include <utility> // move
 #include <vector> // vector
 
 #ifndef JSON_NO_IO
@@ -44,22 +45,32 @@ template<typename CharType> struct output_adapter_protocol
 template<typename CharType>
 using output_adapter_t = std::shared_ptr<output_adapter_protocol<CharType>>;
 
-/// output adapter for byte vectors
+/// @brief non-virtual output sink writing into a std::vector
+///
+/// This sink is not part of the virtual output_adapter_protocol hierarchy: it is
+/// passed to binary_writer by value as a template parameter, so
+/// write_character()/write_characters() are ordinary (inlinable) calls with no
+/// vtable lookup and no shared_ptr. It is used for the common
+/// `to_cbor`/`to_msgpack`/... into a std::vector. output_vector_adapter below
+/// wraps this same sink to provide the virtual interface.
 template<typename CharType, typename AllocatorType = std::allocator<CharType>>
-class output_vector_adapter : public output_adapter_protocol<CharType>
+class output_vector_sink
 {
   public:
-    explicit output_vector_adapter(std::vector<CharType, AllocatorType>& vec) noexcept
+    explicit output_vector_sink(std::vector<CharType, AllocatorType>& vec) noexcept
         : v(vec)
     {}
 
-    void write_character(CharType c) override
+    void write_character(CharType c)
     {
         v.push_back(c);
     }
 
-    JSON_HEDLEY_NON_NULL(2)
-    void write_characters(const CharType* s, std::size_t length) override
+    // no JSON_HEDLEY_NON_NULL here: binary_writer legitimately passes a null
+    // pointer with length 0 for empty strings/binary values. Appending an empty
+    // range is a no-op; the type-erased path tolerates this via the (unattributed)
+    // virtual base, and the concrete sink must do the same.
+    void write_characters(const CharType* s, std::size_t length)
     {
         v.insert(v.end(), s, s + length);
     }
@@ -68,6 +79,34 @@ class output_vector_adapter : public output_adapter_protocol<CharType>
     std::vector<CharType, AllocatorType>& v;
 };
 
+/// output adapter for byte vectors
+///
+/// The appending itself lives in output_vector_sink; this class only adds the
+/// virtual output_adapter_protocol interface on top of it, so both the
+/// type-erased and the templated path share one implementation.
+template<typename CharType, typename AllocatorType = std::allocator<CharType>>
+class output_vector_adapter : public output_adapter_protocol<CharType>
+{
+  public:
+    explicit output_vector_adapter(std::vector<CharType, AllocatorType>& vec) noexcept
+        : sink(vec)
+    {}
+
+    void write_character(CharType c) override
+    {
+        sink.write_character(c);
+    }
+
+    JSON_HEDLEY_NON_NULL(2)
+    void write_characters(const CharType* s, std::size_t length) override
+    {
+        sink.write_characters(s, length);
+    }
+
+  private:
+    output_vector_sink<CharType, AllocatorType> sink;
+};
+
 #ifndef JSON_NO_IO
 /// output adapter for output streams
 template<typename CharType>
@@ -118,6 +157,39 @@ class output_string_adapter : public output_adapter_protocol<CharType>
     StringType& str;
 };
 
+/// @brief output sink forwarding to a type-erased output adapter
+///
+/// Wraps the polymorphic output_adapter_t so the same binary_writer template can
+/// also target arbitrary adapters (output streams, strings, user-provided
+/// adapters) via the `output_adapter`-based overloads. Each write still goes
+/// through one virtual call, exactly as before; only the concrete sinks above
+/// avoid it.
+template<typename CharType>
+class output_adapter_sink
+{
+  public:
+    explicit output_adapter_sink(output_adapter_t<CharType> adapter)
+        : oa(std::move(adapter))
+    {
+        JSON_ASSERT(oa);
+    }
+
+    void write_character(CharType c)
+    {
+        oa->write_character(c);
+    }
+
+    // no JSON_HEDLEY_NON_NULL: forwards (null, 0) for empty payloads, exactly as
+    // the type-erased path already did before this sink existed
+    void write_characters(const CharType* s, std::size_t length)
+    {
+        oa->write_characters(s, length);
+    }
+
+  private:
+    output_adapter_t<CharType> oa;
+};
+
 template<typename CharType, typename StringType = std::basic_string<CharType>>
 class output_adapter
 {

include/nlohmann/json.hpp

@@ -140,7 +140,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     friend ::nlohmann::detail::serializer<basic_json>;
     template<typename BasicJsonType>
     friend class ::nlohmann::detail::iter_impl;
-    template<typename BasicJsonType, typename CharType>
+    template<typename BasicJsonType, typename CharType, typename OutputSinkType>
     friend class ::nlohmann::detail::binary_writer;
     template<typename BasicJsonType, typename InputType, typename SAX>
     friend class ::nlohmann::detail::binary_reader;
@@ -187,6 +187,14 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     template<typename InputType>
     using binary_reader = ::nlohmann::detail::binary_reader<basic_json, InputType>;
     template<typename CharType> using binary_writer = ::nlohmann::detail::binary_writer<basic_json, CharType>;
+    // binary_writer over a concrete (non-virtual) sink appending into a std::vector,
+    // used by the vector-returning to_* overloads
+    template<typename CharType> using vector_binary_writer =
+        ::nlohmann::detail::binary_writer<basic_json, CharType, ::nlohmann::detail::output_vector_sink<CharType>>;
+    template<typename CharType> static vector_binary_writer<CharType> vector_writer(std::vector<CharType>& v)
+    {
+        return vector_binary_writer<CharType>(::nlohmann::detail::output_vector_sink<CharType>(v));
+    }
 
   JSON_PRIVATE_UNLESS_TESTED:
     using serializer = ::nlohmann::detail::serializer<basic_json>;
@@ -4337,7 +4345,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     static std::vector<std::uint8_t> to_cbor(const basic_json& j)
     {
         std::vector<std::uint8_t> result;
-        to_cbor(j, result);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_cbor(j);
         return result;
     }
 
@@ -4360,7 +4369,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     static std::vector<std::uint8_t> to_msgpack(const basic_json& j)
     {
         std::vector<std::uint8_t> result;
-        to_msgpack(j, result);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_msgpack(j);
         return result;
     }
 
@@ -4385,7 +4395,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
             const bool use_type = false)
     {
         std::vector<std::uint8_t> result;
-        to_ubjson(j, result, use_size, use_type);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_ubjson(j, use_size, use_type);
         return result;
     }
 
@@ -4413,7 +4424,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
             const bjdata_version_t version = bjdata_version_t::draft2)
     {
         std::vector<std::uint8_t> result;
-        to_bjdata(j, result, use_size, use_type, version);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_ubjson(j, use_size, use_type, true, true, version);
         return result;
     }
 
@@ -4440,7 +4452,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     static std::vector<std::uint8_t> to_bson(const basic_json& j)
     {
         std::vector<std::uint8_t> result;
-        to_bson(j, result);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_bson(j);
         return result;
     }
 

tests/src/unit-binary_writer_sinks.cpp

@@ -0,0 +1,198 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  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 <cstdint>
+#include <string>
+#include <vector>
+
+namespace
+{
+
+// a spread of values exercising every writer path: scalars of each width, the
+// float paths, strings, binary, and containers big enough to reallocate
+std::vector<json> test_values()
+{
+    json big_array = json::array();
+    for (int i = 0; i < 5000; ++i)
+    {
+        big_array.push_back(i);
+    }
+
+    json big_object = json::object();
+    for (int i = 0; i < 1000; ++i)
+    {
+        big_object[std::to_string(i)] = i;
+    }
+
+    return
+    {
+        json(nullptr), json(true), json(false),
+        json(0), json(-1), json(255), json(-129), json(65535), json(-32769),
+        json(4294967295U), json(-2147483649LL), json(18446744073709551615ULL),
+        json(0.0), json(-0.5), json(3.1415926535897932),
+        json(""), json("hello"), json(std::string(1000, 'x')),
+        json::binary({0x00, 0x01, 0x02}, 42),
+        json::array(), json::object(),
+        json::array({1, 2, 3}), json({{"a", 1}, {"b", nullptr}}),
+        json({{"nested", {{"deep", json::array({1, "two", 3.0, nullptr})}}}}),
+        big_array, big_object
+    };
+}
+
+// values to_bson() accepts: the document must be an object
+std::vector<json> bson_values()
+{
+    json big_object = json::object();
+    for (int i = 0; i < 1000; ++i)
+    {
+        big_object[std::to_string(i)] = i;
+    }
+
+    return
+    {
+        json::object(),
+        json({{"a", 1}, {"b", nullptr}, {"c", true}, {"d", 2.5}, {"e", "text"}}),
+        json({{"arr", json::array({1, 2, 3})}, {"obj", {{"k", "v"}}}}),
+        big_object
+    };
+}
+
+} // namespace
+
+// The vector-returning to_*(j) overloads write through the non-virtual
+// output_vector_sink, while to_*(j, adapter) goes through output_adapter_sink.
+// The two are separate code paths that must stay byte-for-byte identical; these
+// checks fail if either overload is ever changed without the other.
+TEST_CASE("binary writer output sinks")
+{
+    SECTION("vector sink and adapter sink agree")
+    {
+        // note: no SUBCASE inside these loops - doctest keys subcases by
+        // name/file/line, so a subcase in a loop body would only ever run for
+        // the first iteration
+        for (const auto& j : test_values())
+        {
+            CAPTURE(j.dump(-1, ' ', false, json::error_handler_t::replace));
+
+            std::vector<std::uint8_t> cbor;
+            json::to_cbor(j, cbor);
+            CHECK(json::to_cbor(j) == cbor);
+
+            std::vector<std::uint8_t> msgpack;
+            json::to_msgpack(j, msgpack);
+            CHECK(json::to_msgpack(j) == msgpack);
+
+            for (const bool use_size :
+                    {
+                        false, true
+                    })
+            {
+                for (const bool use_type :
+                        {
+                            false, true
+                        })
+                {
+                    if (use_type && !use_size)
+                    {
+                        continue; // not a supported combination
+                    }
+                    CAPTURE(use_size);
+                    CAPTURE(use_type);
+                    std::vector<std::uint8_t> ubjson;
+                    json::to_ubjson(j, ubjson, use_size, use_type);
+                    CHECK(json::to_ubjson(j, use_size, use_type) == ubjson);
+                }
+            }
+
+            for (const auto version :
+                    {
+                        json::bjdata_version_t::draft2, json::bjdata_version_t::draft3
+                    })
+            {
+                std::vector<std::uint8_t> bjdata;
+                json::to_bjdata(j, bjdata, false, false, version);
+                CHECK(json::to_bjdata(j, false, false, version) == bjdata);
+            }
+        }
+
+        for (const auto& j : bson_values())
+        {
+            CAPTURE(j.dump());
+            std::vector<std::uint8_t> bson;
+            json::to_bson(j, bson);
+            CHECK(json::to_bson(j) == bson);
+        }
+    }
+
+    SECTION("the char adapter produces the same bytes")
+    {
+        for (const auto& j : test_values())
+        {
+            CAPTURE(j.dump(-1, ' ', false, json::error_handler_t::replace));
+
+            const std::vector<std::uint8_t> expected = json::to_cbor(j);
+            std::vector<char> as_char;
+            json::to_cbor(j, as_char);
+
+            REQUIRE(as_char.size() == expected.size());
+            std::vector<std::uint8_t> as_bytes;
+            as_bytes.reserve(as_char.size());
+            for (const char c : as_char)
+            {
+                as_bytes.push_back(static_cast<std::uint8_t>(c));
+            }
+            CHECK(as_bytes == expected);
+        }
+    }
+}
+
+// binary_reserve_hint() is documented as a *lower* bound on the serialized size,
+// so that reserving it up front can never leave the returned vector holding
+// capacity beyond what the value actually needs.
+TEST_CASE("binary_reserve_hint never over-reserves")
+{
+    for (const auto& j : test_values())
+    {
+        CAPTURE(j.dump(-1, ' ', false, json::error_handler_t::replace));
+
+        const std::size_t hint = nlohmann::detail::binary_reserve_hint(j);
+
+        CHECK(hint <= json::to_cbor(j).size());
+        CHECK(hint <= json::to_msgpack(j).size());
+        CHECK(hint <= json::to_ubjson(j).size());
+        CHECK(hint <= json::to_ubjson(j, true, true).size());
+        CHECK(hint <= json::to_bjdata(j).size());
+    }
+
+    for (const auto& j : bson_values())
+    {
+        CAPTURE(j.dump());
+        CHECK(nlohmann::detail::binary_reserve_hint(j) <= json::to_bson(j).size());
+    }
+
+    SECTION("scalars get no hint")
+    {
+        CHECK(nlohmann::detail::binary_reserve_hint(json(nullptr)) == 0);
+        CHECK(nlohmann::detail::binary_reserve_hint(json(42)) == 0);
+        CHECK(nlohmann::detail::binary_reserve_hint(json("a string")) == 0);
+        CHECK(nlohmann::detail::binary_reserve_hint(json::binary({0x01})) == 0);
+    }
+
+    SECTION("containers are hinted from their element count")
+    {
+        CHECK(nlohmann::detail::binary_reserve_hint(json::array()) == 1);
+        CHECK(nlohmann::detail::binary_reserve_hint(json::array({1, 2, 3})) == 4);
+        CHECK(nlohmann::detail::binary_reserve_hint(json::object()) == 1);
+        CHECK(nlohmann::detail::binary_reserve_hint(json({{"a", 1}, {"b", 2}})) == 5);
+    }
+}